MkDocs

MkDocs converts Markdown files into HTML pages, effectively creating a static website containing documentation.

Markdown is extensible, and the MkDocs ecosystem exploits its extensible nature through a number of extensions{{Cite web |title=Extensions — Python-Markdown 3.4.4 documentation |url=https://python-markdown.github.io/extensions/ |access-date=2023-09-23 |website=python-markdown.github.io}}{{Cite web |title=Pymdown Extensions - PyMdown Extensions Documentation |url=https://facelessuser.github.io/pymdown-extensions/ |access-date=2023-09-23 |website=facelessuser.github.io}} that help with for autogenerating documentation from source code, adding admonitions, writing mathematical notation, inserting footnotes, highlighting source code etc.

MkDocs provides two built-in themes, default theme (based on Bootstrap) and Read the Docs theme. Many of the available third-party themes are listed in the official catalog,{{Citation |title=Theming catalog |date=2023-09-23 |url=https://github.com/mkdocs/catalog |access-date=2023-09-23 |publisher=MkDocs}} including the popular Material for MkDocs theme.{{Cite web |last=Donath |first=Martin |title=Material for MkDocs |url=https://squidfunk.github.io/mkdocs-material/ |access-date=2023-09-23 |website=squidfunk.github.io |language=en}}

The first tagged version of MkDocs, version 0.2, came out on January 21, 2014.{{Cite web |title=Release 0.2 · mkdocs/mkdocs |url=https://github.com/mkdocs/mkdocs/releases/tag/0.2 |access-date=2023-09-24 |website=GitHub |language=en}}

By early 2015, Read the Docs supported building documentation with MkDocs, in addition to Sphinx. In preparation for the 0.12 release,{{Cite web |title=MkDocs 0.12 is in the wild. Lots of bug fixes and a few new features. |url=https://twitter.com/MkDocsProject/status/588049882214232065 |date=2015-04-14 |access-date=2023-09-24 |website=X (formerly Twitter) |language=en}} MkDocs started using Read the Docs for hosting.{{Cite web |title=mkdocs {{!}} Read the Docs |url=https://readthedocs.org/projects/mkdocs/builds/2315117/ |date=2015-02-12 |access-date=2023-09-24 |website=readthedocs.org}}

In January 2016, MkDocs added support for installable themes.{{Cite web |title=The new MkDocs release supports installable themes. Nice addition to the project that will let you install via pip |url=https://twitter.com/csimpkins/status/690170253586866179 |date=2016-01-21 |access-date=2023-09-24 |website=X (formerly Twitter) |language=en}} Next month, Martin Donath started developing Material for MkDocs theme. In the following years, the theme became very popular and in July 2020 the development model was changed to sponsorware, where the new features get released to the Insiders version first and become publicly available after funding goals are hit.{{Cite web |last=Donath |first=Martin |date=2021-12-27 |title=The past, present and future - Material for MkDocs |url=https://squidfunk.github.io/mkdocs-material/blog/2021/12/27/the-past-present-and-future/ |access-date=2023-09-24 |website=squidfunk.github.io |language=en}}

MkDocs offers built-in support for deployment to GitHub Pages. Alternatives, such as GitLab and Cloudflare Pages, offer first-party support for deploying MkDocs sites.{{Cite web |title=GitLab Pages examples / mkdocs · GitLab |url=https://gitlab.com/pages/mkdocs |access-date=2023-12-10 |website=GitLab |language=en}}{{Cite web |date=2023-08-07 |title=Deploy an MkDocs site · Cloudflare Pages docs |url=https://developers.cloudflare.com/pages/framework-guides/deploy-an-mkdocs-site/ |access-date=2023-12-10 |website=developers.cloudflare.com |language=en}}

Many companies use MkDocs with the Material theme to deploy their documentation, including Atlassian,{{Cite web |title=Atlassian DC Helm Charts |url=https://atlassian.github.io/data-center-helm-charts/ |access-date=2023-12-10 |website=atlassian.github.io}} Google,{{Cite web |title=Accompanist |url=https://google.github.io/accompanist/ |access-date=2023-12-10 |website=google.github.io}} Microsoft,{{Cite web |title=Code With Engineering Playbook |url=https://microsoft.github.io/code-with-engineering-playbook/ |access-date=2023-12-10 |website=microsoft.github.io}} and Red Hat.{{Cite web |title=home - Ansible Lint Documentation |url=https://ansible-lint.readthedocs.io/ |access-date=2023-12-10 |website=ansible-lint.readthedocs.io |language=en}} It is also a popular choice among open source projects, such as Electron,{{Cite web |title=electron-builder |url=https://www.electron.build/ |access-date=2023-12-10 |website=www.electron.build}} Kubernetes,{{Cite web |title=Welcome - kOps - Kubernetes Operations |url=https://kops.sigs.k8s.io/ |access-date=2023-12-10 |website=kops.sigs.k8s.io}} and WebKit.{{Cite web |title=WebKit Documentation |url=https://docs.webkit.org/ |access-date=2023-12-10 |website=docs.webkit.org}}

A major benefit of MkDocs verses other static site generators is that all the files you edit for content are pure markdown files. In contrast, jekyll, a much more popular generator due to integration/branding with github, uses yaml at the top of every markdown page that may be daunting or annoying for writers and also cannot be interpreted by many standard markdown generators, such as medium, github.com, visual studio code extensions, etc.

{{Portal|Free and open-source software}}

• Comparison of documentation generators
• JAMstack

{{Reflist}}

• {{Official website|name=MkDocs}}
• [https://readthedocs.org/ Read the Docs] large-scale, collaborative documentation host powered by Sphinx, MkDocs, and Jupyter Book

Category:Free documentation generators

Category:Free software programmed in Python

Category:Software using the BSD license