Implementation:Treeverse LakeFS MkDocs Site Configuration

Knowledge Sources	Treeverse_LakeFS
Domains	Documentation, Configuration, Site Generation
Last Updated	2026-02-08 00:00 GMT

Overview

This MkDocs configuration file defines the build settings, Material theme, navigation structure, Markdown extensions, and plugins for the lakeFS documentation site hosted at docs.lakefs.io.

Description

The mkdocs.yml file is the central configuration for the lakeFS documentation site, built with MkDocs and the Material for MkDocs theme. It resides in the docs/ directory and controls all aspects of the documentation build process.

Site Settings:

site_name: lakeFS Documentation
site_url: https://docs.lakefs.io/
repo_url: https://github.com/treeverse/lakeFS (displayed as treeverse/lakeFS)
site_description: Open Source Data Version Control for Data Lakes and Lakehouses
dev_addr: 127.0.0.1:4000 (local development server)
docs_dir: src (source files directory)
site_dir: site (build output directory)
use_directory_urls: true

Material Theme Configuration:

Uses the material theme with a custom logo (assets/logo.svg) and favicon
Custom overrides directory for template extensions
Features include: footnote tooltips, code copy buttons, content tabs linking, content tooltips, search suggestions, and search sharing
Color palette: white primary with teal accent
GitHub repository icon via FontAwesome

Extra Configuration:

Version management via mike provider with latest as default alias
Status badges for: New, Enterprise Feature, Deprecated Feature, Experimental Feature
Configurable enable_ask_ai feature via environment variable (defaults to true)

Markdown Extensions (17 extensions):

toc -- Table of contents with permalinks and depth of 5
tables, footnotes, fenced_code, attr_list, def_list, admonition, codehilite
pymdownx.highlight -- Syntax highlighting with anchor line numbers
pymdownx.inlinehilite, pymdownx.snippets
pymdownx.emoji -- Emoji support via Material twemoji
pymdownx.superfences -- Mermaid diagram support via custom fences
pymdownx.tabbed -- Tabbed content with alternate style
pymdownx.tasklist -- Task/TODO lists with custom checkboxes
pymdownx.critic, pymdownx.caret, pymdownx.keys, pymdownx.mark, pymdownx.tilde, pymdownx.details

Plugins:

mike -- Version selector for documentation versioning
search -- Built-in search functionality
render_swagger -- Swagger/OpenAPI rendering with arbitrary locations
meta -- Metadata support
glightbox -- Image lightbox
redirects -- URL redirect maps for moved/renamed pages

Navigation Structure: The nav section defines a comprehensive documentation hierarchy with 12 top-level sections: Welcome, Quickstart (7-step guide), Use Cases, User Guides, Data Management, lakeFS Enterprise, Integrations (covering Spark, Iceberg, DuckDB, Databricks, and many more), Concepts, Security (authentication and authorization), Reference, and Community.

Usage

Use this configuration file when building or modifying the lakeFS documentation site. Run mkdocs serve from the docs/ directory for local development on port 4000, or mkdocs build to generate the static site. Modify the nav section to add or reorganize documentation pages, and the markdown_extensions section to enable additional Markdown features.

Code Reference

Source Location

Repository: Treeverse_LakeFS
File: docs/mkdocs.yml

Signature

# MkDocs settings
site_name: lakeFS Documentation
site_url: https://docs.lakefs.io/
repo_url: https://github.com/treeverse/lakeFS
repo_name: treeverse/lakeFS
docs_dir: src
site_dir: site

theme:
  name: material
  logo: assets/logo.svg
  custom_dir: overrides
  features:
    - content.footnote.tooltips
    - content.code.copy
    - content.tabs.link
    - content.tooltips
    - search.suggest
    - search.share

Import

# This file is used by MkDocs at build time:
# mkdocs serve -f docs/mkdocs.yml
# mkdocs build -f docs/mkdocs.yml

I/O Contract

Inputs

Name	Type	Required	Description
site_name	string	Yes	Name displayed in the documentation site header
site_url	string	Yes	Canonical URL for the documentation site
repo_url	string	No	URL to the source repository (displayed as link)
docs_dir	string	Yes	Directory containing source Markdown files (default: src)
site_dir	string	Yes	Directory for built static site output (default: site)
theme.name	string	Yes	MkDocs theme name (material)
nav	list	Yes	Navigation structure defining the sidebar hierarchy
markdown_extensions	list	No	List of Markdown extensions to enable
plugins	list	No	List of MkDocs plugins to load
extra_css	list	No	Additional CSS files to include (e.g., assets/css/overrides.css)
ENABLE_ASK_AI	environment variable	No	Enables the Ask AI feature (defaults to true)

Outputs

Name	Type	Description
site/	directory	Static HTML documentation site generated by mkdocs build
Navigation sidebar	HTML	Rendered sidebar based on the nav configuration
Search index	JSON	Search index generated by the search plugin
Versioned docs	directory	Versioned documentation managed by the mike plugin

Usage Examples

Example

# Serve the documentation locally for development
cd docs/
mkdocs serve
# Documentation available at http://127.0.0.1:4000

# Build the static documentation site
mkdocs build -f docs/mkdocs.yml

# Deploy a versioned release with mike
mike deploy --push --update-aliases 1.0 latest

# Adding a new page to the navigation
nav:
  - Welcome to lakeFS: index.md
  - New Section:
      - Overview: new-section/index.md
      - Getting Started: new-section/getting-started.md

Related Pages

Principle:Treeverse_LakeFS_Documentation_Site_Configuration

Page Connections

Double-click a node to navigate. Hold to expand connections.

Principle

Implementation

Heuristic

Environment