Overview
The MkDocs Material theme configuration file for the Ragas documentation site, defining site metadata, navigation structure, theme settings, Markdown extensions, plugins, and analytics integration.
Description
The mkdocs.yml file is the central configuration for the Ragas documentation site built with MkDocs and the Material for MkDocs theme. It defines the site name, description, URL (loaded from the READTHEDOCS_CANONICAL_URL environment variable), and repository link. The navigation section organizes documentation into five major areas: Get Started (installation, quick start, tutorials), Core Concepts (experimentation, datasets, metrics, test data generation, components), How-to Guides (customizations, applications, CLI, integrations, migrations), References (API docs for core, evaluation, testset generation, integrations), and Community. The theme configuration enables Material features including navigation tabs, instant navigation with prefetch and preview, search suggestions, code copy/annotation, and a three-mode color scheme (auto/light/dark) with a gold accent. Markdown extensions support syntax highlighting, admonitions, tabbed content, emoji, MathJax, Mermaid diagrams, and code snippets. Plugins include search, social cards, copy-to-llm (for ChatGPT/Claude integration), llmstxt (LLM-friendly documentation output), git revision dates, git committers, mkdocstrings (Python API docs with numpy docstring style), and glightbox (image lightbox).
Usage
# Build the documentation site
make build-docs
# Serve documentation locally
make serve-docs
# Or directly with MkDocs
mkdocs build
mkdocs serve
Code Reference
| Field |
Value
|
| Source Location |
mkdocs.yml
|
| Structure |
YAML configuration file with top-level keys: site_name, site_description, site_url, repo_name, repo_url, watch, nav, validation, theme, markdown_extensions, extra_css, extra, plugins, extra_javascript
|
| File Size |
340 lines
|
Data Schema
| Section |
Key Fields |
Description
|
| Site Metadata |
site_name, site_description, site_url, repo_name, repo_url |
Basic site identity; site_url loaded from env var
|
| Navigation |
nav |
Hierarchical menu with five top-level sections: Get Started, Core Concepts, How-to Guides, References, Community
|
| Theme |
theme.name, theme.features, theme.palette |
Material theme with navigation tabs, instant navigation, three-mode color scheme (primary: #bd8526)
|
| Markdown Extensions |
markdown_extensions |
pymdownx.highlight, admonition, pymdownx.tabbed, pymdownx.emoji, pymdownx.arithmatex, pymdownx.superfences (mermaid), pymdownx.snippets
|
| Plugins |
plugins |
search, social, copy-to-llm, llmstxt, git-revision-date-localized, git-committers, mkdocstrings, glightbox
|
| Analytics |
extra.analytics |
Google Analytics via GOOGLE_ANALYTICS_KEY env var
|
| Extra JS |
extra_javascript |
MathJax, header border, toggle, Octolane analytics, Common Room analytics
|
Navigation Structure
| Section |
Contents
|
| Get Started |
Installation, Quick Start, Tutorials (prompt, RAG, workflow, agent evaluation)
|
| Core Concepts |
Experimentation, Datasets, Metrics (RAG, Nvidia, Agents, NL Comparison, SQL, General Purpose, Summarization), Test Data Generation, Components
|
| How-to Guides |
Customizations, Applications, CLI, Integrations (Arize, LangSmith, Bedrock, Gemini, AG-UI, Haystack, LangChain, LlamaIndex, etc.), Migrations
|
| References |
Prompt, LLMs, Embeddings, Tokenizers, RunConfig, Executor, Cache, Optimizers, Schemas, Metrics, evaluate/aevaluate, Testset Generation, Integrations
|
| Community |
Community index page
|
Usage Examples
# Override the site URL for local development
site_url: http://localhost:8000
# Add a new documentation page to the navigation
nav:
- 🚀 Get Started:
- getstarted/index.md
- New Page: getstarted/new_page.md
# Build with environment variable for analytics
GOOGLE_ANALYTICS_KEY=G-XXXXX mkdocs build
# Serve locally with live reload
mkdocs serve --dev-addr 0.0.0.0:8000
Related Pages
