diff --git a/src/guide/faq.mdx b/src/guide/faq.mdx
new file mode 100644
index 0000000..d87de4a
--- /dev/null
+++ b/src/guide/faq.mdx
@@ -0,0 +1,31 @@
+---
+title: "FAQ"
+description: "Frequently Asked Questions"
+index: 1000
+---
+# {frontmatter.title}
+
+This page is being actively expanded as common questions come up again.
+
+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
+
+## How do I
+
+### Make a rounded window
+Rounded windows are simply transparent square ones with a rounded rectangle
+inside of them.
+
+```qml
+@@Quickshell.PanelWindow {
+ color: "transparent"
+
+ @@QtQuick.Rectangle {
+ // match the size of the window
+ anchors.fill: parent
+
+ radius: 5
+ color: "white" // your actual color
+ }
+}
+```
diff --git a/src/guide/index.mdx b/src/guide/index.mdx
index fd95fd9..da09868 100644
--- a/src/guide/index.mdx
+++ b/src/guide/index.mdx
@@ -4,3 +4,28 @@ description: "Configuring the shell"
index: -1
---
# {frontmatter.title}
+
+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).
+
+Before continuing on your own, read the [Item Size and Position](/docs/guide/size-position)
+page to learn how to lay out elements in QML. This is significantly different
+from many other layout systems such as CSS.
+
+To learn what features Quickshell offers and how to use them, use the
+left sidebar and click through the `Quickshell Types` pages. The sidebar
+also links QtQuick's type index, which contains most of the visual elements used
+to build a UI.
+
+You may also want to check out the [Official Examples] to see some code,
+as well as review existing user configs. Do note that Quickshell has evolved
+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 Room] for help.
+
+[Matrix Room]: https://matrix.to/#/#quickshell:outfoxxed.me
diff --git a/src/guide/install-setup.mdx b/src/guide/install-setup.mdx
index e9a4f84..32401b0 100644
--- a/src/guide/install-setup.mdx
+++ b/src/guide/install-setup.mdx
@@ -61,7 +61,7 @@ sudo dnf copr enable errornointernet/quickshell
sudo dnf install quickshell
```
-## Guix
+### Guix
Quickshell's source repository works as a channel. Add the following to your channel list:
```scheme
@@ -79,9 +79,11 @@ You can also clone the repository and use `guix shell -f quickshell.scm` to try
See [BUILD.md](https://git.outfoxxed.me/quickshell/quickshell/src/branch/master/BUILD.md)
for build instructions and configurations.
-See [Installation](./installation) if Quickshell isn't installed yet.
-
## 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.
+
### 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.
@@ -128,9 +130,9 @@ require("lspconfig").qmlls.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.
+[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.
We are aware of the following issues:
- Qmlls does not work well when a file is not correctly structured.
diff --git a/src/guide/introduction.mdx b/src/guide/introduction.mdx
index 5523605..8a1b5cf 100644
--- a/src/guide/introduction.mdx
+++ b/src/guide/introduction.mdx
@@ -4,7 +4,6 @@ index: 2
---
import Collapsible from "@components/Collapsible.astro";
-import MD_Title from "@components/MD_Title.tsx"
# {frontmatter.title}
@@ -15,11 +14,11 @@ import MD_Title from "@components/MD_Title.tsx"
This page will walk you through the process of creating a simple bar/panel, and
introduce you to all the basic concepts involved.
-There are many links to the [QML Overview](/docs/configuration/qml-overview)
+There are many links to the [QML Overview](/docs/guide/qml-language)
and [Type Reference](/docs/types) which you should follow if you don't
fully understand the concepts involved.
-## Shell Files
+## Shell Files
Every quickshell instance starts from a shell root file, conventionally named `shell.qml`.
The default path is `~/.config/quickshell/shell.qml`.
@@ -27,7 +26,8 @@ The default path is `~/.config/quickshell/shell.qml`.
Each shell file starts with the shell root object. Only one may exist per configuration.
-```qml {filename="~/.config/quickshell/shell.qml"}
+```qml
+// ~/.config/quickshell/shell.qml
import Quickshell
@@Quickshell.ShellRoot {
@@ -39,42 +39,7 @@ The shell root is not a visual element but instead contains all of the visual
and non visual objects in your shell. You can have multiple different shells
with shared components and different shell roots.
-
-Quickshell can be launched with configurations in locations other than the default one.
-
-The `-p` or `--path` option will launch the shell root at the given path.
-It will also accept folders with a `shell.qml` file in them.
-It can also be specified via the `QS_CONFIG_PATH` environment variable.
-
-The `-c` or `--config` option will launch a configuration from the current manifest,
-or if no manifest is specified, a subfolder of quickshell's base path.
-It can also be specified via the `QS_CONFIG_NAME` environment variable.
-
-The base path defaults to `~/.config/quickshell`, but can be changed using
-the `QS_BASE_PATH` environment variable.
-
-The `-m` or `--manifest` option specifies the quickshell manifest to read configs
-from. When used with `-c`, the config will be chosen by name from the manifest.
-It can also be specified via the `QS_MANIFEST` environment variable.
-
-The manifest path defaults to `~/.config/quickshell/manifest.conf` and is a list
-of `name = path` pairs where path can be relative or absolute.
-Lines starting with `#` are comments.
-
-```properties
-# ~/.config/quickshell/manifest.conf
-myconf1 = myconf
-myconf2 = ./myconf
-myconf3 = myconf/shell.nix
-myconf4 = ~/.config/quickshell/myconf
-```
-
-You can use `quickshell --current` to print the current values of any of these
-options and what set them.
-
-
-
-## Creating Windows
+## Creating Windows
Quickshell has two main window types available,
[PanelWindow](/docs/types/quickshell/panelwindow) for bars and widgets, and
@@ -111,7 +76,7 @@ a centered piece of [text](https://doc.qt.io/qt-6/qml-qtquick-text.html). It wil
More information about available properties is available in the [type reference](/docs/types/quickshell/panelwindow).
-## Running a process
+## Running a process
Now that we have a piece of text, what if it did something useful?
To start with lets make a clock. To get the time we'll use the `date` command.
@@ -170,7 +135,7 @@ import QtQuick
}
```
-## Running code at an interval
+## Running code at an interval
With the above example, your bar should now display the time, but it isn't updating!
Let's use a @@QtQml.Timer to fix that.
@@ -227,7 +192,7 @@ import QtQuick
}
```
-## Reusable components
+## Reusable components
If you have multiple monitors you might have noticed that your bar
is only on one of them. If not, you'll still want to **follow this section
@@ -520,14 +485,15 @@ import QtQuick
}
```
-## Multiple files
+## Multiple files
In an example as small as this, it isn't a problem, but as the shell
grows it might be preferable to separate it into multiple files.
To start with, let's move the entire bar into a new file.
-```qml {filename="shell.qml"}
+```qml
+// shell.qml
import Quickshell
@@Quickshell.ShellRoot {
@@ -535,7 +501,8 @@ import Quickshell
}
```
-```qml {filename="Bar.qml"}
+```qml Bar.qml
+// Bar.qml
import Quickshell
import Quickshell.Io
import QtQuick
@@ -600,7 +567,8 @@ make up the actual clock, need to be dealt with.
To start with, we can move the clock widget to a new file. For now it's just a
single @@QtQuick.Text object but the same concepts apply regardless of complexity.
-```qml {filename="ClockWidget.qml"}
+```qml
+// ClockWidget.qml
import QtQuick
@@QtQuick.Text {
@@ -613,7 +581,8 @@ import QtQuick
}
```
-```qml {filename="Bar.qml"}
+```qml
+// Bar.qml
import Quickshell
import Quickshell.Io
import QtQuick
@@ -670,7 +639,8 @@ on the clock widget without cluttering the bar file.
Let's deal with the clock's update logic now:
-```qml {filename="Time.qml"}
+```qml
+// Time.qml
import Quickshell
import Quickshell.Io
import QtQuick
@@ -697,7 +667,8 @@ import QtQuick
}
```
-```qml {filename="Bar.qml"}
+```qml
+// Bar.qml
import Quickshell
@@Quickshell.Scope {
@@ -729,7 +700,7 @@ import Quickshell
}
```
-## Singletons
+## Singletons
Now you might be thinking, why do we need the `Time` type in
our bar file, and the answer is we don't. We can make `Time`
@@ -738,7 +709,9 @@ a [Singleton](/docs/configuration/qml-overview/#singletons).
A singleton object has only one instance, and is accessible from
any scope.
-```qml {filename="Time.qml"}
+```qml
+// Time.qml
+
// with this line our type becomes a singleton
pragma Singleton
@@ -769,7 +742,8 @@ import QtQuick
}
```
-```qml {filename="ClockWidget.qml"}
+```qml
+// ClockWidget.qml
import QtQuick
@@QtQuick.Text {
@@ -780,7 +754,8 @@ import QtQuick
}
```
-```qml {filename="Bar.qml"}
+```qml
+// Bar.qml
import Quickshell
@@Quickshell.Scope {
@@ -811,7 +786,7 @@ import Quickshell
}
```
-## JavaScript APIs
+## JavaScript APIs
In addition to calling external processes, a [limited set of javascript interfaces] is available.
We can use this to improve our clock by using the [Date API] instead of calling `date`.
@@ -819,7 +794,8 @@ We can use this to improve our clock by using the [Date API] instead of calling
[limited set of javascript interfaces]: https://doc.qt.io/qt-6/qtqml-javascript-functionlist.html
[Date API]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date
-```qml {filename="Time.qml"}
+```qml
+// Time.qml
pragma Singleton
import Quickshell
diff --git a/src/guide/positioning.mdx b/src/guide/size-position.mdx
similarity index 96%
rename from src/guide/positioning.mdx
rename to src/guide/size-position.mdx
index 9410b7f..fd7a1e9 100644
--- a/src/guide/positioning.mdx
+++ b/src/guide/size-position.mdx
@@ -1,9 +1,7 @@
---
-title: "Positioning"
+title: "Item Size and Position"
index: 2
---
-import MD_Title from "@components/MD_Title.tsx"
-
# {frontmatter.title}
> [!TIP]
@@ -167,12 +165,7 @@ examples. See its linked documentation for more information on how to use it.
Rewriting the examples from the top of the page:
```qml
@@QtQuick.Item {
- @@Quickshell.Widgets.MarginWrapperManager {
- margin: 5
- // By default, MarginWrapperManager centers the child
- // instead of resizing it when encountering constraints.
- resizeChild: true
- }
+ @@Quickshell.Widgets.MarginWrapperManager { margin: 5 }
// Automatically detected by MarginWrapperManager as the
// primary child of the container and sized accordingly.
@@ -200,7 +193,6 @@ Or as a reusable component:
// of the container and actual size of the child.
@@Quickshell.Widgets.MarginWrapperManager {
id: manager
- resizeChild: true
margin: 5 // the default value of margin
}
}
diff --git a/src/pages/index.astro b/src/pages/index.astro
index 4380f47..e03297e 100644
--- a/src/pages/index.astro
+++ b/src/pages/index.astro
@@ -16,7 +16,7 @@ const title = "Quickshell";