github wiki replacement / mkdocs-docs (#2147)

* Add wiki based on mkdocs

* wording fixes

* fix github bg color on narrow

* Fix left sidebar section headers being bigger than pages

* fix hover accent

* fix list rendering on fractional layout

* fix videos

* fix automatic full links

* remove redundant commented css

* improve dark mode contrast

* update pygments for better child node coloring

* update logo

* remove blank lines

* add systemd language hint

---------

Co-authored-by: Ivan Molodetskikh <yalterz@gmail.com>

1 files changed, 75 insertions, 0 deletions

diff --git a/docs/wiki/IPC.md b/docs/wiki/IPC.md
new file mode 100644
index 00000000..813461d6
--- /dev/null
+++ b/docs/wiki/IPC.md
@@ -0,0 +1,75 @@
+You can communicate with the running niri instance over an IPC socket.
+Check `niri msg --help` for available commands.
+
+The `--json` flag prints the response in JSON, rather than formatted.
+For example, `niri msg --json outputs`.
+
+> [!TIP]
+> If you're getting parsing errors from `niri msg` after upgrading niri, make sure that you've restarted niri itself.
+> You might be trying to run a newer `niri msg` against an older `niri` compositor.
+
+### Event Stream
+
+<sup>Since: 0.1.9</sup>
+
+While most niri IPC requests return a single response, the event stream request will make niri continuously stream events into the IPC connection until it is closed.
+This is useful for implementing various bars and indicators that update as soon as something happens, without continuous polling.
+
+The event stream IPC is designed to give you the complete current state up-front, then follow up with updates to that state.
+This way, your state can never "desync" from niri, and you don't need to make any other IPC information requests.
+
+Where reasonable, event stream state updates are atomic, though this is not always the case.
+For example, a window may end up with a workspace id for a workspace that had already been removed.
+This can happen if the corresponding workspaces-changed event arrives before the corresponding window-changed event.
+
+To get a taste of the events, run `niri msg event-stream`.
+Though, this is more of a debug function than anything.
+You can get raw events from `niri msg --json event-stream`, or by connecting to the niri socket and requesting an event stream manually.
+
+You can find the full list of events along with documentation [here](https://yalter.github.io/niri/niri_ipc/enum.Event.html).
+
+### Programmatic Access
+
+`niri msg --json` is a thin wrapper over writing and reading to a socket.
+When implementing more complex scripts and modules, you're encouraged to access the socket directly.
+
+Connect to the UNIX domain socket located at `$NIRI_SOCKET` in the filesystem.
+Write your request encoded in JSON on a single line, followed by a newline character, or by flushing and shutting down the write end of the connection.
+Read the reply as JSON, also on a single line.
+
+You can use `socat` to test communicating with niri directly:
+
+```sh
+$ socat STDIO "$NIRI_SOCKET"
+"FocusedWindow"
+{"Ok":{"FocusedWindow":{"id":12,"title":"t socat STDIO /run/u ~","app_id":"Alacritty","workspace_id":6,"is_focused":true}}}
+```
+
+The reply is an `Ok` or an `Err` wrapping the same JSON object as you get from `niri msg --json`.
+
+For more complex requests, you can use `socat` to find how `niri msg` formats them:
+
+```sh
+$ socat STDIO UNIX-LISTEN:temp.sock
+# then, in a different terminal:
+$ env NIRI_SOCKET=./temp.sock niri msg action focus-workspace 2
+# then, look in the socat terminal:
+{"Action":{"FocusWorkspace":{"reference":{"Index":2}}}}
+```
+
+You can find all available requests and response types in the [niri-ipc sub-crate documentation](https://yalter.github.io/niri/niri_ipc/).
+
+### Backwards Compatibility
+
+The JSON output *should* remain stable, as in:
+
+- existing fields and enum variants should not be renamed
+- non-optional existing fields should not be removed
+
+However, new fields and enum variants will be added, so you should handle unknown fields or variants gracefully where reasonable.
+
+The formatted/human-readable output (i.e. without `--json` flag) is **not** considered stable.
+Please prefer the JSON output for scripts, since I reserve the right to make any changes to the human-readable output.
+
+The `niri-ipc` sub-crate (like other niri sub-crates) is *not* API-stable in terms of the Rust semver; rather, it follows the version of niri itself.
+In particular, new struct fields and enum variants will be added.