From d6697a612e6385b041b3ae33cfddd03e45622faf Mon Sep 17 00:00:00 2001 From: outfoxxed Date: Sat, 26 Jul 2025 22:01:51 -0700 Subject: [PATCH 1/2] fix broken /docs links in guides --- src/guide/v0_1_0/faq.md | 6 +++--- src/guide/v0_1_0/index.md | 10 +++++----- src/guide/v0_1_0/install-setup.md | 5 +++-- src/guide/v0_1_0/qml-language.md | 2 +- 4 files changed, 12 insertions(+), 11 deletions(-) diff --git a/src/guide/v0_1_0/faq.md b/src/guide/v0_1_0/faq.md index 0318655..0f14112 100644 --- a/src/guide/v0_1_0/faq.md +++ b/src/guide/v0_1_0/faq.md @@ -7,8 +7,8 @@ index: 1000 > [!NOTE] > This page is being actively expanded upon as more common questions come up. > -> Make sure to also read the [Item Size and Position](/docs/guide/size-position) and -> [QML Language](/docs/guide/qml-language) pages for questions related to +> Make sure to also read the [Item Size and Position](@docs/guide/size-position) and +> [QML Language](@docs/guide/qml-language) pages for questions related to > item sizing/positioning and QML in general. ## Misc @@ -100,7 +100,7 @@ its contained item. } ``` -[MarginWrapper]: /docs/guide/size-position#marginwrapper-components +[MarginWrapper]: @docs/guide/size-position#marginwrapper-components ### Reference images and resources By default, paths passed to components such as @@QtQuick.Image or diff --git a/src/guide/v0_1_0/index.md b/src/guide/v0_1_0/index.md index afcf8b8..748e60d 100644 --- a/src/guide/v0_1_0/index.md +++ b/src/guide/v0_1_0/index.md @@ -3,13 +3,13 @@ title: "Usage Guide" description: "Configuring the shell" index: -1 --- -See the [Installation and Setup](/docs/guide/install-setup) page to get started. +See the [Installation and Setup](@docs/guide/install-setup) page to get started. To write a Quickshell config, start by following the -[Guided Introduction](/docs/guide/introduction), and skimming the -[QML Language Overview](/docs/guide/qml-language). +[Guided Introduction](@docs/guide/introduction), and skimming the +[QML Language Overview](@docs/guide/qml-language). -After that, read the [Item Size and Position](/docs/guide/size-position) page before +After that, read the [Item Size and Position](@docs/guide/size-position) page before continuing on your own to learn how to lay out elements in QML. Laying out elements in QML is significantly different from many other layout systems such as CSS. @@ -24,7 +24,7 @@ considerably over time and most configs don't reflect current best practice. [Official Examples]: https://git.outfoxxed.me/quickshell/quickshell-examples -See also the [FAQ](/docs/guide/faq) page, and the [Matrix Space] or [Discord Server] (bridged) for help. +See also the [FAQ](@docs/guide/faq) page, and the [Matrix Space] or [Discord Server] (bridged) for help. [Matrix Space]: https://matrix.to/#/#quickshell:outfoxxed.me [Discord Server]: https://discord.gg/UtZeT3xNyT diff --git a/src/guide/v0_1_0/install-setup.md b/src/guide/v0_1_0/install-setup.md index 5a9635b..dcdc612 100644 --- a/src/guide/v0_1_0/install-setup.md +++ b/src/guide/v0_1_0/install-setup.md @@ -114,7 +114,7 @@ for build instructions and configurations. ## Editor configuration If you want to write your own configuration, installing a QML grammar and the LSP is recommended. -Read the [Usage Guide](/docs/guide) after configuring your editor. +Read the [Usage Guide](@docs/guide) after configuring your editor. > [!NOTE] > Qmlls versions prior to 6.8.2 do not require `-E` @@ -190,6 +190,7 @@ We are aware of the following issues: this problem and how to fix it. - The LSP cannot provide any documentation for Quickshell types. - `root:` imports cannot be resolved by the LSP. +- `PanelWindow` in particular cannot be resolved. Keeping in mind the above caveats, qmlls should be able to guide you towards a more correct code should you choose to use it. @@ -201,4 +202,4 @@ more correct code should you choose to use it. # Next steps -Create your first configuration by reading the [Intro](/docs/configuration/intro). +Create your first configuration by reading the [Intro](@docs/guide/introduction). diff --git a/src/guide/v0_1_0/qml-language.md b/src/guide/v0_1_0/qml-language.md index 943fbf1..47ff55d 100644 --- a/src/guide/v0_1_0/qml-language.md +++ b/src/guide/v0_1_0/qml-language.md @@ -173,7 +173,7 @@ Name { Every object can contain [properties](#properties), [functions](#functions), and [signals](#signals). You can find out what properties are available for a type -by looking it up in the [Type Reference](/docs/types/). +by looking it up in the [Type Reference](@docs/types/). #### Properties From a273fca42bc3ae2119fe12484362118f48bc0d6c Mon Sep 17 00:00:00 2001 From: outfoxxed Date: Sat, 26 Jul 2025 22:02:07 -0700 Subject: [PATCH 2/2] update install guide for v0.2.0 --- src/guide/v0_2_0/install-setup.md | 194 ++++++++++++++++++++++++++++++ 1 file changed, 194 insertions(+) create mode 100644 src/guide/v0_2_0/install-setup.md diff --git a/src/guide/v0_2_0/install-setup.md b/src/guide/v0_2_0/install-setup.md new file mode 100644 index 0000000..8989a58 --- /dev/null +++ b/src/guide/v0_2_0/install-setup.md @@ -0,0 +1,194 @@ +--- +title: "Installation & Setup" +index: 0 +--- +> [!NOTE] +> Quickshell is still in a somewhat early stage of development. +> There will be breaking changes before 1.0, however a migration guide will be provided. + +## Installation + +Since Quickshell 0.1, you can now choose whether to install by tracking the master branch, +or install by latest release. + +Note that you may want to install some additional packages (names vary by distro): +- `qtsvg`: support for SVG image loading (bundled with most packages) +- `qtimageformats`: support for WEBP images as well as some less common ones +- `qtmultimedia`: support for playing videos, audio, etc +- `qt5compat`: extra visual effects, notably gaussian blur. @@QtQuick.Effects.MultiEffect is usually preferable + +### Nix +Release versions of Quickshell are available from Nixpkgs under the `quickshell` package. + +The Quickshell repo also has an embedded flake which can be used from either mirror: +- `git+https://git.outfoxxed.me/outfoxxed/quickshell` +- `github:quickshell-mirror/quickshell` + +> [!NOTE] +> You can use `?ref=` to specify a tag if you want a tagged release. + +```nix +{ + inputs = { + nixpkgs.url = "nixpkgs/nixos-unstable"; + + quickshell = { + # add ?ref= to track a tag + url = "git+https://git.outfoxxed.me/outfoxxed/quickshell"; + + # THIS IS IMPORTANT + # Mismatched system dependencies will lead to crashes and other issues. + inputs.nixpkgs.follows = "nixpkgs"; + }; + }; +} +``` + +The package is available as `quickshell.packages..default`, which can be added to +your `environment.systemPackages`, `home.packages` if you use home-manager, or a devshell. + +When using the flake, additional QML packages can be added to Quickshell's environment using +`.withModules [ ]`. + +### Arch +Quickshell is available from the aur under: +- the [quickshell](https://aur.archlinux.org/packages/quickshell) package for the latest release +- the [quickshell-git](https://aur.archlinux.org/packages/quickshell-git) package that tracks the master branch + +> [!WARNING] +> When using an AUR package, Quickshell may break whenever Qt is updated. +> The AUR gives us no way to actually fix this, but Quickshell will attempt to +> warn you if it detects a breakage when updating. If warned of a breakage, +> please reinstall the package. + +Install using the command below: +```sh +yay -S quickshell +# or +yay -S quickshell-git +``` +(or your AUR helper of choice) + +### Fedora +Quickshell is available from the [errornointernet/quickshell] COPR, as either: +- `quickshell` that tracks the latest release +- `quickshell-git` that tracks the master branch + +[errornointernet/quickshell]: https://copr.fedorainfracloud.org/coprs/errornointernet/quickshell + +Install using the command below: +```sh +sudo dnf copr enable errornointernet/quickshell + +sudo dnf install quickshell +# or +sudo dnf install quickshell-git +``` + +### Guix +Release versions of Quickshell are available from the standard Guix repository +as `quickshell` from the `(gnu packages wm)` module. + +Install using the command below: +```sh +guix install quickshell +``` + +You can also add `quickshell` to your Guix system configuration or Guix Home configuration. + +For the git version, Quickshell's source repository works as a channel. +Add the following to your channel list: + +```scheme +(channel + (name quickshell) + (url "https://git.outfoxxed.me/outfoxxed/quickshell") + (branch "master")) +``` + +However, since the package definition is located in the source repository, it cannot be used +as a channel out of the box. You can clone the repository and use `guix shell -f quickshell.scm` +to use the git version of the package. + +### Manual build +See [BUILD.md](https://git.outfoxxed.me/quickshell/quickshell/src/branch/master/BUILD.md) +for build instructions and configurations. + +## Editor configuration +If you want to write your own configuration, installing a QML grammar and the LSP is recommended. + +Read the [Usage Guide](@docs/guide) after configuring your editor. + +> [!NOTE] +> Qmlls versions prior to 6.8.2 do not require `-E` + +### Emacs +Install the [yuja/tree-sitter-qml](https://github.com/yuja/tree-sitter-qmljs) tree-sitter grammar, +and the [xhcoding/qml-ts-mode](https://github.com/xhcoding/qml-ts-mode) mode. + +Both are packaged for nix via [outfoxxed/nix-qml-support](https://git.outfoxxed.me/outfoxxed/nix-qml-support). + +Either `lsp-mode` or `eglot` should be usable for LSP ([caveats below](#language-server)). + +The author's personal emacs config uses `lsp-mode` and `qml-ts-mode` as follows: +```elisp +(use-package qml-ts-mode + :after lsp-mode + :config + (add-to-list 'lsp-language-id-configuration '(qml-ts-mode . "qml-ts")) + (lsp-register-client + (make-lsp-client :new-connection (lsp-stdio-connection '("qmlls")) + :activation-fn (lsp-activate-on "qml-ts") + :server-id 'qmlls)) + (add-hook 'qml-ts-mode-hook (lambda () + (setq-local electric-indent-chars '(?\n ?\( ?\) ?{ ?} ?\[ ?\] ?\; ?,)) + (lsp-deferred)))) +``` + +### Neovim +Neovim has built-in syntax highlighting for QML, however tree-sitter highlighting +may work better than the built-in highlighting. You can install the grammar +using `:TSInstall qmljs`. + +To use the language server ([caveats below](#language-server)), +install [nvim-lspconfig](https://github.com/neovim/nvim-lspconfig) +and the following snippet to your configuration: + +```lua +require("lspconfig").qmlls.setup {} +``` + +### Helix +Helix has built-in syntax highlighting and qmlls support. + +### Vscode +1. Install the [Official QML Support extension] +2. Enable the `qt-qml.qmlls.useQmlImportPathEnvVar` setting. +![](/assets/images/vscode-qml-env.png) + +[Official QML Support extension]: https://marketplace.visualstudio.com/items?itemName=TheQtCompany.qt-qml + +## Language Server +The QML language has an associated language server, +[qmlls](https://doc.qt.io/qt-6/qtqml-tooling-qmlls.html). +We recommend using it, as it will catch a lot of bad practice that may +make your configuration harder to maintain later. + +To enable language server support for your shell, create an empty file named `.qmlls.ini` +next to the `shell.qml` file. Quickshell will replace it with a managed qmlls configuration. +You should gitignore the `.qmlls.ini` file, as its content depends on information that +is different on every computer. + +We are aware of the following issues: +- Qmlls does not work well when a file is not correctly structured. + This means that completions and lints won't work unless braces are closed + correctly and such. +- The LSP cannot provide any documentation for Quickshell types. +- `PanelWindow` in particular cannot be resolved. + +Keeping in mind the above caveats, qmlls should be able to guide you towards a +more correct code should you choose to use it. + +# Next steps + +Create your first configuration by reading the [Intro](@docs/configuration/intro).