The Linux desktop has excellent documentation. It is also spread across a dozen projects. This page collects the sources worth bookmarking, with a bias toward primary documentation and maintained projects.
| Resource |
Why it matters |
| freedesktop.org specifications |
The index of XDG, desktop entry, MIME, icon, trash, notification, and MPRIS specs |
| XDG Base Directory |
Where config, data, state, cache, and runtime files belong |
| Desktop Entry |
The .desktop file format |
| Shared MIME-info |
File type detection and MimeType= |
| Icon Theme |
hicolor and icon naming |
| Trash |
Safe deletion |
| Autostart |
Login startup entries |
| Notifications |
Desktop notification protocol |
| MPRIS |
Media player controls |
| Secret Service |
Keyring access |
| Wayland |
Protocol documentation and compositor architecture |
| XDG Desktop Portal |
Portal interfaces and usage |
| AppStream |
Metadata for software centers |
| systemd |
User services, timers, journald, coredump |
| systemd user units |
Running background services per user |
The guide’s practical workflow is in User Documentation. These are the primary sources behind it. The guide’s own house rules are in the Style Guide.
| Resource |
Why it matters |
| ISO/IEC/IEEE 26514:2022 |
Design and development of information for users; the software-documentation backbone |
| ISO 24495-1:2023 |
Plain-language principles: relevant, findable, understandable, usable |
| ISO/IEC/IEEE 26513:2017 |
Reviewing and testing information for users |
| IEC/IEEE 82079-1:2019 |
Horizontal principles for product information, when a contract or regulated market requires them |
| ISO 9241-11:2018 |
Usability vocabulary for task-based evaluation |
| WCAG 2.2 |
Accessible HTML documentation and in-app help |
| EN 301 549 V4.1.1 |
EU accessibility requirements, including documentation and support services |
| Diátaxis |
Structure model for tutorials, how-to guides, reference, and explanation |
| Resource |
Why it matters |
| Ubuntu for Developers |
Toolchains, IDEs, packaging, and support |
| Ubuntu Desktop documentation |
Desktop behavior, accessibility, and snap/deb policy |
| Ubuntu 26.04 release notes |
The baseline for this guide |
| Ubuntu Pro Client |
pro, ESM, Livepatch, FIPS, CIS |
| Snap documentation |
snapd, confinement, interfaces, updates |
| Snapcraft |
Building snaps |
| Rockcraft |
Ubuntu-based OCI images |
| Ubuntu packaging guide |
deb packaging |
| New package guide |
Ubuntu archive process |
| Build packages in a PPA |
PPA upload and signing |
| Ubuntu accessibility stack |
AT-SPI, GTK, Orca, BRLTTY |
| AppArmor |
Confinement profiles and auditing |
| Polkit |
Privileged actions |
| NetworkManager |
Connectivity and network state |
| PipeWire |
Audio/video graph |
| WirePlumber |
PipeWire session/policy manager |
| UPower |
Battery and power state |
| BlueZ D-Bus API |
Bluetooth |
| OpenPrinting CUPS |
Printing |
| UDisks2 API |
Disks and mounts |
| fwupd / LVFS |
Firmware updates |
| PackageKit |
Package management |
| snapd REST API |
Snap automation |
| Ubuntu Desktop snap/deb packages |
App Center package formats |
| Permissions prompting |
Security Center and Snap prompting |
| Ubuntu Insights |
Opt-in system telemetry |
| Resource |
Why it matters |
| Flatpak documentation |
Sandbox, manifests, runtimes, portals |
| Flatpak runtimes |
Runtime branches and support windows |
| Flatpak Builder |
Manifest format and build workflow |
| Flathub documentation |
Submission, maintenance, verification |
| Flathub requirements |
What gets accepted |
| Flathub metainfo guidelines |
Metadata, screenshots, branding, translations |
| Flathub quality guidelines |
Store-listing quality targets |
| Flathub linter |
Manifest and metainfo validation |
| Flathub submission |
The PR process |
| AppStream documentation |
Metadata, validation, screenshots |
| AppStream validator issue tags |
Exact appstreamcli issue names |
| Debian Policy |
The deb package contract |
| Debian packaging tutorial |
Practical deb building |
| Ubuntu packaging |
Ubuntu-specific packaging |
| Launchpad PPAs |
Personal package archives |
| Snapcraft documentation |
Snap packaging and confinement |
| AppImage documentation |
Portable single-file apps |
The guide is published for human readers and agents from the same source. The agent-facing files are generated at build time, so they cannot drift from the HTML.
- llms.txt — curated index grouped by section, with links to every Markdown page.
- llms-full.txt — the complete guide in one Markdown file.
- Per-page Markdown — append
.md to a route: /start/why-linux.md, /platform/ubuntu.md, /reference/baseline.md.
- Discovery — every HTML page advertises its Markdown sibling with
<link rel="alternate" type="text/markdown"> and points to /llms.txt with rel="describedby".
- Local MCP server —
npm run mcp:docs starts a read-only stdio server with search_docs, get_page, list_pages, get_related, and get_baseline.
The MCP server runs locally over stdio; the project does not operate a remote endpoint. Content negotiation (Accept: text/markdown) depends on host or CDN support and is not enabled by the static site. The .md endpoints work on any static host.
- Prefer primary documentation over blog posts.
- Check the release notes for the toolkit version you target.
- Re-test links and commands at least once per release cycle.
- If a tool is unmaintained, say so and point to the replacement.
- When in doubt, read the specification. It is shorter than the argument.
- Check the Ubuntu release notes and release cycle; note any support-date discrepancy.
- Check GNOME/GTK/libadwaita, Qt/KDE, Snapcraft, Flatpak, and Flathub release notes for the versions you target.
- Update
src/data/baseline.json and reference/baseline.mdx together.
- Re-check the pages that cite the changed versions or channels.
- Run
npm run check:baseline, npm run build, npm run check:agent-docs, and npm run test:docs-mcp.
- Re-run the external link check and the internal link/anchor check.
- Review the diff for unsourced claims, vendor promotion, and Apple/macOS/Windows comparisons.
- Record the review date and the sources you checked.
Back to The Native Standard or Checklists.
