MkDocs¶
Mkdocs is a static site generator that is useful for building project documentation. It combines document source files written in Markdown, and is configured with a single YAML file.
Installing MkDocs
To install MkDocs, run the following command from a terminal:
Creating a Project¶
To create a simple project that you can use to learn Mkdocs, run the following command:
The following files should have then been created for you:
You should now have a mkdocs.yml
configuration file, a docs
directory, and a index.md
file within the docs
directory. These are all the files that are needed in order to create a simple site using Mkdocs. Mkdocs has the dev tools required to preview the documentation as it is created.
Opening the Documentation in the Browser¶
From the learning-mkdocs directory, run mkdocs serve
command. Open localhost:8000
in a browser and you should see the following page.
If you edit the mkdocs.yml
config file, for example, by changing the site_name
and saving the file, you should see the changes automatically take effect in your browser.
Once your browser reloads, you'll see the new changes!
Changing the Theme¶
To change how the documentation is displayed, the configuration file can be changed to use a different theme. Edit mkdocs.yml
to include a theme
setting.
Requirement: Material Extention Installed
Install Material by running the following command:
Save the changes, and you'll see the Material theme being used.
Adding Pages¶
To add a second page to your documentation, firt run this to copy an example Markdown file to your project:
curl 'https://raw.githubusercontent.com/tjzegmott/TJZegmott.github.io/master/files/markdown-intro.md' > docs/markdown.md
Now, edit the configuration file to include navigation on the right of our page. Add information about the order, title, and nesting of each page by adding a nav
setting:
To nest the navigation tree, lets edit the mkdocs.yml
once more:
site_name: Learning MkDocs
theme:
name: material
nav:
- Home: index.md
- Skills:
- Markdown: markdown.md
Requirement: Material for MkDocs Extentions
You might've noticed that some of the documentation is not displaying nicely. This is because markdown.md
was written using "Material for MkDocs" extentions. These extentions can be installed by running:
mkdocs.yml
site_name: Learning MkDocs
theme:
name: material
# Extensions
markdown_extensions:
- markdown.extensions.admonition
- markdown.extensions.attr_list
- markdown.extensions.def_list
- markdown.extensions.footnotes
- markdown.extensions.meta
- markdown.extensions.toc:
permalink: true
- Home: index.md
- Skills:
- Markdown: markdown.md