Contributing to Bazzite MkDocs documentation

• Contributing to Bazzite MkDocs documentation
  • Introduction
  • Documentation Guidelines
    • 1. Internal links
    • 2. Avoid using h1 headers (#) in pages
  • What is MkDocs
  • Setup MkDocs tooling
    • 1. Create the markdown file where we will store our document.
    • 2. Set a proper page name
  • How to add images to embeds
  • Translate documentation

Introduction

This is a guide that will show you how to write documentation.

Documentation Guidelines

1. Internal links

Do not utilize absolute urls pointing to internal pages in the documentation (https://docs.bazzite.gg).

Instead:

• Use relative paths
  • ./index.md
  • ../Handheld_and_HTPC_edition/Steam_Gaming_Mode.md
• Use absolute paths*
  • /General/Installation_Guide/Installing_Bazzite_for_Handheld_PCs.md

* Absolute paths are relative to the docs_dir declared in mkdocs.yml. In this case, src/.

2. Avoid using h1 headers (#) in pages

Instead, use h2 headers (##).

If you really need to, use # only and exclusively for page titles, and only once per page.

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 can't 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 utils/install-deps.sh

Dependencies list
^{Ignore if using install-deps.sh}

• uv (can be installed with Homebrew)
• Just (preinstalled in all Universal Blue images)

To run the MkDocs dev-server to preview the Bazzite documentation, run this:

just mkdocs serve

You will need other tools as well, like:

• A markdown compatible code editor (ex.: Visual Studio Code)
• git (comes preinstalled in most Linux distributions)

1. Create the markdown file where we will store our document.

⚠️ 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 _

2. 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"
---

How to add images to embeds

Reference: #34

Attach the necesary parameters to the markdown page, in the yaml metadata

---
# Simple
# Uses a default blend setting with purple and crops
preview: ../img/distrobox.png
description: |
  Distrobox is ...
---

or

---
# Expanded
preview:
  src: ../img/distrobox.png
  alpha: 150 # from 0 (invisible) to 255 (fully visible)
  contain: True # For images with transparent sides only, center the image without cropping
description: |
  Distrobox is ...
---

We can use the first image found in a page as a fallback. Set use_image_from_page to true in mkdocs.yml:

plugins:
  - bazzite-social:
      use_image_from_page: true # Use first image found in a page as fallback

Translate documentation

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 can't 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

MkDocs should show a language selector in the top bar.