PIP-Talk - Week 41
The topic for this week is translation with Mkdocs
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)
BSD License (BSD)
- 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).
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
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
To manually build/rebuild you use the command: build (within the project folder).
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.
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).
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
- Homepage: https://www.mkdocs.org/
- Documentation: https://www.mkdocs.org/user-guide/
- Source Code: https://github.com/mkdocs/mkdocs
- PyPI: https://pypi.org/project/mkdocs/