Skip to main content

​
Overview

niri’s documentation files are found in docs/wiki/ and should be viewable and browsable in at least three systems:

GitHub Preview

The GitHub repo’s markdown file preview

GitHub Wiki

The GitHub repo’s wiki

Documentation Site

The documentation site

​
The GitHub Wiki

This is generated with the publish-wiki job in .github/workflows/ci.yml.
In order to have this job run as expected in your fork, you’ll need to enable the wiki feature in your repo’s settings on GitHub.This could be useful as a contributor to verify that the wiki generates the way you expect it to.

​
The Documentation Site

The documentation site is generated with mkdocs. The configuration files are found in docs/.
To set up and run the documentation site locally, it is recommended to use uv.

​
Serving the Site Locally with uv

1

Navigate to docs directory

cd docs/
2

Sync dependencies

uv sync
3

Run mkdocs server

uv run mkdocs serve
The documentation site should now be available on http://127.0.0.1:8000/niri/
Changes made to the documentation while the development server is running will cause an automatic page refresh in the browser.
Images may not be visible, as they are stored on Git LFS.If this is the case, run:
git lfs pull

​
Documentation Elements

Elements such as links, admonitions, images, and snippets should work as expected in markdown file previews on GitHub, the GitHub repo’s wiki, and in the documentation site.

Link guidelines

Links should in all cases be relative (e.g. ./FAQ.md), unless it’s an external one.Links should have anchors if they are meant to lead the user to a specific section on a page (e.g. ./Getting-Started.md#nvidia).
mkdocs will terminate if relative links lead to non-existing documents or non-existing anchors.This means that the CI pipeline will fail when building documentation, as will mkdocs serve locally.

​
Admonitions

This is an important distinction from other mkdocs-based documentation you might have encountered.Admonitions, or alerts should be written the way GitHub defines them.
The above admonition is written like this: 
> [!IMPORTANT]
> This is an important distinction from other `mkdocs`-based documentation you might have encountered.
Available admonition types: 
> [!NOTE]
> Useful information that users should know.

​
Images

Images should have relative links to resources in docs/wiki/img/, and should contain sensible alt-text. 
![Alt text description](./img/screenshot.png)

​
Videos

For compatibility with both mkdocs and GitHub Wiki, videos need to be wrapped in a <video> tag (displayed by mkdocs) and have the video link again as fallback text (displayed by GitHub Wiki) padded with blank lines. 
<video controls src="https://github.com/user-attachments/assets/379a5d1f-acdb-4c11-b36c-e85fd91f0995">

https://github.com/user-attachments/assets/379a5d1f-acdb-4c11-b36c-e85fd91f0995

</video>

​
Snippets

Configuration and code snippets in general should be annotated with a language.
If the language used in the snippet is KDL, open the code block like this:
```kdl
layout {
    gaps 16
}
```

​
Best Practices

Always run mkdocs serve locally to verify that:
  • All links work correctly
  • Images display properly
  • Admonitions render as expected
  • No build errors occur
Always provide meaningful alt text for images to improve accessibility and help users understand content when images don’t load.
Always specify the language for code blocks to enable proper syntax highlighting across all platforms.

​
Contributing Documentation

When contributing documentation changes, make sure to:
  1. Follow the link and admonition guidelines above
  2. Test locally with mkdocs serve
  3. Verify the documentation works on all three platforms
  4. Use proper markdown formatting for code, images, and videos
For more information on contributing to niri, see the CONTRIBUTING.md file.

Build docs developers (and LLMs) love

Get started for freeTalk to us