Skip to content

Intro

Estimated time to read: 3 minutes

What is MkDocs?

MkDocs is a documentation generation tool designed to simplify the process of creating documents for software projects, personal web pages, and more. With MkDocs, you can write documentation using the Markdown markup language, making the process of creating and maintaining documentation accessible even to those who are not familiar with more complex markup languages like HTML.

Why Use MkDocs?

There are several reasons to choose MkDocs as a tool for documentation creation. Here are some of the main motivations:

  1. Ease of use: MkDocs is based on the Markdown markup language, known for its simplicity and clarity. This makes the creation and maintenance of documentation accessible even to those who are not familiar with more complex markup languages like HTML.

  2. Speed in creation: MkDocs simplifies the documentation creation process. With just a few commands, you can initialize a project, add new pages, and generate a complete documentation site. This allows you to focus more on content, reducing the time required for documentation creation.

  3. Professional and elegant appearance: MkDocs generates documentation websites with a modern and elegant design. The clean appearance and intuitive navigation enhance the user experience, making the documentation more enjoyable to read and consult.

  4. Flexible configuration: MkDocs offers many configuration options that allow you to customize the appearance and behavior of the documentation site. You can customize the theme, add navigation elements, and embed code snippets to tailor the documentation to the needs of your project.

  5. Large support community: MkDocs has an active community and a plugin ecosystem that provides additional functionality. You can find support online, tutorials, and additional resources thanks to the community that continually contributes to the improvement of the MkDocs ecosystem.

What Will We Cover?

In this tutorial, we will explore step by step how to use MkDocs to create clean and easily navigable documentation for your project. You can also use MkDocs to build a site for a community (as we did 😉).

  • Introduction to MkDocs
  • Initializing the project
  • Creating documentation pages using Markdown.
  • Customizing the appearance of your documentation site.
  • Developing your site locally
  • Deploying your site

Some personal considerations

We feel like sharing some considerations after using mkdocs both at work and here in the community:

  • It is a very good library that allows you to get good results, but which are often similar to each other, if you are looking for the extreme customization that a frontend with javascript can offer you it is not for you
  • It is a very flexible tool, but it is difficult sometimes to integrate different libraries that conflict.
  • There are very good and viable alternatives on Python, but they are often less beautiful.
  • Wordpress is definitely a good alternative to landing pages, but we are nerds and like things a little nerdy :) Plus you can version the code and your own files, plus it's much more collaborative, without weird point-and-clicks or weird plugins
  • Customizing the template to create your own style is not that easy

However we were very happy with the library, it allows you to make very good websites very fast and light.

Why Markdown?

Markdown is a widely used standard format for creating rich text quickly and easily, it is also the same format used in README files on Github in every repository.

There are many extensions that allow you to enrich Markdown, however we recommend that you look at and practice with Github's standard help, especially keeping this very handy official Github cheatsheet handy at all times.