How to wiki

The Garuda Linux wiki is a static Astro site built with Starlight and themed with Catppuccin Mocha / Latte. Every article is a single Markdown file, so contributing only needs a text editor and a GitLab account.

Quick start

1. Clone the repository

   git clone https://gitlab.com/garuda-linux/website/wiki.git
   cd wiki

2. Install dependencies

   The wiki needs Node.js 26 or newer and pnpm 11 or newer, set in devEngines in package.json. nix develop provides both. With direnv, run direnv allow once and the shell loads on cd.

   pnpm install

3. Start the dev server

   pnpm dev

   Open http://localhost:4321/en/. The server reloads on every saved change.

4. Verify your work before opening a merge request

   pnpm build

pnpm build runs astro check (TypeScript and content validation) and then a production build, including the internal link checker. A merge request with a failing build will not be merged.

Command reference

Command	What it does
pnpm dev	Development server with hot reload at /en/.
pnpm build	astro check + production build + link validation. Run before a MR.
pnpm check	Type and content check only, without building.
pnpm preview	Serve the built dist/ locally, closest to production.
pnpm fmt	Format the whole repository with Prettier.
nix develop	Shell with Node.js and pnpm that installs the pre-commit hooks.
nix flake check	Runs the Nix formatting and spell check, the same as the CI flake check.
nix fmt	Format and lint the Nix files with nixfmt, deadnix and statix.

The pre-commit hooks run on every commit:

• treefmt formats and lints the Nix files, the same as nix fmt.
• typos checks the spelling. Words that are correct but unknown to it, such as product names, go into _typos.toml.
• Prettier formats the staged files, the same as pnpm fmt. When it changes a file, the commit stops. Stage the formatted file and commit again.
• astro check checks types and the content schema, the same as pnpm check.
• Vale checks the writing style with the rules in .vale/styles/Garuda/: no semicolons in prose, and no sentences that name forum threads or their authors as the source. Link the source at the end of the page instead.
• The content check (pnpm check:content) fails on missing images and on a lastUpdated date in the future. It also lists unused images and pages that were not updated for 12 months.
• The shell check (pnpm check:shell) runs shellcheck on every sh and bash code block. Label config files as text or ini, not sh. A block with placeholders that are not valid shell can opt out with sh nocheck after the opening fence.

Prettier and astro check use the versions in package.json, so they need pnpm install first and skip themselves without node_modules. The CI build job runs both, plus the full pnpm build. The other checks need no npm packages and also run in nix flake check. The three migration guides are listed in .prettierignore and are skipped by Vale, so their wording and formatting never change.

Two checks need the network and run in a scheduled CI pipeline, for example once a week:

• pnpm check:packages looks up every package from a pacman -S, paru -S or yay -S command in the Arch, Garuda and Chaotic-AUR repositories and the AUR.
• lychee checks the external links with lychee.toml, one request at a time.

Project layout

• Directorysrc/

  • Directoryassets/ static images imported by articles

    • …
  • Directorycomponents/ Astro overrides of Starlight components

    • …
  • Directorycontent/

    • Directorydocs/en/ the English articles, one folder per topic, one .mdx file per page

      • …
  • content.config.ts collection and frontmatter schema
• plugins/remark-locale-links.mjs rewrites /en/ links on translated pages
• Directorypublic/ files served from the site root (_redirects, the favicons and downloadable config files)

  • …
• astro.config.ts site, theme, sidebar and locale configuration

Anatomy of a page

Each article starts with YAML frontmatter. title and sources are required, everything else is optional. Copy this template for a new page.

src/content/docs/en/example.mdx

---
title: Example article
description: Shown in search results and link previews.
tags:
  - example
lastUpdated: 2026-10-18
sources:
  - pkgbuilds/garuda-update
  - https://wiki.archlinux.org/title/Pacman
sidebar:
  order: 1
---
## First section

Body copy in Markdown.

Note

lastUpdated in the frontmatter overrides the Git date. Wiki.js shipped one per page and the importer kept it, so if you edit a page that has one, bump the date yourself. Pages without it get the date of their last Git commit.

sources lists where the facts on the page come from, so the page can be checked again later. Each entry is a Garuda GitLab repository name, optionally followed by a path inside it (for example pkgbuilds/garuda-update, iso-profiles/garuda/dr460nized or toolbox), or a full URL such as an Arch Wiki page or a forum topic. Use wiki for pages that only link to other wiki pages. The build fails when a page has no sources.

