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:
- MkDocs as the web frameworks.
- Pipenv, pip or other package manager to handle Python dependencies.
- The Material theme for all the styling.
Optional dependencies:
- GNU Make for building.
Example installation procedures tested on Debian Bullseye are available:
- scripts/onion-mkdocs-provision-build: installs all the needed dependencies to build Onion MkDocs websites.
- scripts/onion-mkdocs-provision-host: provision the hosting environment to serve Onion MkDocs websites, including a Tor Onion Service.
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: