improve guide pages somewhat, add faq

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
+  }
+}
+```

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

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.
@@ -129,8 +131,8 @@ 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,
+We recommend using it, as it will catch a lot of bad practice that may
-is in development.
+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.

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.
 
-## <MD_Title titleVar={2} client:visible> Shell Files </MD_Title>
+## 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.
 
-<Collapsible title="Shell search paths and manifests">
+## Creating Windows
-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.
-
-</Collapsible>
-
-## <MD_Title titleVar={2}> Creating Windows </MD_Title>
 
 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).
 
-## <MD_Title titleVar={2}> Running a process </MD_Title>
+## 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
 }
 ```
 
-## <MD_Title titleVar={2}> Running code at an interval </MD_Title>
+## 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
 }
 ```
 
-## <MD_Title titleVar={2}> Reusable components </MD_Title>
+## 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
 }
 ```
 
-## <MD_Title titleVar={2}> Multiple files </MD_Title>
+## 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
 }
 ```
 
-## <MD_Title titleVar={2}> Singletons </MD_Title>
+## 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
 }
 ```
 
-## <MD_Title titleVar={2}> JavaScript APIs </MD_Title>
+## 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

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 {
+  @@Quickshell.Widgets.MarginWrapperManager { margin: 5 }
-    margin: 5
-    // By default, MarginWrapperManager centers the child
-    // instead of resizing it when encountering constraints.
-    resizeChild: true
-  }
   
   // 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
   }
 }

src/pages/index.astro

@@ -16,7 +16,7 @@ const title = "Quickshell";
     <section class="main-page_links">
       <section class="main-page_links_set">
         <a href="/docs/guide/install-setup" class="main-page_link-card">
-          <h3>Get started</h3>
+          <h3>Install</h3>
         </a>
         <a href="/docs/types" class="main-page_link-card">
           <h3>Documentation</h3>