MkDocs is a so-called static site generator that uses Python to turn your Markdown files into HTML. It is a great tool to document your projects and works nicely with GitHub Pages.
This post is part of my journey to learn Python. You can find the other parts of this series here.
Installation
We can install MkDocs like most other Python tools with PIP:
|
1 |
$ pip install mkdocs |
Create a new site
With one command we can create a new project (replace my-demo with the name of your project):
|
1 |
$ mkdocs new my-demo |
INFO – Creating project directory: my-demo
INFO – Writing config file: my-demo\mkdocs.yml
INFO – Writing initial docs: my-demo\docs\index.md
The whole MkDocs project is inside a folder with the project name we used in the new command. Whenever you do something with MkDocs you must be in this folder – otherwise you will get an error message.
Inside the project folder is the configuration file mkdocs.yaml and a docs folder, where you can put your markdown files. The generated docs/index.md file lists the most important commands for MkDocs and points you to the helpful documentation:
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 |
# Welcome to MkDocs For full documentation visit [mkdocs.org](https://www.mkdocs.org). ## Commands * `mkdocs new [dir-name]` - Create a new project. * `mkdocs serve` - Start the live-reloading docs server. * `mkdocs build` - Build the documentation site. * `mkdocs -h` - Print help message and exit. ## Project layout mkdocs.yml # The configuration file. docs/ index.md # The documentation homepage. ... # Other markdown pages, images and other files. |
Minimalistic configuration
All the configuration for your site goes into the file mkdocs.yaml. In a newly created project this configuration file only has one single line:
|
1 |
site_name: My Docs |
That is all it takes. In the next post I will explain how you can customise MkDocs and we will add a few more lines to this file.
Preview mode
Inside our project we can run a preview mode of our site with this command:
|
1 |
$ mkdocs serve |
INFO – Building documentation…
INFO – Cleaning site directory
INFO – Documentation built in 0.10 seconds
[I 210205 12:59:42 server:335] Serving on http://127.0.0.1:8000
INFO – Serving on http://127.0.0.1:8000
[I 210205 12:59:42 handlers:62] Start watching changes
Preview means in this case that MkDocs runs our site in a development server that automatically updates the web site when it detects a change in a Markdown file. This is a great help when you try something out and want to see how it looks right away.
Open your browser and go to http://127.0.0.1:8000 to see how your site looks:
Generate HTML
The great benefit of a static site generator is that we end up with plain HTML that does not need a special web server to deliver our site. Before we can put our HTML on a server we need to generate it with this command:
|
1 |
$ mkdocs build |
INFO – Cleaning site directory
INFO – Building documentation to directory: D:\Python\MkDocs\my-demo\site
INFO – Documentation built in 0.43 seconds
You find the generated HTML pages and a bit of JavaScript in the site folder. You can copy the content from this folder to your web server or put it onto your GitHub page.
Next
While you add additional content to your site, you start noticing that the default template may not be the best fit for your needs. In the next post we look at how we can customise MkDocs.
1 thought on “Python Friday #57: Introduction to MkDocs”