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.5.3 [1] / September 18, 2023;2 months ago (2023-09-18)
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

MkDodcs 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 21st, 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.

<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 a markup language that is easy to read in its source code form. 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 Graph drawing software

diagrams.net is a cross-platform graph drawing software developed in HTML5 and JavaScript. Its interface can be used to create diagrams such as flowcharts, wireframes, UML diagrams, organizational charts, and network diagrams. Parts of its source code are provided under the Apache 2 open-source license.

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.

<span class="mw-page-title-main">GitHub</span> Hosting service for software projects

GitHub, Inc. is a platform and cloud-based service for software development and version control, allowing developers to store and manage their code. It uses Git software, providing the distributed version control of Git plus access control, bug tracking, software feature requests, task management, continuous integration, and wikis for every project. Headquartered in California, it has been a subsidiary of Microsoft since 2018.

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.

<span class="mw-page-title-main">Cloud9 IDE</span> Online integrated development environment

Cloud9 IDE is an Online IDE, published as open source from version 2.0, until version 3.0. It supports multiple programming languages, including C, C++, PHP, Ruby, Perl, Python, JavaScript with Node.js, and Go.

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 the Cloud Native Computing Foundation.

The following table compares notable software frameworks, libraries and computer programs for deep learning.

The Open edX platform is the open-source software 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. The platform was originally developed as a research project at MIT, with maintenance transferred to edX in 2012.

<span class="mw-page-title-main">Read the Docs</span>

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.

Microsoft Docs was a library of technical documentation for end users, developers, and IT professionals who work with Microsoft products. Microsoft Docs was introduced in June 2016 as a replacement of the MSDN and TechNet libraries which previously hosted some of these materials. Microsoft Docs initially contained only .NET documentation. The process of migrating the bulk of the MSDN and TechNet libraries' content took approximately two years.

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.