mirror of https://github.com/ublue-os/bazzite.git synced 2024-12-28 18:20:09 +00:00

feat(docs): Replace mdbook with mkdocs workflow (#1548 )

* 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 6a781c6596.

* docs: Replace include with an url to repo README

* ci(docs): Add multilanguage doc build support

* docs: add Justfile utility

* docs: update Justfile utility

* ci(docs): Add stricter workflow trigger to deploy_docs

* docs: add 'preview_translation' to Justfile

* docs: add documentation translation guide

* ci(docs): Add mdbook cache

* ci(docs): Add i18n-report

* ci(docs): tweak deploy_docs workflow triggers

* ci(docs): remove unnecessary slash at build.yml

* ci(docs): remove unnecessary slash at deploy_docs.yml

* ci(docs): add docs/book.toml to deploy_docs trigger

* ci(docs): Add schedule trigger

* ci(docs): add github-pages cleaning

* ci(docs): Exclude docs from generate_changelog

* docs: Add dependencies installation script

* ci(docs): Add mdbook pdf build

* docs: Tweak Justfile to support pdf generation

* Revert "docs: Always fetch the highest quality image by fetch_discourse_md"

This reverts commit 74130ee1fe.

* ci(docs): Exclude deploy_docs.yml from cache-mdbook keys

* docs: Add 'mdbook_build' to Justfile

* docs: Add 'mdbook_serve' to Justfile

* docs: Add debug flag to fetch_discourse_md

* docs: Automate discourse documentation scrapping

* docs: Add flock to fetch_discourse_md

* docs: Add translation file generation with Justfile

* docs: Prefix url replacements with site-url in replace-urls.py preprocessor

* docs: Add installation guides

docs: Replace print button

* Revert "docs: Prefix url replacements with site-url in replace-urls.py preprocessor"

This reverts commit a685de4dce.

* Reapply "docs: Prefix url replacements with site-url in replace-urls.py preprocessor"

This reverts commit 777d8055ea.

* docs: fix replace-urls.py

* docs: fix fetch_discourse_md.py hitting discourse ip_10_secs_limit

* ci(docs): Remove duplicate '/' in build translation step

* ci(docs): Update actions/cache

* ci(docs): Reduce deploy_docs schedule timespan between triggers

* docs: update install-deps.sh

* docs: Update Advanced docs

* docs: Add favicon

* docs: Reword unstable documentation warning

* docs: Change default theme to 'navy'

* ci(docs): Move permisions to job scope

* docs: refactor fetch_discourse_md.py

Now it will export the function 'fetch', which other python scripts can
use

* docs: Add mkdocs skeleton

* docs: Add cmdrun hook

* ci(docs): Migrade deploy_docs to use mkdocs

* chore: remove mdbook leftover files

* docs: add support for markdown emojies

* docs: add support for i18n translations to mkdocs

* docs: add resource prefetching

* docs: enable navigation indexes in toc

* docs: add unstable documentation warning

* docs: normalize toc

docs: Add markdown magiclinks

* docs: remove unnecesary extensions

* ci(docs): Separate docs build into its own action

* ci(docs): fix build docs action

* ci(docs): Add default parameters to build_mkdocs action

* ci(docs): Clean up leftover mdbook files

* docs: remove leftover mkdocs-print-site-plugin

* chore: add mkdocs offline documentation

* docs: fix list indentation

* ci(docs): Add github links to mkdocs

* ci(docs): Add github authors to mkdocs

* docs: Update documentation guide and scripts to mkdocs

* docs: Add cache capabilities to cmdrun hook

* docs: Enable instant loading

docs: Enable toc in sidebar

* docs: Update summary and add more posts

* docs: Add mkdocs-material social plugin

* docs: Disable instant loading

* docs: Fix section url

* docs: Fix fetch_discourse not fetching images properly

* docs: Disable warning for using absolute links

* docs: Add url replacement hook

* docs: Restore 'General' section

* docs: Remove aditional languages for now

* docs: Add missing page titles

* docs: move and rename index.md to docs/src/Handheld_and_HTPC_edition/Steam_Gaming_Mode.md

* docs: remove leftover Bazzite_resources.md

* docs: Add time fallback to git-revision-date

* docs: Add navigation tabs

* docs: Clear cmdrun cache with Justfile

* docs: Add missing dual-boot guide url

* docs: Change to a shorter section name for handheld and HTPC

* docs: Add embed_youtube hook

* docs: Remove leftover resources entry in index

docs: Fix outdated 'Steam Gaming Overview' link in index

* docs: Limit vertical image size

* docs: add more url replacements

* docs: Enable search features

2024-08-28 15:48:19 -07:00

5.7 KiB

Raw Blame History

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 docs directory
```
$ cd docs
```
Get sure we have fetch_discourse_md.py in 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-copy
```
Normally, fetch_discourse_md.py would dump the resulting markdown doc in the terminal output, with wl-copy we 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

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.

5.7 KiB Raw Blame History