MkDocs

Last updated
MkDocs
Developer(s) Tom Christie, Dougal Matthews, Waylan Limberg, Oleh Prypin, Ultrabug
Initial releaseJanuary 24, 2014 (2014-01-24)
Stable release
1.6.1 [1] / August 30, 2024;2 months ago (2024-08-30)
Repository
Written in Python
Operating system Cross-platform
Type Documentation generator
License BSD
Website www.mkdocs.org

MkDocs is static site generator designed for building project documentation. It is written in Python, and also used in other environments.

Contents

Mode of operation

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 [2] [3] 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, [4] including the popular Material for MkDocs theme. [5]

History

The first tagged version of MkDocs, version 0.2, came out on January 21, 2014. [6]

By early 2015, Read the Docs supported building documentation with MkDocs, in addition to Sphinx. In preparation for the 0.12 release, [7] MkDocs started using Read the Docs for hosting. [8]

In January 2016, MkDocs added support for installable themes. [9] 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. [10]

Usage

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. [11] [12]

Many companies use MkDocs with the Material theme to deploy their documentation, including Atlassian, [13] Google, [14] Microsoft, [15] and Red Hat. [16] It is also a popular choice among open source projects, such as Electron, [17] Kubernetes, [18] and WebKit. [19]

See also

Related Research Articles

Programming languages can be grouped by the number and types of paradigms supported.

A lightweight markup language (LML), also termed a simple or humane markup language, is a markup language with simple, unobtrusive syntax. It is designed to be easy to write using any generic text editor and easy to read in its raw form. Lightweight markup languages are used in applications where it may be necessary to read the raw document as well as the final rendered output.

A source-code-hosting facility is a file archive and web hosting facility for source code of software, documentation, web pages, and other works, accessible either publicly or privately. They are often used by open-source software projects and other multi-developer projects to maintain revision and version history, or version control. Many repositories provide a bug tracking system, and offer release management, mailing lists, and wiki-based project documentation. Software authors generally retain their copyright when software is posted to a code hosting facilities.

<span class="mw-page-title-main">Markdown</span> Plain text markup language

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 elsewhere in online forums, collaborative software, documentation pages, and readme files.

Notable issue tracking systems, including bug tracking systems, help desk and service desk issue tracking systems, as well as asset management systems, include the following. The comparison includes client-server application, distributed and hosted systems.

AsciiDoc is a human-readable document format, semantically equivalent to DocBook XML, but using plain-text mark-up conventions. AsciiDoc documents can be created using any text editor and read “as-is”, or rendered to HTML or any other format supported by a DocBook tool-chain, i.e. PDF, TeX, Unix manpages, e-books, slide presentations, etc. Common file extensions for AsciiDoc files are txt and adoc.

diagrams.net Web based diagram editor

diagrams.net is a cross-platform graph drawing software application developed in HTML5 and JavaScript. Its interface can be used to create diagrams such as flowcharts, wireframes, UML diagrams, organizational charts, and network diagrams.

This is a comparison of notable web frameworks, software used to build and deploy web applications.


This is a comparison of notable free and open-source configuration management software, suitable for tasks like server configuration, orchestration and infrastructure as code typically performed by a system administrator.

Bitbucket is a Git-based source code repository hosting service owned by Atlassian. Bitbucket offers both commercial plans and free accounts with an unlimited number of private repositories.

cdist Software configuration management tool

cdist is a free software configuration management tool for Unix-like systems. It manages nodes over SSH using the Bourne Shell, and does not require any additional software to be installed on target nodes.

Ansible is a suite of software tools that enables infrastructure as code. It is open-source and the suite includes software provisioning, configuration management, and application deployment functionality.

Kubernetes is an open-source container orchestration system for automating software deployment, scaling, and management. Originally designed by Google, the project is now maintained by a worldwide community of contributors, and the trademark is held by the Cloud Native Computing Foundation.

The following tables compare notable software frameworks, libraries, and computer programs for deep learning applications.

