mkdocs

Project documentation with Markdown.

19,243

2,396

19,243

View on GitHub

Top Related Projects

docsify

27,539

🃏 A magical documentation site generator.

vuepress

22,531

📝 Minimalistic Vue-powered static site generator

docusaurus

56,173

Easy to maintain open source documentation websites.

Quick Overview

MkDocs is a fast, simple, and static site generator that's geared towards building project documentation. It uses Markdown to create content and can be easily customized with themes and extensions. MkDocs is particularly popular for creating documentation websites for software projects.

Pros

Easy to set up and use, with a gentle learning curve
Supports Markdown for content creation, making it accessible for non-developers
Highly customizable with themes and plugins
Built-in dev-server for live previewing changes

Cons

Limited built-in features compared to some more complex documentation systems
May require additional plugins for advanced functionality
Not as suitable for large-scale documentation projects with complex structures
Requires Python knowledge for advanced customization and plugin development

Code Examples

Basic configuration in mkdocs.yml:

site_name: My Project Documentation
nav:
  - Home: index.md
  - User Guide: user-guide.md
  - API Reference: api-reference.md
theme: material

Adding a custom CSS file:

extra_css:
  - css/custom.css

Enabling search and navigation features:

plugins:
  - search
  - navigation

markdown_extensions:
  - toc:
      permalink: true

Getting Started

Install MkDocs:

pip install mkdocs

Create a new project:

mkdocs new my-project
cd my-project

Add your Markdown files to the docs directory
Run the development server:

mkdocs serve

Build the static site:

mkdocs build

The static site will be generated in the site directory, ready for deployment.

Competitor Comparisons

mkdocs-material

20,594

Documentation that simply works

Pros of MkDocs Material

Enhanced visual design and customization options
Extensive feature set including search, navigation, and admonitions
Active development and frequent updates

Cons of MkDocs Material

Steeper learning curve due to additional configuration options
Larger file size and potentially slower load times
Some features may require additional setup or plugins

Code Comparison

MkDocs (basic configuration):

site_name: My Docs
theme: readthedocs
nav:
  - Home: index.md
  - About: about.md

MkDocs Material (enhanced configuration):

site_name: My Docs
theme:
  name: material
  palette:
    primary: indigo
    accent: orange
nav:
  - Home: index.md
  - About: about.md

MkDocs Material offers more extensive theming options and features out of the box, while MkDocs provides a simpler, more lightweight approach. The choice between the two depends on project requirements, desired customization level, and performance considerations.

sphinx_rtd_theme

4,767

Sphinx theme from Read the Docs

Pros of sphinx_rtd_theme

More customizable and feature-rich theme for Sphinx documentation
Seamless integration with Read the Docs hosting platform
Supports a wider range of Sphinx extensions and features

Cons of sphinx_rtd_theme

Steeper learning curve compared to MkDocs
Requires more configuration and setup time
Less intuitive for beginners in documentation writing

Code Comparison

sphinx_rtd_theme (conf.py):

import sphinx_rtd_theme

extensions = [
    'sphinx_rtd_theme',
]
html_theme = 'sphinx_rtd_theme'

MkDocs (mkdocs.yml):

theme:
  name: 'material'

The sphinx_rtd_theme requires more configuration in the Sphinx project's conf.py file, while MkDocs uses a simpler YAML configuration. This reflects the overall difference in complexity and flexibility between the two systems.

sphinx_rtd_theme is better suited for large, complex documentation projects with advanced features, while MkDocs excels in simplicity and ease of use for smaller projects or quick documentation setups.

sphinx

6,483

The Sphinx documentation generator

Pros of Sphinx

More powerful and flexible, supporting complex documentation structures
Extensive ecosystem of extensions and themes
Better support for API documentation generation

Cons of Sphinx

Steeper learning curve, especially for non-Python users
More complex configuration and setup process
Slower build times for large documentation projects

Code Comparison

MkDocs configuration (mkdocs.yml):

site_name: My Project
nav:
  - Home: index.md
  - About: about.md
theme: material

Sphinx configuration (conf.py):

project = 'My Project'
extensions = ['sphinx.ext.autodoc', 'sphinx.ext.napoleon']
html_theme = 'alabaster'

MkDocs focuses on simplicity and ease of use, making it ideal for smaller projects or those new to documentation. It uses Markdown by default and has a straightforward configuration.

Sphinx, while more complex, offers greater customization and is better suited for large-scale documentation projects, especially those involving API documentation. It uses reStructuredText by default but can also support Markdown with extensions.

Both tools are popular choices for documentation, with the choice depending on project requirements and user preferences.

docsify

27,539

🃏 A magical documentation site generator.

Pros of Docsify

No build process required; runs entirely in the browser
Simpler setup and configuration compared to MkDocs
Supports plugins and themes without additional installation

