User Guide

Overview

MKDOCS is a fast and simple static website generator written in markdown and confiqured with single YAML file to provide projects documentation.

You can also use RTL theme support in Persian

Host anywhere

You can host this HTML static pages on Github pages, Amazon S3 or anywhere else

Easy to customize

Customize the theme just the way you like easily.

Installation

In order to install MkDocs you'll need Python installed on your system, as well as the Python package manager, pip. You can check if you have these already installed like so:

$ python --version
Python 2.7.2
$ pip --version
pip 1.5.2

MkDocs supports Python 2.6, 2.7, 3.3, 3.4 and 3.5.

On Windows we recommend that you install Python and pip with Chocolatey.

Install the mkdocs package using pip

pip install mkdocs

You should now have the mkdocs command installed on your system. Run mkdocs --version to check that everything worked okay.

$ mkdocs --version
mkdocs, version 0.15.2

Getting started

Getting started is super easy.

mkdocs new my-project
cd my-project

Let's check initial project which has been created for us.

There's a single configuration file named mkdocs.yml, and a folder named docs that will contain our documentation source files. Right now the docs folder just contains a single documentation page, named index.md.

MkDocs comes with a built-in webserver that lets you preview your documentation as you work on it. We start the webserver by making sure we're in the same directory as the mkdocs.yml config file, and then running the mkdocs serve command:

$ mkdocs serve
Running at: http://127.0.0.1:8000/

Open up http://127.0.0.1:8000 in your browser, and you'll see the index page being displayed:

The webserver also supports auto-reloading, and will rebuild your documentation whenever anything in the configuration file, documentation directory or theme directory changes.

Go ahead and edit the docs/index.md file now and save the file. Then simply hit reload in the browser and you'll see your updated documentation.

To edit the configuration file, mkdocs.yml. Change the site_name setting to something else and save the file.

Adding pages

Go to docs/index.md document and change the initial heading to MkLorum, then reload the site in your browser, and you should see the change take effect immediately.

Let's also add a second page to our documentation:

curl 'jaspervdj.be/lorem-markdownum/markdown.txt' > docs/about.md

We'd like our documentation site to include some navigation headers, so we'll edit the configuration file and add some information about the order and title to use for out headers:

site_name: My Docs
pages:
- Home: index.md
- About: about.md
theme: basic_theme

More Commands

There are various other commands and options available. For a complete list of commands, use the --help flag:

mkdocs --help

Jinks Installation

You can easily download Jinks themes with Pip:

pip install mkdocs-jinks

To change the theme of your documentation site you need to open mkdocs.yml. and add this line:

theme: jinks_en

And run it as we said before by following command:

mkdocs serve