MkDocs

Project documentation with Markdown.

MkDocs is a fast, simple and downright gorgeous static site generator that’s geared towards building project documentation. Documentation source files are written in Markdown, and configured with a single YAML configuration file.

I’ve written a lot of md files till now, an interesting things came about, I wanted to create a project documentation and have read other documentation with almost same template. So here I am with Mkdocs.

First steps

pip install mkdocs

So you will be needing pip here.

Complete python installation is here.

mkdocs new my-project                                               ──(Sat,Dec28)─┘
cd my-project
INFO    -  Creating project directory: my-project
INFO    -  Writing config file: my-project/mkdocs.yml
INFO    -  Writing initial docs: my-project/docs/index.md

Project layout

mkdocs.yml    # The configuration file.
docs/
    index.md  # The documentation homepage.
    ...       # Other markdown pages, images and other files.

Let’s serve:

mkdocs serve

So cool!

Modification:

Now try editing the configuration file: mkdocs.yml. Change the site_name setting to MkLorum and save the file.

site_name: MkLorum

Add pages:

Create a page at same level as index.md, named about.md

and add to mkdocs.yml

nav:
  - Home: index.md
  - About: about.md

Favorite part: theming!!

Add themes to yml file like

theme: readthedocs

More themes can be found here.

Third party themes

I have applied theme called cinder

1. Download the theme
2. Extract
3. Copy the cinder directory to your mkdocs project
4. mkdocs.yml and cinder should be at same level
5. Update the yml with

theme:
  name: null
  custom_dir: 'cinder'

Creating a nested documentation(Story!)

.
├── docs
│   ├── about.md
│   ├── chapters
│   │   ├── 1
│   │   │   ├── image.png
│   │   │   └── index.md
│   │   ├── 2
│   │   │   └── index.md
│   │   └── index.md
│   └── index.md
└── mkdocs.yml

And the yml file is like:

site_name: Atulya Docs
nav:
  - Home: index.md
  - About: about.md
  - The Lost Treasure: ./chapters

Building the project:

mkdocs build 

After building it you can try to check the output from a HTTP server

python3 -m http.server 8080    

Project link: https://codeberg.org/atulyaraaj/mkdocs-code

Documentation link: https://mystories.codeberg.page/