Oct 12, 2022

PIP-Talk - Week 41

The topic for this week is translation with Mkdocs

logo

Mkdocs is a fast, simple and gorgeous static site generator that’s geared towards building project documentation. The generated documentation has a built in search function and template support. It´s easy to connect the deployment to Github and other destinations.

Bellow is a sample of a simple documentation site built with mkdoc:

![img](img src=“https://www.mkdocs.org/img/readthedocs.png" =550x)

License

BSD License (BSD)

Features

  • Build static HTML files from Markdown files.
  • Built in webserver.
  • Live preview.
  • Use Plugins and Markdown Extensions to enhance MkDocs.
  • Use the built-in themes, third party themes or create your own.
  • Publish your documentation anywhere that static files can be served (ex: Github).

Get started

install mkdocs

First of all, install mkdocs:

pip install mkdocs

A even better way is to install the module as a pipx application (read more about pipx).

pipx install mkdocs

initialize your project

For every new project you would need to initialize the project. This is done with the command: new. When you initialize your project mkdocs will create a skeleton of needed files and folders.

Here we will create a simple documentation for our project-y

mkdocs new project-y
cd project-x

add document

Adding a new file to the documentation is simply to create a new markdown file (*.md) in the docs folder and to include the file in the mkdocs.yaml file. In this mkdocs.yaml example I have tree files that will be added to the documentation (and some metadata):

site_name: Project-y
site_url: https://blog.toxicglue.com/
nav:
      - 'index.md'
      - 'about.md'
      - 'example.md'
theme: readthedocs

build

To manually build/rebuild you use the command: build (within the project folder).

mkdocs build

preview or live-preview

To view your generated documentation you use the command: serve. This command will start up the internal webserver on default port: 8000.

mkdocs serve

If you would like the server to use another port, you could do this with the -a switch. Here we start the webserver on port 2021.

mkdocs serve -a localhost:2021

Note: the server will rebuild all changes live, so there is no need to rebuild or restart the server during changes (new or changed files).

publish

There a couple of ways to deploy the generated documentation. You could use Github pages or any server of your choice (since the result is just static html files)

The command gh-deploy will deploy your files to your github:

mkdocs gh-deploy --config-file ../my-project/mkdocs.yml --remote-branch master

Example of a simple and manual scp copy operation:

mkdocs build
scp -r ./site [email protected]:/path/to/server/root

Links and resources