From aabd966878566aef38087bdc21a3d14635fb9d90 Mon Sep 17 00:00:00 2001 From: outfoxxed Date: Mon, 4 Nov 2024 04:06:17 -0800 Subject: [PATCH] basic installation/getting started pages --- src/config/io/helpers.ts | 4 ++ .../docs/configuration/getting-started.mdx | 60 +++++++++++++++++ src/pages/docs/configuration/installation.mdx | 65 +++++++++++++++++++ src/styles/docs/docs.css | 2 +- 4 files changed, 130 insertions(+), 1 deletion(-) create mode 100644 src/pages/docs/configuration/getting-started.mdx create mode 100644 src/pages/docs/configuration/installation.mdx diff --git a/src/config/io/helpers.ts b/src/config/io/helpers.ts index 136d810..c525ad4 100644 --- a/src/config/io/helpers.ts +++ b/src/config/io/helpers.ts @@ -42,6 +42,8 @@ export function groupRoutes(routes: RouteData[]): GroupedRoutes { tutorials: { configuration: [ { name: "About", type: "about" }, + { name: "Installation", type: "installation" }, + { name: "Getting Started", type: "getting-started" }, { name: "Intro", type: "intro" }, { name: "Positioning", type: "positioning" }, { name: "QML Overview", type: "qml-overview" }, @@ -54,6 +56,8 @@ export function groupRoutes(routes: RouteData[]): GroupedRoutes { acc.tutorials = { configuration: [ { name: "About", type: "about" }, + { name: "Installation", type: "installation" }, + { name: "Getting Started", type: "getting-started" }, { name: "Intro", type: "intro" }, { name: "Positioning", type: "positioning" }, { name: "QML Overview", type: "qml-overview" }, diff --git a/src/pages/docs/configuration/getting-started.mdx b/src/pages/docs/configuration/getting-started.mdx new file mode 100644 index 0000000..ae56a7e --- /dev/null +++ b/src/pages/docs/configuration/getting-started.mdx @@ -0,0 +1,60 @@ +--- +layout: "@layouts/ConfigLayout.astro" +title: "Getting Started" +--- +# {frontmatter.title} +See [Installation](./installation) if Quickshell isn't installed yet. + +## Editor configuration +### 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 call `require("lspconfig").qmlljs.setup({})`. + +## Language Server +The QML language has an associated language server, +[qmlls](https://doc.qt.io/qt-6/qtqml-tooling-qmlls.html). +Please note that the language server, along with quickshell's support of it, +is in development. + +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. +- Qmlls cannot handle quickshell's singletons. This means you won't see + completions, and usages of singleton members may show a warning. + We're still investigating this problem and how to fix it. + +Keeping in mind the above caveats, qmlls should be able to guide you towards +more correct code should you chose to use it. + +> [!NOTE] +> Nix users should note that qmlls will not be able to pick up qml modules +> that are not in `QML2_IMPORT_PATH`. diff --git a/src/pages/docs/configuration/installation.mdx b/src/pages/docs/configuration/installation.mdx new file mode 100644 index 0000000..699c179 --- /dev/null +++ b/src/pages/docs/configuration/installation.mdx @@ -0,0 +1,65 @@ +--- +layout: "@layouts/ConfigLayout.astro" +title: "Installation" +--- +# {frontmatter.title} + +> [!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. + +All packages currently track quickshell's master branch. This may change in the future. + +# Nix +The Quickshell repo has an embedded flake. +You can use either `git+https://git.outfoxxed.me/outfoxxed/quickshell` +or `github:quickshell-mirror/quickshell`. + +```nix +{ + inputs = { + nixpkgs.url = "nixpkgs/nixos-unstable"; + + quickshell = { + 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 you can add to +`environment.systemPackages` or `home.packages` if you use home-manager. + +# Arch +Quickshell is available from the aur by [mcgoth] under +the [quickshell](https://aur.archlinux.org/packages/quickshell) package. + +> [!WARNING] +> When using the AUR package, quickshell may break any time 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 your AUR helper of choice) + +# Fedora +Quickshell is available from [errornointernet](https://github.com/errornointernet/)'s +Fedora COPR as [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 +``` + +# Manual build +See [BUILD.md](https://git.outfoxxed.me/quickshell/quickshell/src/branch/master/BUILD.md) +for build instructions and configurations. diff --git a/src/styles/docs/docs.css b/src/styles/docs/docs.css index e4d5b45..355df9b 100644 --- a/src/styles/docs/docs.css +++ b/src/styles/docs/docs.css @@ -46,7 +46,7 @@ } } - & p { + & p, h1, h2, h3, h4, h5 { margin-block: 0.618rem; }