Skip to content

Onion MkDocs: Material template for Tor documentation

This is a MkDocs documentation template for Tor-related projects and based on the Material theme.

Repository

Check the repository at https://gitlab.torproject.org/tpo/web/onion-mkdocs.

Requirements

Onion MkDocs relies the following software:

Optional dependencies:

Example installation procedures tested on Debian Bullseye are available:

Repository setup

This repository is ready to be used in any existing repository. It can be installed in a number of ways as follows.

Forking the project

Simply fork this project and change whatever you need.

As a Git submodule

You can simply put it as a Git submodule somewhere, like in a vendor (or vendors) folder of your project:

mkdir -p vendor && \
git submodule add --depth 1 https://gitlab.torproject.org/tpo/web/onion-mkdocs vendor/onion-mkdocs

Then use symbolic links to reference all the needed files from the root of your repository.

If you plan to use either GitLab CI/CD or GitHub Actions to build your documentation, make sure to at least copy/adapt the corresponding files from the submodule. You can't just symlink those since the submodule won't be accessible when GitLab and GitHub looks for CI/CD or Actions files. The provided GitLab CI/CD and GitHub actions configuration takes care of initializing the submodule during build time, but they should be available in the main repo in order to do so.

Manually copying

Even simpler, copy all the relevant files from this repository into your project.

Other ways

  • git-subtree(1).
  • ?

Compiling

Once all dependencies are installed and the required files are in place in your repository, just type the following to build your Onion MkDocs website:

vendor/onion-mkdocs/scripts/onion-mkdocs-build

Or, if you have setup the proper Makefile targets:

make compile

Serve

As an alias to mkdocs(1) serve command, type

vendor/onion-mkdocs/scripts/onion-mkdocs-serve

Or, if you have setup the proper Makefile targets:

make serve

Watching

A basic "watch" mode to rebuild your site whenever the docs change (like a live edit mode), use

vendor/onion-mkdocs/scripts/onion-mkdocs-watch

Or, if you have setup the proper Makefile targets:

make watch

Formatting support

MkDocs extensions

Supports all default MkDocs extensions.

Tasklists

Supports Material theme's tasklist, which is compatible with GitLab Flavored Markdown (GLFM).

Diagrams

Onion MkDocs also comes with Diagrams support:

graph LR
  Write --> Build --> Share

Other formatting plugins

All other markdown extensions from the Material theme are also available by additional configuration.

GitLab pages support

Onion MkDocs supports GitLab pages out-of-the box with a simple GitLab CI/CD configuration.

GitHub pages support

Onion MkDocs also supports GitHub pages out-of-the box with a simple GitHub CI/CD configuration.

Onionshare support

It's possible to share your local Onion MkDocs build with others by using OnionShare. Ensure you have a working onionshare-cli installation, the proper Makefile targets and then type:

make share

Can even be combined with make watch to keep the shared site always up-to-date (untested).

Live examples

Check out some live examples of Onion MkDocs config in action:

Index