Cons of Docsify

Limited static site generation capabilities
Less robust search functionality out of the box
Fewer built-in features for larger documentation projects

Code Comparison

MkDocs configuration (mkdocs.yml):

site_name: My Docs
theme: material
nav:
  - Home: index.md
  - About: about.md

Docsify configuration (index.html):

<!DOCTYPE html>
<html>
<head>
  <meta charset="UTF-8">
  <title>My Docs</title>
</head>
<body>
  <div id="app"></div>
  <script>
    window.$docsify = {
      name: 'My Docs',
      loadSidebar: true
    }
  </script>
  <script src="//cdn.jsdelivr.net/npm/docsify/lib/docsify.min.js"></script>
</body>
</html>

Both MkDocs and Docsify are popular documentation tools, but they cater to different needs. MkDocs is better suited for larger projects requiring static site generation and more advanced features, while Docsify offers a simpler, more lightweight solution for smaller projects or quick documentation setups.

vuepress

22,531

📝 Minimalistic Vue-powered static site generator

Pros of VuePress

Built-in Vue.js integration for dynamic content and custom components
Default theme optimized for documentation sites with features like search and sidebar
Automatic code splitting for better performance

Cons of VuePress

Steeper learning curve, especially for those unfamiliar with Vue.js
More complex setup and configuration compared to MkDocs
Slower build times for large sites due to webpack bundling

Code Comparison

MkDocs configuration (mkdocs.yml):

site_name: My Docs
theme: material
nav:
  - Home: index.md
  - About: about.md

VuePress configuration (.vuepress/config.js):

module.exports = {
  title: 'My Docs',
  themeConfig: {
    sidebar: [
      '/',
      '/about'
    ]
  }
}

Both MkDocs and VuePress are popular static site generators for creating documentation websites. MkDocs is Python-based and focuses on simplicity, while VuePress leverages Vue.js for more advanced features and customization. MkDocs is generally easier to set up and use, making it a good choice for straightforward documentation projects. VuePress, on the other hand, offers more flexibility and power for complex documentation sites, especially those requiring dynamic content or custom components.

docusaurus

56,173

Easy to maintain open source documentation websites.

Pros of Docusaurus

Built-in support for versioning documentation
React-based, allowing for more dynamic and interactive content
Includes features like search, internationalization, and blog out of the box

Cons of Docusaurus

Steeper learning curve, especially for those unfamiliar with React
Heavier and more complex setup compared to MkDocs
May be overkill for simple documentation projects

Code Comparison

MkDocs (Python-based):

site_name: My Docs
nav:
  - Home: index.md
  - About: about.md
theme: material

Docusaurus (JavaScript/React-based):

module.exports = {
  title: 'My Site',
  tagline: 'The tagline of my site',
  url: 'https://your-docusaurus-site.example.com',
  baseUrl: '/',
  onBrokenLinks: 'throw',
  onBrokenMarkdownLinks: 'warn',
  favicon: 'img/favicon.ico',
  organizationName: 'facebook',
  projectName: 'docusaurus',
};

Convert designs to code with AI

Introducing Visual Copilot: A new AI model to turn Figma designs to high quality code using your components.

Try Visual Copilot

README

MkDocs

Project documentation with Markdown

MkDocs is a fast, simple and downright gorgeous static site generator that's geared towards building project documentation. Documentation source files are written in Markdown, and configured with a single YAML configuration file. It is designed to be easy to use and can be extended with third-party themes, plugins, and Markdown extensions.

Please see the Documentation for an introductory tutorial and a full user guide.

Features

Build static HTML files from Markdown files.
Use Plugins and Markdown Extensions to enhance MkDocs.
Use the built-in themes, third party themes or create your own.
Publish your documentation anywhere that static files can be served.
Much more!

Support

If you need help with MkDocs, do not hesitate to get in contact with us!

For questions and high-level discussions, use Discussions on GitHub.
- For small questions, a good alternative is the Chat room on Gitter/Matrix.
To report a bug or make a feature request, open an Issue on GitHub.

Please note that we may only provide support for problems/questions regarding core features of MkDocs. Any questions or bug reports about features of third-party themes, plugins, extensions or similar should be made to their respective projects.
But, such questions are not banned from the chat room.

Make sure to stick around to answer some questions as well!

Contributing to MkDocs

The MkDocs project welcomes, and depends on, contributions from developers and users in the open source community. Please see the Contributing Guide for information on how you can help.

Code of Conduct

Everyone interacting in the MkDocs project's codebases, issue trackers, and discussion forums is expected to follow the PyPA Code of Conduct.

License

BSD-2-Clause

Top Related Projects

Convert designs to code with AI

Introducing Visual Copilot: A new AI model to turn Figma designs to high quality code using your components.

Try Visual Copilot