72 files changed, 1317 insertions, 41 deletions
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 93713dff..ff10b677 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -291,21 +291,10 @@ jobs:
       - run: nix flake check
         continue-on-error: true
 
-  check-links:
-    runs-on: ubuntu-24.04
-    steps:
-      - uses: actions/checkout@v4
-        with:
-          show-progress: false
-      - uses: lycheeverse/lychee-action@v2.0.2 # later versions break fragment checks. don't bump until this is fixed: https://github.com/lycheeverse/lychee/issues/1574
-        with:
-          args: --offline --include-fragments 'wiki/*.md'
-
   publish-wiki:
     if: github.event_name == 'push' && github.ref == 'refs/heads/main'
     needs:
-      - build
-      - check-links
+      - publish-docs
     permissions:
       contents: write
     runs-on: ubuntu-24.04
@@ -315,28 +304,39 @@ jobs:
           lfs: true
           show-progress: false
       - uses: Andrew-Chen-Wang/github-wiki-action@b7e552d7cb0fa7f83e459012ffc6840fd87bcb83
+        with:
+          path: docs/wiki/
 
-  rustdoc:
-    needs: build
-    permissions:
-      contents: write
+  publish-docs:
+    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+    needs:
+      - build
     runs-on: ubuntu-24.04
     steps:
       - uses: actions/checkout@v4
         with:
+          lfs: true
           show-progress: false
-
+      - name: Install uv
+        uses: astral-sh/setup-uv@v6
+        with:
+            enable-cache: true
+      - name: Install the project
+        run: uv sync --locked --all-extras --dev
+        working-directory: docs/
+      - name: Generate niri documentation
+        run: uv run mkdocs build
+        working-directory: docs/
       - uses: dtolnay/rust-toolchain@stable
-
-      - name: Generate documentation
+      - name: Generate rustdoc documentation
         run: cargo doc --no-deps -p niri-ipc
