Mkdocs is a project that enables you into writing documentation for your project in a super fast and easy way.
First, you have to create a
docs/ folder in the root of your project,
inside it, you can start creating markdown (
The main file of the documentation is called
index.md. This can be configured
by configuring the navigation setting in your
Once you finish writing your documentation, using the command line,
mkdocs will get all of these markdown files and will output a rendered
HTML website to the
If you are starting from the ground up, you need to install
mkdocs in your
python -m pip install mkdocs mkdocs-kpn
Creating a configuration¶
In the root of your project create a file called
and put this initial configuration:
site_name: <My Website Name> theme: name: kpn markdown_extensions: - codehilite: guess_lang: false
For more settings check the Full Example at the bottom of the page.
Add search support¶
Just add to the
mkdocs.yml the following:
plugins: - search: prebuild_index: true
A search input will appear. The search index is offline, so no backend is required.
python -m mkdocs build
Will output the generated website into a
site/ folder. Remember to add it
.gitignore, the idea is for CI's to automatically build it.
python -m mkdocs serve
This command will run a webserver which will reload your browser as soon as you make a change. This is useful to see your documentation while you are writing it.
Full configuration example¶
# Project information site_name: 'KPN Theme' site_description: 'A KPN theme for MkDocs' site_author: 'Jon Doe' # Repository repo_name: 'kpn/mkdocs-kpn-theme' repo_url: https://github.com/kpn/mkdocs-kpn-theme # Copyright copyright: 'Copyright © KPN' # Google Analytics Disabled by default google_analytics: - 'UA-XXXXXXXX-X' - 'auto' extra: # Use the repo edit url instead of the link to the repo use_edit_url: false # Extensions markdown_extensions: - admonition - codehilite: guess_lang: false - toc: permalink: true - footnotes - pymdownx.critic - pymdownx.emoji - pymdownx.keys - pymdownx.mark - pymdownx.smartsymbols - pymdownx.tasklist - pymdownx.tilde
To document your API we recommend using mkdocstrings.