flowchart TD
Start[("Markdown Source Files
(*.md)")]:::inputNode
Config[("mkdocs.yml
Configuration")]:::inputNode
Parser["MkDocs Parser"]:::processNode
Plugins["Plugin Pipeline"]:::processNode
Theme["Theme Template Engine
(Jinja2)"]:::processNode
HTML["HTML Generation"]:::processNode
Assets[("Static Assets
CSS, JS, Images")]:::inputNode
Output[("site/ Directory
Complete Static Site")]:::outputNode
Start --> Parser
Config --> Parser
Parser --> Plugins
Plugins --> Theme
Theme --> HTML
Assets --> HTML
HTML --> Output
classDef inputNode fill:#4facfe,stroke:#333,stroke-width:3px,color:#fff,font-size:16px
classDef processNode fill:#43aa8b,stroke:#333,stroke-width:2px,color:#fff,font-size:16px
classDef outputNode fill:#f77f00,stroke:#333,stroke-width:3px,color:#fff,font-size:16px
linkStyle default stroke:#999,stroke-width:2px,font-size:14px
Build Pipeline Overview
MkDocs transforms markdown files into a complete static website through a multi-stage pipeline. This workflow shows the journey from source content to deployed HTML.
Pipeline Stages
- Markdown Source Files - Chapter content written in .md format with frontmatter and extensions
- Configuration (mkdocs.yml) - Site settings including theme, navigation, plugins, and extensions
- MkDocs Parser - Reads markdown and parses into abstract syntax trees (AST)
- Plugin Pipeline - Transforms content through plugins (search index, macros, minification, etc.)
- Theme Template Engine - Applies Jinja2 templates from selected theme (Material, ReadTheDocs, etc.)
- HTML Generation - Converts markdown AST to semantic HTML5 with theme styling
- Static Assets - CSS, JavaScript, images, and fonts copied to build directory
- site/ Directory - Complete static website ready for deployment to web server or CDN
Build Commands
mkdocs build - Creates production build in site/ directory
mkdocs serve - Starts development server with auto-reload on file changes
mkdocs gh-deploy - Builds and deploys to GitHub Pages