> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/niri-wm/niri/llms.txt
> Use this file to discover all available pages before exploring further.

# Documenting niri

> Guidelines for writing and maintaining niri documentation across GitHub wiki, markdown previews, and the documentation site

## Overview

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

<CardGroup cols={3}>
  <Card title="GitHub Preview" icon="markdown">
    The GitHub repo's markdown file preview
  </Card>

  <Card title="GitHub Wiki" icon="book">
    [The GitHub repo's wiki](https://github.com/niri-wm/niri/wiki)
  </Card>

  <Card title="Documentation Site" icon="globe">
    [The documentation site](https://niri-wm.github.io/niri/)
  </Card>
</CardGroup>

## The GitHub Wiki

This is generated with the `publish-wiki` job in `.github/workflows/ci.yml`.

<Tip>
  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.
</Tip>

## The Documentation Site

The documentation site is generated with [mkdocs](https://www.mkdocs.org/). The configuration files are found in `docs/`.

<Info>
  To set up and run the documentation site locally, it is recommended to use [uv](https://docs.astral.sh/uv/).
</Info>

### Serving the Site Locally with uv

<Steps>
  <Step title="Navigate to docs directory">
    ```bash theme={null}
    cd docs/
    ```
  </Step>

  <Step title="Sync dependencies">
    ```bash theme={null}
    uv sync
    ```
  </Step>

  <Step title="Run mkdocs server">
    ```bash theme={null}
    uv run mkdocs serve
    ```

    The documentation site should now be available on [http://127.0.0.1:8000/niri/](http://127.0.0.1:8000/niri/)
  </Step>
</Steps>

<Note>
  Changes made to the documentation while the development server is running will cause an automatic page refresh in the browser.
</Note>

<Tip>
  **Images may not be visible**, as they are stored on Git LFS.

  If this is the case, run:

  ```bash theme={null}
  git lfs pull
  ```
</Tip>

## 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.

### Links

<Card title="Link guidelines" icon="link">
  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`).
</Card>

<Warning>
  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.
</Warning>

### Admonitions

<Note>
  **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](https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax#alerts).
</Note>

The above admonition is written like this:

```markdown theme={null}
> [!IMPORTANT]
> This is an important distinction from other `mkdocs`-based documentation you might have encountered.
```

**Available admonition types:**

<Tabs>
  <Tab title="NOTE">
    ```markdown theme={null}
    > [!NOTE]
    > Useful information that users should know.
    ```
  </Tab>

  <Tab title="TIP">
    ```markdown theme={null}
    > [!TIP]
    > Helpful advice for doing things better.
    ```
  </Tab>

  <Tab title="IMPORTANT">
    ```markdown theme={null}
    > [!IMPORTANT]
    > Key information users need to know.
    ```
  </Tab>

  <Tab title="WARNING">
    ```markdown theme={null}
    > [!WARNING]
    > Urgent info that needs immediate attention.
    ```
  </Tab>

  <Tab title="CAUTION">
    ```markdown theme={null}
    > [!CAUTION]
    > Advises about risks or negative outcomes.
    ```
  </Tab>
</Tabs>

### Images

Images should have relative links to resources in `docs/wiki/img/`, and should contain sensible alt-text.

```markdown theme={null}
![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.

```html theme={null}
<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.

<Tabs>
  <Tab title="KDL Config">
    If the language used in the snippet is KDL, open the code block like this:

    ````markdown theme={null}
    ```kdl
    layout {
        gaps 16
    }
    ```
    ````
  </Tab>

  <Tab title="Bash/Shell">
    For shell commands:

    ````markdown theme={null}
    ```bash
    niri --version
    ```
    ````
  </Tab>

  <Tab title="Rust">
    For Rust code:

    ````markdown theme={null}
    ```rust
    pub fn example() {
        println!("Hello, niri!");
    }
    ```
    ````
  </Tab>
</Tabs>

## Best Practices

<AccordionGroup>
  <Accordion title="Test your documentation locally">
    Always run `mkdocs serve` locally to verify that:

    * All links work correctly
    * Images display properly
    * Admonitions render as expected
    * No build errors occur
  </Accordion>

  <Accordion title="Use relative links">
    Always use relative links for internal documentation references.

    This ensures links work correctly across all three viewing platforms (GitHub preview, wiki, and docs site).
  </Accordion>

  <Accordion title="Include alt text for images">
    Always provide meaningful alt text for images to improve accessibility and help users understand content when images don't load.
  </Accordion>

  <Accordion title="Annotate code blocks">
    Always specify the language for code blocks to enable proper syntax highlighting across all platforms.
  </Accordion>
</AccordionGroup>

## Contributing Documentation

<Info>
  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
</Info>

<Note>
  For more information on contributing to niri, see the [CONTRIBUTING.md](https://github.com/niri-wm/niri/blob/main/CONTRIBUTING.md) file.
</Note>