0e18978fe1
* feat: add mdbook docs * chore: add several articles to docs * docs: add documentation at surface level Using Discourse urls as fallback for missing content for now docs: add missing image files * docs: Add missing chapter emojis docs: Add missing warning in Advanced docs in summary docs: add missing waydroid guide docs: rename files to avoid spaces docs: fix badly set docs build params docs: remove unnecesary placeholders * docs: Realocate 'Gaming' section under 'General' * docs: Add 'Introduction' section This section contains a table of contents of the documentation * docs: Add unstable documentation warning * docs: Add missing github url docs: add missing symlink to resources * docs: Add discourse scrapper utility * docs: minor discourse scrapper docs changes * docs: Add youtube embeding preprocessor * minor reformat for youtube-embed * docs: Add mdbook preprocessor template * docs: add format-author preprocessor * docs: add git lib to mdbook toolset * docs: Always fetch the highest quality image by fetch_discourse_md * docs: fix youtube-embed ignoring new line requirement * docs: Add documentation transcription guide * docs: Missing url in transcription guide * docs: Remove YAML header from doc guide * docs: Minor tweaks to transcription guide * docs: Add utilities preprocessor module docs: Move debug preprocessor util to utils * docs: tweak debug function * docs: Add 'replace-urls' preprocessor * chore: Move mappings parameter in replace-urls preprocessor * docs: add ignore field to replace-urls * docs: add Mdbook python types * docs: Add ignore field to replace-urls Now we can exclude files from being processed with blob patterns * chore(ci): add deploy_docs * chore(ci): Add dynamic edit url template to deploy_docs * chore(ci): Add html.site-url to deploy_docs * chore(readme): Use relative paths for repo_content * chore(ci): Add README to included paths for deploy_docs * chore(ci): Disable deploy_docs * chore(ci): Use main in deploy_docs.on.push.branches * docs: Rephrase unstable docs warning * chore(ci): Exclude docs from triggering build workflow * chore(ci): Enable deploy_docs * fix(docs): Remove unnecessary imports in preprocessors * docs: Move unstable docs warning to index.hbs * docs: Add page metadata inclusion with fetch_discourse_md.py * docs: Move fetch_discourse_md.py to docs/utils * docs: Add 'fetched_at' metadata field in fetch_discourse_md.py * docs: Update fetch_discourse_md.py to format metadata in json * Revert "chore(readme): Use relative paths for repo_content" This reverts commit |
||
|---|---|---|
| .. | ||
| hooks | ||
| src | ||
| theme_overrides | ||
| utils | ||
| .gitignore | ||
| Justfile | ||
| mkdocs.yml | ||
| poetry.lock | ||
| pyproject.toml | ||
| README.md | ||
Contributing to Bazzite MkDocs documentation
Introduction
This is a guide that will show you how to write, or transcribe documentation from Discourse forums (https://universal-blue.discourse.group/) to MkDocs pages.
What is MkDocs
MkDocs is a fast, simple and downright gorgeous static site generator that's geared towards building project documentation. Documentation source files are written in Markdown, and configured with a single YAML configuration file.
Source ~ https://www.mkdocs.org/
TL;DR: Its a fancy way tool that allows us to create a documentation website with basic Markdown.
The essential part that cant be missing in a mdBook is the mkdocs.yml file.
mkdocs.yml acts as our main configuration file. One of its main tasks is to configure the Table of Contents and to configure translation files.
Setup MkDocs tooling
⚠️ WARNING ⚠️
This step is required in order to setup previews of the resulting MkDocs
To install our dependencies, run this:
bash docs/utils/install-deps.sh
Dependencies list
Ignore if using install-deps.sh
- Poetry (can be installed with Homebrew)
- Just (preinstalled in all Universal Blue images)
You will need other tools as well, like:
- A markdown compatible code editor (ex.: Visual Studio Code)
- git (comes preinstalled in most Linux distributions)
Transcribe Discourse docs to MkDocs
Best way to learn is with a real life example. We will transcribe https://universal-blue.discourse.group/docs?topic=2657, which at the time of writting is a post called Managing and Modding Games.
1. Basic preparation
We will start with getting our utilities ready:
-
A web browser with the Discourse doc page we want to transcribe. We will use https://universal-blue.discourse.group/docs?topic=2657 for this example.
-
Our code editor.
-
A terminal open in the
docsdirectory$ cd docsGet sure we have
fetch_discourse_md.pyin there, we will need it$ ls ./utils/fetch_discourse_md.py ./utils/fetch_discourse_md.py
2. Copy the post
fetch_discourse_md.py is your friend for this task.
-
Copy the URL of the document
-
In the terminal, pass the URL to
fetch_discourse_md.py$ ./utils/fetch_discourse_md.py "https://universal-blue.discourse.group/docs?topic=2657" | wl-copyNormally,
fetch_discourse_md.pywould dump the resulting markdown doc in the terminal output, withwl-copywe store it in our clipboard for now. -
Create the markdown file where we will store our document. The title of the post is "Dual Boot Preliminary Setup and Post-Setup Guide", so somewhere under "Advanced" should be fitting.
⚠️ WARNING
Just remember, ⚠️DO NOT USE SPACES IN THE FILE NAME⚠️. Is really important, spaces in filenames is going to bit us later in a future. Instead, use underscores
_
4. Paste the document in the file
5. Rewrite URLs
We are almost done. The problem is fetch_discourse_md.py only will give us a dumped version of the Discourse document.
There is posibly URLs that are pointing to other documentation posts in Discourse that we might have already in our MkDocs.
The url in the image above is pointing to the Steam Gaming Mode Overview (Handheld/HTPC) post. At the time of writting this, we have that post avaliable in our MkDocs, so we can simply replace that URL with ours
In our case, the post is located in ../Handheld_and_HTPC_edition/Steam_Gaming_Mode/index.md
6. Add our page to navigation bar
Tip
You can skip this step if you dont need to show the page in the navigation bar
We can check how our post looks in MkDocs, run in the terminal
just mkdocs serve
Now, more likely you wont find our new added post.
If you take a look at the brief explanation, you will read about mkdocs.yml. Files not listed in there wont be added to the navigation bar, though still will be accessible with the search bar.
Lets add our file there. Look for the nav field in there and add the new file as shown:
And now our post should be visible in the nav bar.
7. (Bonus) Set a proper page name
You can add more explicit page titles (used by the browser tab names) by using YAML metadata.
Adding this at the start of the markdown file would change the tab name to "Hello world":
---
title: "Hello world"
---
Translate documentation
⚠️ WARNING
It is better to start translation once transcription in a post is settled to keep up.
Translating documentation is as straightfoward as can be.
Lets say we want to translate Homebrew.md to Spanish. All what you would have to do is make a copy of the file with the name Homebrew.es.md and start translating.
Perhaps you cant see your translation with just mkdocs serve.
Chances are we need to configure MkDocs to do so.
Open mkdocs.yml, look for the field languages, should look something like this:
languages:
- locale: en
default: true
name: English
build: true
Add your language, in our case is Spanish:
languages:
- locale: en
default: true
name: English
build: true
- locale: es
name: Spanish
build: true
And now MkDocs should show a language selector in the top bar.