MkDocs is

static site generator Static site generators (SSGs) are Software engine, software engines that use text input files (such as Markdown, reStructuredText, AsciiDoc and JSON) to generate static web pages. Unlike dynamic websites, these static pages do not change based on t ...

designed for building project documentation. It is written in

Python Python may refer to: Snakes * Pythonidae, a family of nonvenomous snakes found in Africa, Asia, and Australia ** ''Python'' (genus), a genus of Pythonidae found in Africa and Asia * Python (mythology), a mythical serpent Computing * Python (prog ...

, and also used in other environments.

Mode of operation

MkDocs converts

Markdown Markdown is a lightweight markup language for creating formatted text using a plain-text editor. John Gruber created Markdown in 2004 as an easy-to-read markup language. Markdown is widely used for blogging and instant messaging, and also used ...

files into

HTML Hypertext Markup Language (HTML) is the standard markup language for documents designed to be displayed in a web browser. It defines the content and structure of web content. It is often assisted by technologies such as Cascading Style Sheets ( ...

pages, effectively creating a static website containing documentation. Markdown is extensible, and the MkDocs ecosystem exploits its extensible nature through a number of extensions that help with for autogenerating documentation from source code, adding admonitions, writing mathematical notation, inserting footnotes, highlighting source code etc.

Themes

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, including the popular Material for MkDocs theme.

History

The first tagged version of MkDocs, version 0.2, came out on January 21, 2014. By early 2015, Read the Docs supported building documentation with MkDocs, in addition to

Sphinx A sphinx ( ; , ; or sphinges ) is a mythical creature with the head of a human, the body of a lion, and the wings of an eagle. In Culture of Greece, Greek tradition, the sphinx is a treacherous and merciless being with the head of a woman, th ...

. In preparation for the 0.12 release, MkDocs started using Read the Docs for hosting. In January 2016, MkDocs added support for installable themes. 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.

Usage

MkDocs offers built-in support for deployment to

GitHub GitHub () is a Proprietary software, proprietary developer platform that allows developers to create, store, manage, and share their code. It uses Git to provide distributed version control and GitHub itself provides access control, bug trackin ...

Pages. Alternatives, such as

GitLab GitLab is a software forge primarily developed by GitLab Inc. It is available as a community edition and a commercial edition. History GitLab was created in 2011 by Ukrainian programmer Dmitriy Zaporozhets as a side project written in Rub ...

and

Cloudflare Cloudflare, Inc., is an American company that provides content delivery network services, cybersecurity, DDoS mitigation, wide area network services, reverse proxies, Domain Name Service, ICANN-accredited domain registration, and other se ...

Pages, offer first-party support for deploying MkDocs sites. Many companies use MkDocs with the Material theme to deploy their documentation, including

Atlassian Atlassian Corporation () is an Australia, Australian-United States, American proprietary software company that specializes in collaboration tools designed primarily for software development and project management. Domicile (law), Domiciled in ...

Google Google LLC (, ) is an American multinational corporation and technology company focusing on online advertising, search engine technology, cloud computing, computer software, quantum computing, e-commerce, consumer electronics, and artificial ...

Microsoft Microsoft Corporation is an American multinational corporation and technology company, technology conglomerate headquartered in Redmond, Washington. Founded in 1975, the company became influential in the History of personal computers#The ear ...

, and

Red Hat Red Hat, Inc. (formerly Red Hat Software, Inc.) is an American software company that provides open source software products to enterprises and is a subsidiary of IBM. Founded in 1993, Red Hat has its corporate headquarters in Raleigh, North ...

. It is also a popular choice among open source projects, such as

Electron The electron (, or in nuclear reactions) is a subatomic particle with a negative one elementary charge, elementary electric charge. It is a fundamental particle that comprises the ordinary matter that makes up the universe, along with up qua ...

Kubernetes Kubernetes (), also known as K8s is an open-source software, open-source OS-level virtualization, container orchestration (computing), orchestration system for automating software deployment, scaling, and management. Originally designed by Googl ...

, and

WebKit WebKit is a browser engine primarily used in Apple's Safari web browser, as well as all web browsers on iOS and iPadOS. WebKit is also used by the PlayStation consoles starting with the PS3, the Tizen mobile operating systems, the Amazon K ...

. 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.

References

External links