Getting started with MkDocs
MkDocs is a documentation generator that focuses on speed and simplicity. It has many great features including:
Preview your documentation as you write it
Easy customization with themes and extensions
Writing documentation with Markdown
Note
MkDocs is a great choice for building technical documentation. However, Read the Docs also supports Sphinx, another tool for writing and building documentation.
Quick start
See also
If you already have a Mkdocs project, check out our Importing your documentation guide.
Assuming you have Python already, install MkDocs:
pip install mkdocs
Setup your MkDocs project:
mkdocs new .
This command creates mkdocs.yml which holds your MkDocs configuration,
and docs/index.md which is the Markdown file
that is the entry point for your documentation.
You can edit this index.md file to add more details about your project
and then you can build your documentation:
mkdocs serve
This command builds your Markdown files into HTML and starts a development server to browse your documentation. Open up http://127.0.0.1:8000/ in your web browser to see your documentation. You can make changes to your Markdown files and your docs will automatically rebuild.
Your MkDocs project is built
Once you have your documentation in a public repository such as GitHub, Bitbucket, or GitLab, you can start using Read the Docs by importing your docs.
Warning
We strongly recommend to pin the MkDocs version used for your project to build the docs to avoid potential future incompatibilities.
Get inspired!
You might learn more and find the first ingredients for starting your own documentation project by looking at Example projects - view live example renditions and copy & paste from the accompanying source code.
External resources
Here are some external resources to help you learn more about MkDocs.