There's a popular maxim that "a product is as good as its documentation". This holds true as much for software as it does for physical products.
As a small, indie developer who doesn't specialize in front-end design, I often hire a freelancer to build my product website—which, of course, usually includes a documentation section.
A documentation section can take quite a bit of time and money to build, even for a simple product, so it would be nice not to have to reinvent the wheel for every site. Fortunately, there is a way.
Introducing MkDocs
MkDocs is a free, static site generator geared towards building project documentation. It can be used to generate a stand-alone site, or just a documentation section of a larger site.
Because MkDocs produces static files, your documentation is light-weight and easy to host—using free services such as GitHub Pages and Read The Docs—or of course on your own server.
In this article, I'll introduce MkDocs, showing you how to install it, build documentation with it and finally host the generated documentation on a web server.
To get a sense of the sort of documentation MkDocs produces, have a look at my ProfilePress WordPress plugin documentation, which is built with MkDocs using the Read the Docs theme.
MkDocs is written in Python. The documentation source files are written in Markdown, and configured with a single YAML configuration file.
To build documentation with MkDocs, you need to have it installed locally in your computer. So let's next look at how to install it.
Installing Python and MkDocs
Static site generators like Jekyll (used mainly for blogging, and built on Ruby) and MkDocs do require some command-line chops, so be warned. However, to those not used to working with the command line, I encourage you to read on and give it a try, as it's not as bad as it looks!
Installing Python and pip
To install MkDocs, you need to have Python and pip (a Python package manager) installed in your computer. They may already be installed on your computer. If you have Python 3.4 or later installed, you probably have pip installed. (See the Python installation guide for full instructions.)
To install Python on a Linux distribution such as Ubuntu, see this stackoverflow thread or do a Google search for your distribution.
For Windows, download your preferred version installer and run the file to install Python.
Alternatively, if you have the Chocolatey package manager installed in your machine, run choco install python.
To verify that your Python distribution has pip installed, run the pip --version command. Otherwise, run python get-pip.py or choco install pip via Chocolatey to get it installed.
Installing MkDocs
Now that Python and pip are installed, run pip install mkdocs to install MkDocs.
To confirm everything is fine, run mkdocs help to give mkdocs command a try.
If you are on Windows and the mkdocs command isn't alive, be sure to add C:\path-to-python-folder\Scripts to Path environmental variable.
Building the Documentation
Now that you have Python and MkDocs set up, you can get on with your actual documentation.
Firstly, create a project for the documentation (let's call it sp-doc) and navigate to the created folder:
$ mkdocs new sp-doc
$ cd sp-doc
The generated project folder will contain a docs folder—where the Markdown files for the documentation will be stored—and the configuration file mkdocs.yml.
Here is the directory structure:
|-- docs # MD doc pages
|-- index.md
|-- mkdocs.yml # config file
Add the following bare-minimum configuration to mkdocs.yml file:
site_name: SitePoint Documentation
site_description: Description of the documentation
theme: readthedocs
pages:
- ['index.md', 'Index']
MkDocs ships with a number of themes—such as "MkDocs", "Read the Docs" and "Bootstrap". Say you intend to use the default theme. In that case, simply replace readthedocs with mkdocs in the code above.
The pages config is used to determine the set of pages that should be built for the documentation and the navigation menu.
Markdown files added to pages must be relative to the docs folder. For example, if you created a new folder called config inside the docs directory and added a setup.md file in it, here's how you would add it to pages in the mkdocs.yml file configuration:
site_name: SitePoint Documentation
site_description: Description of the description
theme: readthedocs
pages:
- ['index.md', 'Index']
- ['start.md', 'Get Started']
- ['config/setup.md', 'Configuration', 'Setup']
- ['config/debug.md', 'Configuration', 'Debug']
This creates some new pages that appear automatically in our documentation menu. Firstly, there's a start.md page, with the title "Get Started".
We've also added a new section to the documentation menu called "Configuration", under which there's a link to new Setup and Debug pages.
MkDocs includes a built-in web server, so you can preview your documentation locally as you work on it.
To start the web server, ensure you are in the directory where mkdocs.yml config file resides, and then run the mkdocs serve command.
Visit http://127.0.0.1:8000 in your browser to view the documentation:
If you're satisfied with what you've created, run mkdocs build to generate the static files for the documentation which will be saved to site directory.
You can copy the static files and host them on a web server of your choosing to take the documentation live.
In the next section, we'll learn how to deploy MkDocs to Read the Docs and GitHub Pages.
Continue reading %Building Product Documentation with MkDocs%
by Agbonghama Collins via SitePoint