Callouts

Use Starlight asides for notes, tips and warnings. An optional [Title] replaces the default label.

:::note
Something worth knowing.
:::

:::tip[Optional title]
A shortcut or a better way of doing things.
:::

:::caution
Something that may break and how to recover.
:::

:::danger
Irreversible or destructive actions. Use sparingly.
:::

Code blocks

Always set a language so the highlighter and copy button behave. sh, bash, ini, yaml, json, conf and text are the common ones here.

```sh
garuda-update
```

text is the right choice for plain console output and file listings that are not shell commands.

Components

Starlight ships components that replace plain link lists and long instructions.

import {
  Card,
  CardGrid,
  LinkCard,
  Steps,
  Tabs,
  TabItem,
} from "@astrojs/starlight/components";

<CardGrid>
  <LinkCard title="Garuda Update" href="/en/maintenance/garuda-update/" />
  <LinkCard title="Snapshots" href="/en/maintenance/restoring-snapshots/" />
</CardGrid>

Adding a page

1. Create the file in the topic folder under src/content/docs/en/ where it belongs. File names are lowercase kebab-case (this-is-a-page.mdx). The path becomes the URL, so en/gaming/steam.mdx is served at /en/gaming/steam/.
2. Add frontmatter with at least a title and sources. Use the template above.
3. Set sidebar.order in the frontmatter to place the page within its group. The sidebar is generated from the folders, so astro.config.ts only needs a change for a new top-level folder.
4. Run pnpm build and fix anything the checker reports.
5. Commit with a conventional commit message, for example docs(gaming): add the Steam page or fix(boot): correct the bootloader ID. Run cz commit inside nix develop to write one with Commitizen. The commit hook rejects other messages, and the CI checks the commit title again.
6. Push to your fork and open a merge request. Check that its pipeline passes.

Images

Put images in a folder under src/assets/ that mirrors the page path, for example src/assets/hardware/touchpad-gestures/ for en/hardware/touchpad-gestures.mdx. Section index pages use an index folder, for example src/assets/gaming/index/. Images that more than one page uses go in src/assets/shared/. Reference them with the ~/assets/ alias, which works from every page and every language. Prefer WebP or PNG screenshots, and keep file sizes small.

![KDE Plasma display settings](~/assets/hardware/touchpad-gestures/kde-display.png)

Links and redirects

• Internal links are written as absolute site paths, for example /en/maintenance/garuda-update/.
• plugins/remark-locale-links.mjs rewrites the /en/ prefix on translated pages, so write the English path once and it adapts per locale.
• Moved or renamed a page? Add a 301 rule to public/_redirects so old URLs keep working.
• pnpm build fails on broken internal links. Fix them rather than removing the validator.

Translations

Translations run through Transifex, the same way as the other Garuda projects:

1. transifex.yml in the repository root tells the Transifex GitLab integration that the English pages in src/content/docs/en/ and the UI strings in src/content/i18n/en.json are the source.
2. Transifex pushes finished translations to a translations_* branch. Pages go to src/content/docs/<lang>/, UI strings to src/content/i18n/<lang>.json.
3. The transifex-automerge job from gitlab-ci-commons, included in .gitlab-ci.yml, merges that branch into the default branch.
4. astro.config.ts turns every folder next to en/ into a locale, labelled with the language’s own name. Pages that are not translated yet fall back to English, and plugins/remark-locale-links.mjs keeps links inside the reader’s language.
5. In CI, Lunaria compares the git dates of every translation with its English page. /localization shows which pages are translated, missing or outdated, and an outdated page links to the current English page in its translation notice. Lunaria fails on uncommitted changes, so local builds skip both.

Never edit translated files by hand. Fix the English page or the translation in Transifex instead.

Caution

A malformed translation can break the MDX parse of that page, for example a changed component tag or import line. The build fails and shows the page. Fix the string in Transifex and let it push again.

Troubleshooting

Astro cannot write its telemetry or the pnpm store inside a container

Point both at a writable directory:

export ASTRO_TELEMETRY_DISABLED=1
export XDG_RUNTIME_DIR="$TMPDIR/run"

The site root shows a 404 in the dev server

Expected. The root redirect to /en/ only exists on Cloudflare Pages, so use /en/ locally.