Backend Docs¶

👋 Welcome to the MAJORITY Backend documentation site!

New to Backend?¶

Everyone's documentation¶

Do not be afraid to create new content, or update the existing one! Even small improvements are highly appreciated!

Updating¶

To edit a page, just click the "edit" icon in the top right corner of a page (which leads to Github edit, for example
https://github.com/majority-dev/be-docs/edit/master/docs/README.md for this page) and make a commit directly on Github.
It will take 1-2 minutes before the edit is live on the site.

To add a new page, go to Github and create a new page (i.e. https://github.com/majority-dev/be-docs/new/master/docs).
Pages will be automatically included in the left side table of contents.

It is also possible to check out the repo and do edits locally if you prefer (git clone https://github.com/majority-dev/be-docs.git),
commit directly to the master branch, no PR or review needed.

The docs can be generated locally, if you have python installed:

With uv:

...\be-docs> uvx --with-requirements .\requirements.txt mkdocs serve

Or with pip (but this will pollute your global python unless you first create a venv):

...\be-docs> pip install -r requirements.txt
...\be-docs> mkdocs serve

Technical details¶

The site is built on MkDocs with the Material for MkDocs theme,
and a couple of plugins. The content is stored as Markdown files, which are compiled and deployed by Cloudflare Pages.
(Previously it used Github Actions, but that workflow is disabled.)

Why MkDocs¶

Unfortunately the built in Github Wiki (Gollum) is very limited in its capabilitites. Most importantly it lacks any
kind of feature for folders or other hierarcy, as detailed in this Issue
created already in 2018.

MkDocs is one of the most popular technical site documentation building tools, used by for example Spotify Backstage.
It supports most use cases, and is easy to extend if needed.