-
-      - run: cp ./resources/rustdoc-index.html ./target/doc/index.html
-
+      - run: mkdir -p publish/niri_ipc
+      - run: cp -r ./target/doc/* ./publish/
+      - run: cp -r ./docs/site/* ./publish/
       - name: Deploy documentation
         if: github.ref == 'refs/heads/main'
         uses: peaceiris/actions-gh-pages@v4
         with:
           github_token: ${{ secrets.GITHUB_TOKEN }}
-          publish_dir: ./target/doc
-          force_orphan: true
+          publish_dir: ./publish
+          force_orphan: true
+\ No newline at end of file
diff --git a/docs/.gitignore b/docs/.gitignore
new file mode 100644
index 00000000..6c3abe6c
--- /dev/null
+++ b/docs/.gitignore
@@ -0,0 +1,2 @@
+site
+__pycache__
+\ No newline at end of file
diff --git a/docs/hooks/remove-must-fail.py b/docs/hooks/remove-must-fail.py
new file mode 100644
index 00000000..3284b10d
--- /dev/null
+++ b/docs/hooks/remove-must-fail.py
@@ -0,0 +1,19 @@
+from __future__ import annotations
+import re
+
+# todo: this could be done generically, so that any 
+# ```language,annotation,anything-else 
+# is reduced to
+# ```language
+# which is what's supported by mkdocs/pygments
+# also note: mkdocs provides ways to highlight lines, add line numbers
+# but these are added as 
+# ```language linenums="1"
+# and not split by comma
+def on_page_markdown(
+    markdown: str, *, page, config, files
+):
+    return re.sub(
+        r",must-fail",
+        '', markdown, flags = re.I | re.M
+    )
+\ No newline at end of file
diff --git a/docs/hooks/shortcodes.py b/docs/hooks/shortcodes.py
new file mode 100644
index 00000000..66f5c43e
--- /dev/null
+++ b/docs/hooks/shortcodes.py
@@ -0,0 +1,44 @@
+# Copyright (c) 2016-2025 Martin Donath <martin.donath@squidfunk.com>
+
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to
+# deal in the Software without restriction, including without limitation the
+# rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
+# sell copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+
+# The above copyright notice and this permission notice shall be included in
+# all copies or substantial portions of the Software.
+
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+# FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
+# IN THE SOFTWARE.
+
+from __future__ import annotations
+import re
+from re import Match
+
+def on_page_markdown(
+    markdown: str, *, page, config, files
+):
+    def replace(match: Match):
+        matches = match.groups()
+        preposition, version = matches[0], matches[1]
+        return _badge_for_version(preposition, version)
+
+    return re.sub(
+        r"<sup>(Until|Since): (.*?)</sup>",
+        replace, markdown, flags = re.I | re.M
+    )
+
+def _badge_for_version(preposition: str, version: str):
+    if version == "next release":
+        # we might fail to make real links to release notes on other cases too, but for now this is the one i've found
+        return f"<span class=\"badge\">{preposition}: {version}</span>"
+    else:
+        path = f"https://github.com/YaLTeR/niri/releases/tag/v{version}"
+        return f"<span class=\"badge\">[{preposition}: {version}]({path})</span>"
diff --git a/docs/mkdocs.yaml b/docs/mkdocs.yaml
new file mode 100644
index 00000000..cbd323ad
--- /dev/null
+++ b/docs/mkdocs.yaml
@@ -0,0 +1,107 @@
+site_name: niri
+docs_dir: wiki
+site_url: https://yalter.github.io/niri
+repo_url: https://github.com/YaLTeR/niri
+edit_uri: edit/main/docs/wiki/
+use_directory_urls: false
+
+theme:
+  name: material
+  logo: _assets/icons/logo.svg
+  favicon: _assets/icons/logo.svg
+  features:
+    - navigation.instant
+    - search.suggest
+    - content.code.copy
+    - content.action.edit
+  palette:
+    - media: "(prefers-color-scheme)"
+      primary: custom
+      toggle:
+        icon: material/brightness-auto
+        name: Switch to light mode
+    - media: "(prefers-color-scheme: light)"
+      primary: custom
+      scheme: default
+      toggle:
+        icon: material/brightness-7
+        name: Switch to dark mode
+    - media: "(prefers-color-scheme: dark)"
+      primary: custom
+      scheme: slate
+      toggle:
+        icon: material/brightness-4
+        name: Switch to system preference
+markdown_extensions:
+  - github-callouts
+  - pymdownx.highlight:
+      anchor_linenums: true
+      line_spans: __span
+      pygments_lang_class: true
+  - pymdownx.inlinehilite
+  - pymdownx.magiclink
+  - pymdownx.snippets
+  - pymdownx.superfences
+  - pymdownx.keys
+plugins:
+  - search
+hooks:
+  - hooks/shortcodes.py
+  - hooks/remove-must-fail.py
+extra_css:
+  - _assets/stylesheets/niri.css
+strict: true
+validation:
+  nav:
+    omitted_files: warn
+    not_found: warn
+    absolute_links: relative_to_docs
+  links:
+    not_found: warn
+    anchors: warn
+    absolute_links: relative_to_docs
+    unrecognized_links: warn
+not_in_nav: |
+  _Sidebar.md
+  Configuration:-Overview.md
+  index.md
+# ah, wouldn't it be nice if we could autogenerate this with wiki/_Sidebar.md
+nav:
+  - Usage:
+    - Getting Started: Getting-Started.md
+    - Example systemd Setup: Example-systemd-Setup.md
+    - Important Software: Important-Software.md
+    - Workspaces: Workspaces.md
+    - Floating Windows: Floating-Windows.md
+    - Tabs: Tabs.md
+    - Overview: Overview.md
+    - Screencasting: Screencasting.md
+    - Layer‐Shell Components: Layer‐Shell-Components.md
+    - IPC, niri msg: IPC.md
+    - Application-Specific Issues: Application-Issues.md
+    - Nvidia: Nvidia.md
+    - Xwayland: Xwayland.md
+    - Gestures: Gestures.md
+    - Packaging niri: Packaging-niri.md
+    - FAQ: FAQ.md
+  - Configuration:
+    - Introduction: Configuration:-Introduction.md
+    - Input: Configuration:-Input.md
+    - Outputs: Configuration:-Outputs.md
+    - Key Bindings: Configuration:-Key-Bindings.md
+    - Switch Events: Configuration:-Switch-Events.md
+    - Layout: Configuration:-Layout.md
+    - Named Workspaces: Configuration:-Named-Workspaces.md
+    - Miscellaneous: Configuration:-Miscellaneous.md
+    - Window Rules: Configuration:-Window-Rules.md
+    - Layer Rules: Configuration:-Layer-Rules.md
+    - Animations: Configuration:-Animations.md
+    - Gestures: Configuration:-Gestures.md
+    - Debug Options: Configuration:-Debug-Options.md
+  - Development:
+    - Design Principles: Development:-Design-Principles.md
+    - Developing niri: Development:-Developing-niri.md
+    - Documenting niri: Development:-Documenting-niri.md
+    - Fractional Layout: Development:-Fractional-Layout.md
+    - Redraw Loop: Development:-Redraw-Loop.md
+    - Animation Timing: Development:-Animation-Timing.md
diff --git a/docs/pyproject.toml b/docs/pyproject.toml
new file mode 100644
index 00000000..d80a9c17
--- /dev/null
+++ b/docs/pyproject.toml
@@ -0,0 +1,14 @@
+[project]
+name = "niri-docs"
+version = "0.1.0"
+requires-python = ">=3.10"
+dependencies = [
+    "markdown-callouts>=0.4.0",
+    "mkdocs-material>=9.6.15",
+    "pygments",
+]
+
+# for KDL highlighting support
+# TODO: use the official pygments package once https://github.com/pygments/pygments/pull/2936 is merged
+[tool.uv.sources]
+pygments = { git = "https://github.com/chinatsu/pygments", rev = "0f0b0d4da2839e1285881389155bb4605a0a6dc4" }
diff --git a/docs/uv.lock b/docs/uv.lock
new file mode 100644
index 00000000..a4381a3c
--- /dev/null
+++ b/docs/uv.lock
@@ -0,0 +1,511 @@
+version = 1
+revision = 3
+requires-python = ">=3.10"
+
+[[package]]
+name = "babel"
+version = "2.17.0"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/7d/6b/d52e42361e1aa00709585ecc30b3f9684b3ab62530771402248b1b1d6240/babel-2.17.0.tar.gz", hash = "sha256:0c54cffb19f690cdcc52a3b50bcbf71e07a808d1c80d549f2459b9d2cf0afb9d", size = 9951852, upload-time = "2025-02-01T15:17:41.026Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/b7/b8/3fe70c75fe32afc4bb507f75563d39bc5642255d1d94f1f23604725780bf/babel-2.17.0-py3-none-any.whl", hash = "sha256:4d0b53093fdfb4b21c92b5213dba5a1b23885afa8383709427046b21c366e5f2", size = 10182537, upload-time = "2025-02-01T15:17:37.39Z" },
+]
+
+[[package]]
+name = "backrefs"
+version = "5.9"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/eb/a7/312f673df6a79003279e1f55619abbe7daebbb87c17c976ddc0345c04c7b/backrefs-5.9.tar.gz", hash = "sha256:808548cb708d66b82ee231f962cb36faaf4f2baab032f2fbb783e9c2fdddaa59", size = 5765857, upload-time = "2025-06-22T19:34:13.97Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/19/4d/798dc1f30468134906575156c089c492cf79b5a5fd373f07fe26c4d046bf/backrefs-5.9-py310-none-any.whl", hash = "sha256:db8e8ba0e9de81fcd635f440deab5ae5f2591b54ac1ebe0550a2ca063488cd9f", size = 380267, upload-time = "2025-06-22T19:34:05.252Z" },
+    { url = "https://files.pythonhosted.org/packages/55/07/f0b3375bf0d06014e9787797e6b7cc02b38ac9ff9726ccfe834d94e9991e/backrefs-5.9-py311-none-any.whl", hash = "sha256:6907635edebbe9b2dc3de3a2befff44d74f30a4562adbb8b36f21252ea19c5cf", size = 392072, upload-time = "2025-06-22T19:34:06.743Z" },
+    { url = "https://files.pythonhosted.org/packages/9d/12/4f345407259dd60a0997107758ba3f221cf89a9b5a0f8ed5b961aef97253/backrefs-5.9-py312-none-any.whl", hash = "sha256:7fdf9771f63e6028d7fee7e0c497c81abda597ea45d6b8f89e8ad76994f5befa", size = 397947, upload-time = "2025-06-22T19:34:08.172Z" },
+    { url = "https://files.pythonhosted.org/packages/10/bf/fa31834dc27a7f05e5290eae47c82690edc3a7b37d58f7fb35a1bdbf355b/backrefs-5.9-py313-none-any.whl", hash = "sha256:cc37b19fa219e93ff825ed1fed8879e47b4d89aa7a1884860e2db64ccd7c676b", size = 399843, upload-time = "2025-06-22T19:34:09.68Z" },
+    { url = "https://files.pythonhosted.org/packages/fc/24/b29af34b2c9c41645a9f4ff117bae860291780d73880f449e0b5d948c070/backrefs-5.9-py314-none-any.whl", hash = "sha256:df5e169836cc8acb5e440ebae9aad4bf9d15e226d3bad049cf3f6a5c20cc8dc9", size = 411762, upload-time = "2025-06-22T19:34:11.037Z" },
+    { url = "https://files.pythonhosted.org/packages/41/ff/392bff89415399a979be4a65357a41d92729ae8580a66073d8ec8d810f98/backrefs-5.9-py39-none-any.whl", hash = "sha256:f48ee18f6252b8f5777a22a00a09a85de0ca931658f1dd96d4406a34f3748c60", size = 380265, upload-time = "2025-06-22T19:34:12.405Z" },
+]
+
+[[package]]
+name = "certifi"
+version = "2025.7.14"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/b3/76/52c535bcebe74590f296d6c77c86dabf761c41980e1347a2422e4aa2ae41/certifi-2025.7.14.tar.gz", hash = "sha256:8ea99dbdfaaf2ba2f9bac77b9249ef62ec5218e7c2b2e903378ed5fccf765995", size = 163981, upload-time = "2025-07-14T03:29:28.449Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/4f/52/34c6cf5bb9285074dc3531c437b3919e825d976fde097a7a73f79e726d03/certifi-2025.7.14-py3-none-any.whl", hash = "sha256:6b31f564a415d79ee77df69d757bb49a5bb53bd9f756cbbe24394ffd6fc1f4b2", size = 162722, upload-time = "2025-07-14T03:29:26.863Z" },
+]
+
+[[package]]
+name = "charset-normalizer"
+version = "3.4.2"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/e4/33/89c2ced2b67d1c2a61c19c6751aa8902d46ce3dacb23600a283619f5a12d/charset_normalizer-3.4.2.tar.gz", hash = "sha256:5baececa9ecba31eff645232d59845c07aa030f0c81ee70184a90d35099a0e63", size = 126367, upload-time = "2025-05-02T08:34:42.01Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/95/28/9901804da60055b406e1a1c5ba7aac1276fb77f1dde635aabfc7fd84b8ab/charset_normalizer-3.4.2-cp310-cp310-macosx_10_9_universal2.whl", hash = "sha256:7c48ed483eb946e6c04ccbe02c6b4d1d48e51944b6db70f697e089c193404941", size = 201818, upload-time = "2025-05-02T08:31:46.725Z" },
+    { url = "https://files.pythonhosted.org/packages/d9/9b/892a8c8af9110935e5adcbb06d9c6fe741b6bb02608c6513983048ba1a18/charset_normalizer-3.4.2-cp310-cp310-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:b2d318c11350e10662026ad0eb71bb51c7812fc8590825304ae0bdd4ac283acd", size = 144649, upload-time = "2025-05-02T08:31:48.889Z" },
+    { url = "https://files.pythonhosted.org/packages/7b/a5/4179abd063ff6414223575e008593861d62abfc22455b5d1a44995b7c101/charset_normalizer-3.4.2-cp310-cp310-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl", hash = "sha256:9cbfacf36cb0ec2897ce0ebc5d08ca44213af24265bd56eca54bee7923c48fd6", size = 155045, upload-time = "2025-05-02T08:31:50.757Z" },
+    { url = "https://files.pythonhosted.org/packages/3b/95/bc08c7dfeddd26b4be8c8287b9bb055716f31077c8b0ea1cd09553794665/charset_normalizer-3.4.2-cp310-cp310-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:18dd2e350387c87dabe711b86f83c9c78af772c748904d372ade190b5c7c9d4d", size = 147356, upload-time = "2025-05-02T08:31:52.634Z" },
+    { url = "https://files.pythonhosted.org/packages/a8/2d/7a5b635aa65284bf3eab7653e8b4151ab420ecbae918d3e359d1947b4d61/charset_normalizer-3.4.2-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:8075c35cd58273fee266c58c0c9b670947c19df5fb98e7b66710e04ad4e9ff86", size = 149471, upload-time = "2025-05-02T08:31:56.207Z" },
+    { url = "https://files.pythonhosted.org/packages/ae/38/51fc6ac74251fd331a8cfdb7ec57beba8c23fd5493f1050f71c87ef77ed0/charset_normalizer-3.4.2-cp310-cp310-manylinux_2_5_i686.manylinux1_i686.manylinux_2_17_i686.manylinux2014_i686.whl", hash = "sha256:5bf4545e3b962767e5c06fe1738f951f77d27967cb2caa64c28be7c4563e162c", size = 151317, upload-time = "2025-05-02T08:31:57.613Z" },
+    { url = "https://files.pythonhosted.org/packages/b7/17/edee1e32215ee6e9e46c3e482645b46575a44a2d72c7dfd49e49f60ce6bf/charset_normalizer-3.4.2-cp310-cp310-musllinux_1_2_aarch64.whl", hash = "sha256:7a6ab32f7210554a96cd9e33abe3ddd86732beeafc7a28e9955cdf22ffadbab0", size = 146368, upload-time = "2025-05-02T08:31:59.468Z" },
+    { url = "https://files.pythonhosted.org/packages/26/2c/ea3e66f2b5f21fd00b2825c94cafb8c326ea6240cd80a91eb09e4a285830/charset_normalizer-3.4.2-cp310-cp310-musllinux_1_2_i686.whl", hash = "sha256:b33de11b92e9f75a2b545d6e9b6f37e398d86c3e9e9653c4864eb7e89c5773ef", size = 154491, upload-time = "2025-05-02T08:32:01.219Z" },
+    { url = "https://files.pythonhosted.org/packages/52/47/7be7fa972422ad062e909fd62460d45c3ef4c141805b7078dbab15904ff7/charset_normalizer-3.4.2-cp310-cp310-musllinux_1_2_ppc64le.whl", hash = "sha256:8755483f3c00d6c9a77f490c17e6ab0c8729e39e6390328e42521ef175380ae6", size = 157695, upload-time = "2025-05-02T08:32:03.045Z" },
+    { url = "https://files.pythonhosted.org/packages/2f/42/9f02c194da282b2b340f28e5fb60762de1151387a36842a92b533685c61e/charset_normalizer-3.4.2-cp310-cp310-musllinux_1_2_s390x.whl", hash = "sha256:68a328e5f55ec37c57f19ebb1fdc56a248db2e3e9ad769919a58672958e8f366", size = 154849, upload-time = "2025-05-02T08:32:04.651Z" },
+    { url = "https://files.pythonhosted.org/packages/67/44/89cacd6628f31fb0b63201a618049be4be2a7435a31b55b5eb1c3674547a/charset_normalizer-3.4.2-cp310-cp310-musllinux_1_2_x86_64.whl", hash = "sha256:21b2899062867b0e1fde9b724f8aecb1af14f2778d69aacd1a5a1853a597a5db", size = 150091, upload-time = "2025-05-02T08:32:06.719Z" },
+    { url = "https://files.pythonhosted.org/packages/1f/79/4b8da9f712bc079c0f16b6d67b099b0b8d808c2292c937f267d816ec5ecc/charset_normalizer-3.4.2-cp310-cp310-win32.whl", hash = "sha256:e8082b26888e2f8b36a042a58307d5b917ef2b1cacab921ad3323ef91901c71a", size = 98445, upload-time = "2025-05-02T08:32:08.66Z" },
+    { url = "https://files.pythonhosted.org/packages/7d/d7/96970afb4fb66497a40761cdf7bd4f6fca0fc7bafde3a84f836c1f57a926/charset_normalizer-3.4.2-cp310-cp310-win_amd64.whl", hash = "sha256:f69a27e45c43520f5487f27627059b64aaf160415589230992cec34c5e18a509", size = 105782, upload-time = "2025-05-02T08:32:10.46Z" },
+    { url = "https://files.pythonhosted.org/packages/05/85/4c40d00dcc6284a1c1ad5de5e0996b06f39d8232f1031cd23c2f5c07ee86/charset_normalizer-3.4.2-cp311-cp311-macosx_10_9_universal2.whl", hash = "sha256:be1e352acbe3c78727a16a455126d9ff83ea2dfdcbc83148d2982305a04714c2", size = 198794, upload-time = "2025-05-02T08:32:11.945Z" },
+    { url = "https://files.pythonhosted.org/packages/41/d9/7a6c0b9db952598e97e93cbdfcb91bacd89b9b88c7c983250a77c008703c/charset_normalizer-3.4.2-cp311-cp311-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:aa88ca0b1932e93f2d961bf3addbb2db902198dca337d88c89e1559e066e7645", size = 142846, upload-time = "2025-05-02T08:32:13.