Documentation Sites¶

Version: 1.0.0 Extends: General / Core Template: template-mkdocs

Standards for building documentation sites using MkDocs with Material theme. Includes structure, configuration, and deployment best practices.

When to Use¶

• Project documentation that needs a professional web interface
• API documentation with code examples
• Technical guides and tutorials
• Internal knowledge bases
• Documentation that benefits from diagrams and visual aids
• Technical blogs or combined documentation + blog sites

When Not to Use¶

• Simple READMEs that don't need a full site
• Documentation that will only live in a repository
• Non-technical content better suited for wikis or CMS platforms

Choosing the Right Tool¶

MkDocs + Material is the recommended choice for Python teams. For other scenarios, consider these alternatives:

Core Stack¶

Plugins¶

Blog Plugin¶

For sites that combine documentation with a blog, Material for MkDocs includes a built-in blog plugin. This enables publishing articles with categories, tags, and archive pages alongside technical documentation.

Diagrams¶

Mermaid enables creating diagrams directly in Markdown. Supported types include flowcharts, sequence diagrams, class diagrams, ERDs, state diagrams, and Gantt charts. See the Mermaid documentation for syntax and examples.

Material for MkDocs has built-in Mermaid support that requires no additional plugins.

Icons¶

Material for MkDocs includes several icon sets that can be used inline or in components:

See the Material Icons Reference for usage details.

Best Practices¶

• Navigation: Use mkdocs-awesome-pages with .pages files for flexible navigation instead of hardcoding everything in mkdocs.yml
• Assets: Store images in docs/assets/images/ and reference them with relative paths
• Admonitions: Use sparingly for genuinely important callouts; overuse reduces their effectiveness
• Code blocks: Always specify the language for proper syntax highlighting
• Links: Prefer relative links between docs to avoid broken links when URLs change
• Redirects: When renaming or moving pages, always add redirects to preserve existing links

Hosting¶

Common deployment options for MkDocs sites:

Advanced Features¶