<span class="mw-page-title-main">Notebook interface</span> Programming tool blending code and documents

A notebook interface or computational notebook is a virtual notebook environment used for literate programming, a method of writing computer programs. Some notebooks are WYSIWYG environments including executable calculations embedded in formatted documents; others separate calculations and text into separate sections. Notebooks share some goals and features with spreadsheets and word processors but go beyond their limited data models.

The Open edX platform is the open-source software, originally developed by Piotr Mitros, whose development led to the creation of the edX organization. On June 1, 2013, edX open sourced the platform, naming it Open edX to distinguish it from the organization itself. The source code can be found on GitHub. Maintenance was transferred to edX, an MIT/Harvard education initiative, in 2012.

<span class="mw-page-title-main">Read the Docs</span> Software documentation hosting website

Read the Docs is an open-sourced free software documentation hosting platform. It generates documentation written with the Sphinx documentation generator, MkDocs, or Jupyter Book.

Hugo is a static site generator written in Go. Steve Francia originally created Hugo as an open source project in 2013. Since v0.14 in 2015, Hugo has continued development under the lead of Bjørn Erik Pedersen with other contributors. Hugo is licensed under the Apache License 2.0.

FastAPI is a high-performance web framework for building HTTP-based service APIs in Python 3.8+. It uses Pydantic and type hints to validate, serialize and deserialize data. FastAPI also automatically generates OpenAPI documentation for APIs built with it. It was first released in 2018.

References

  1. ↑ "Release Notes". MkDocs.
  2. ↑ "Extensions — Python-Markdown 3.4.4 documentation". python-markdown.github.io. Retrieved 2023-09-23.
  3. ↑ "Pymdown Extensions - PyMdown Extensions Documentation". facelessuser.github.io. Retrieved 2023-09-23.
  4. ↑ Theming catalog, MkDocs, 2023-09-23, retrieved 2023-09-23
  5. ↑ Donath, Martin. "Material for MkDocs". squidfunk.github.io. Retrieved 2023-09-23.
  6. ↑ "Release 0.2 · mkdocs/mkdocs". GitHub. Retrieved 2023-09-24.
  7. ↑ "MkDocs 0.12 is in the wild. Lots of bug fixes and a few new features". X (formerly Twitter). 2015-04-14. Retrieved 2023-09-24.
  8. ↑ "mkdocs | Read the Docs". readthedocs.org. 2015-02-12. Retrieved 2023-09-24.
  9. ↑ "The new MkDocs release supports installable themes. Nice addition to the project that will let you install via pip". X (formerly Twitter). 2016-01-21. Retrieved 2023-09-24.
  10. ↑ Donath, Martin (2021-12-27). "The past, present and future - Material for MkDocs". squidfunk.github.io. Retrieved 2023-09-24.
  11. ↑ "GitLab Pages examples / mkdocs · GitLab". GitLab. Retrieved 2023-12-10.
  12. ↑ "Deploy an MkDocs site · Cloudflare Pages docs". developers.cloudflare.com. 2023-08-07. Retrieved 2023-12-10.
  13. ↑ "Atlassian DC Helm Charts". atlassian.github.io. Retrieved 2023-12-10.
  14. ↑ "Accompanist". google.github.io. Retrieved 2023-12-10.
  15. ↑ "Code With Engineering Playbook". microsoft.github.io. Retrieved 2023-12-10.
  16. ↑ "home - Ansible Lint Documentation". ansible-lint.readthedocs.io. Retrieved 2023-12-10.
  17. ↑ "electron-builder". www.electron.build. Retrieved 2023-12-10.
  18. ↑ "Welcome - kOps - Kubernetes Operations". kops.sigs.k8s.io. Retrieved 2023-12-10.
  19. ↑ "WebKit Documentation". docs.webkit.org. Retrieved 2023-12-10.
This page is based on this Wikipedia article
Text is available under the CC BY-SA 4.0 license; additional terms may apply.
Images, videos and audio are available under their respective licenses.