From 1271c0ad6b26b1238ca266faaa427385d3370567 Mon Sep 17 00:00:00 2001 From: outfoxxed Date: Tue, 10 Jun 2025 15:38:19 -0700 Subject: [PATCH] add distribution guide --- src/guide/distribution.mdx | 35 +++++++++++++++++++++++++++++++++++ 1 file changed, 35 insertions(+) create mode 100644 src/guide/distribution.mdx diff --git a/src/guide/distribution.mdx b/src/guide/distribution.mdx new file mode 100644 index 0000000..0ae4ebf --- /dev/null +++ b/src/guide/distribution.mdx @@ -0,0 +1,35 @@ +--- +title: "Distributing Configurations" +index: 9 +--- +If you plan to distribute your configuration to a lot of users, you should keep +a couple things in mind: + +### API Breaks +Quickshell will have API breaks in future versions. +You should have a way to track specific revisions with your distribution +to avoid breakage if a user updates quickshell before you can update your configuration. + +With Nix this should be as simple as tracking a specific revision. +For Arch, and other distributions without a mechanism to do this, you may +want to include a package that builds a specific Quickshell revision with +your configuration. + +### Configuration Paths +Quickshell can load configurations from a number of different paths. +The ideal path depends on how you distribute your config. + +#### As dotfiles +If you distribute your config as a set of dotfiles, you should place +the config in `$XDG_CONFIG_HOME/quickshell/` (usually `~/.config/quickshell/`). +Named configurations can be used in the quickshell command by specifying `--config` or `-c` +(`qs -c `). + +You should not use the bare `$XDG_CONFIG_HOME/quickshell` directory as that will +make it harder for users to have any other configuration. + +#### As a package +Some configurations are distributed as distro packages. These packages should use a +path in `$XDG_CONFIG_DIRS`, usually `/etc/xdg` for their files. + +As with dotfiles, named configurations should be used (`$CONFIG_DIR/quickshell/`).