modernize introduction somewhat

At least it no longer recommends deprecated types.

src/config/io/markdown.ts

@@ -32,7 +32,7 @@ const remarkParseAtTypes: RemarkPlugin<[]> = () => {
         const node = rawNode as Md.Literal;
 
         node.value = node.value.replace(
-          /@@((?<module>([A-Z]\w*\.)*)(?<type>([A-Z]\w*))\.?)?((?<member>[a-z]\w*)((?<function>\(\))|(?<signal>\(s\)))?)?(?=[$.,;:)\s]|$)/g,
+          /@@((?<module>([A-Z]\w*\.)*)(?<type>([A-Z]\w*))(\.(?!\s|$))?)?((?<member>[a-z]\w*)((?<function>\(\))|(?<signal>\(s\)))?)?(?=[$.,;:)\s]|$)/g,
           (_full, ...args) => {
             type Capture = {
               module: string | undefined;

src/guide/introduction.mdx

@@ -3,41 +3,27 @@ title: "Introduction"
 index: 2
 ---
 
-import Collapsible from "@components/Collapsible.astro";
-
 # {frontmatter.title}
 
-> [!NOTE]
-> This guide was created a long time ago, and is somewhat outdated.
-> Take a look at @@Quickshell.SystemClock after going through.
-
 This page will walk you through the process of creating a simple bar/panel, and
-introduce you to all the basic concepts involved.
+introduce you to all the basic concepts involved. You can use the
+[QML Language Reference](/docs/guide/qml-language) to learn about the syntax
+of the QML language.
 
-There are many links to the [QML Overview](/docs/guide/qml-language)
+Note that all the <a>Green Links</a> in code blocks will take you to the documentation
-and [Type Reference](/docs/types) which you should follow if you don't
+for their respective types.
-fully understand the concepts involved.
 
-## Shell Files
+## Config Files
+Quickshell searches the `quickshell` subfolder of every XDG standard config path
+for configs. Usually this is `~/.config/quickshell`.
 
-Every quickshell instance starts from a shell root file, conventionally named `shell.qml`.
+Each named subfolder containing a `shell.qml` file is considered to be a config.
-The default path is `~/.config/quickshell/shell.qml`.
+If the base `quickshell` folder contains a shell.qml file, subfolders will not be
-(where `~/.config` can be substituted with `$XDG_CONFIG_HOME` if present.)
+considered.
 
-Each shell file starts with the shell root object. Only one may exist per configuration.
+A specific config can be picked using the `--config` or `-c` argument to Quickshell.
 
-```qml
+Configs at other paths, including raw qml files can be run with `--path` or `-p`.
-// ~/.config/quickshell/shell.qml
-import Quickshell
-
-@@Quickshell.ShellRoot {
-  // ...
-}
-```
-
-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.
 
 ## Creating Windows
 
@@ -48,10 +34,9 @@ Quickshell has two main window types available,
 We'll start with an example:
 
 ```qml
-import Quickshell // for ShellRoot and PanelWindow
+import Quickshell // for PanelWindow
 import QtQuick // for Text
 
-@@Quickshell.ShellRoot {
 @@Quickshell.PanelWindow {
   anchors {
     top: true
@@ -68,19 +53,21 @@ import QtQuick // for Text
     text: "hello world"
   }
 }
-}
 ```
 
 The above example creates a bar/panel on your currently focused monitor with
 a centered piece of [text](https://doc.qt.io/qt-6/qml-qtquick-text.html). It will also reserve space for itself on your monitor.
 
-More information about available properties is available in the [type reference](/docs/types/quickshell/panelwindow).
+More information about available properties is available in the [type reference](/docs/types/Quickshell/PanelWindow).
 
 ## 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.
 
+> [!note/Note]
+> Quickshell can do more than just run processes. Read until the end for more information.
+
 We can use a [Process](/docs/types/quickshell.io/process) object to run commands
 and return their results.
 
@@ -98,7 +85,6 @@ import Quickshell
 import Quickshell.Io // for Process
 import QtQuick
 
-@@Quickshell.ShellRoot {
 @@Quickshell.PanelWindow {
   anchors {
     top: true
@@ -132,7 +118,6 @@ import QtQuick
     }
   }
 }
-}
 ```
 
 ## Running code at an interval
@@ -145,7 +130,6 @@ import Quickshell
 import Quickshell.Io
 import QtQuick
 
-@@Quickshell.ShellRoot {
 @@Quickshell.PanelWindow {
   anchors {
     top: true
@@ -189,7 +173,6 @@ import QtQuick
     }
   }
 }
-}
 ```
 
 ## Reusable components
@@ -217,7 +200,6 @@ import Quickshell
 import Quickshell.Io
 import QtQuick
 
-@@Quickshell.ShellRoot {
 @@Quickshell.Variants {
   model: Quickshell.screens;
 
@@ -262,7 +244,6 @@ import QtQuick
     }
   }
 }
-}
 ```
 
 <span class="small">
@@ -276,8 +257,9 @@ due to the reactive nature of the
 (See: [Reactive Bindings](/docs/configuration/qml-overview/#reactive-bindings).)
 
 Now there's an important problem you might have noticed: when the window
-is created multiple times we also make a new Process and Timer. We can fix
+is created multiple times we also make a new Process and Timer, which makes the
-this by moving the Process and Timer outside of the window.
+bar less efficient than it could be. We can fix this by moving the
+Process and Timer outside of the window using @@Quickshell.Scope.
 
 > [!caution/Error]
 > This code will not work correctly.
@@ -287,7 +269,7 @@ import Quickshell
 import Quickshell.Io
 import QtQuick
 
-@@Quickshell.ShellRoot {
+@@Quickshell.Scope {
   @@Quickshell.Variants {
     model: Quickshell.screens
 
@@ -338,11 +320,11 @@ _What about the `clock` that the process references?_
 If you run the above example you'll see something like this in the console every second:
 
 ```
-file:///home/name/.config/quickshell/shell.qml:33: ReferenceError: clock is not defined
+WARN scene: **/shell.qml[36:-1]: ReferenceError: clock is not defined
-file:///home/name/.config/quickshell/shell.qml:33: ReferenceError: clock is not defined
+WARN scene: **/shell.qml[36:-1]: ReferenceError: clock is not defined
-file:///home/name/.config/quickshell/shell.qml:33: ReferenceError: clock is not defined
+WARN scene: **/shell.qml[36:-1]: ReferenceError: clock is not defined
-file:///home/name/.config/quickshell/shell.qml:33: ReferenceError: clock is not defined
+WARN scene: **/shell.qml[36:-1]: ReferenceError: clock is not defined
-file:///home/name/.config/quickshell/shell.qml:33: ReferenceError: clock is not defined
+WARN scene: **/shell.qml[36:-1]: ReferenceError: clock is not defined
 ```
 
 This is because the `clock` object, even though it has an ID, cannot be referenced
@@ -362,11 +344,11 @@ import Quickshell
 import Quickshell.Io
 import QtQuick
 
-@@Quickshell.ShellRoot {
+@@Quickshell.Scope {
   id: root
 
   // add a property in the root
-  property string time;
+  property string time
 
   @@Quickshell.Variants {
     model: Quickshell.screens
@@ -389,7 +371,7 @@ import QtQuick
 
           anchors.centerIn: parent
 
-          // bind the text to the root's time property
+          // bind the text to the root object's time property
           text: root.time
         }
       }
@@ -427,9 +409,6 @@ above code, but we can make it more concise:
    which means we can skip the `delegate:` part of the assignment.
    We're already using the default property of @@Quickshell.ShellRoot to store our
    Variants, Process, and Timer components among other things.
-3. The ShellRoot doesn't actually need an `id` property to talk about
-   the time property, as it is the outermost object in the file which
-   has [special scoping rules](/docs/configuration/qml-overview/#property-access-scopes).
 
 This is what our shell looks like with the above (optional) cleanup:
 
@@ -438,8 +417,9 @@ import Quickshell
 import Quickshell.Io
 import QtQuick
 
-@@Quickshell.ShellRoot {
+@@Quickshell.Scope {
-  property string time;
+  id: root
+  property string time
 
   @@Quickshell.Variants {
     model: Quickshell.screens
@@ -458,9 +438,7 @@ import QtQuick
 
       @@QtQuick.Text {
         anchors.centerIn: parent
-
+        text: root.time
-        // now just time instead of root.time
-        text: time
       }
     }
   }
@@ -471,8 +449,7 @@ import QtQuick
     running: true
 
     stdout: @@Quickshell.Io.SplitParser {
-      // now just time instead of root.time
+      onRead: data => root.time = data
-      onRead: data => time = data
     }
   }
 
@@ -496,7 +473,7 @@ To start with, let's move the entire bar into a new file.
 // shell.qml
 import Quickshell
 
-@@Quickshell.ShellRoot {
+@@Quickshell.Scope {
   Bar {}
 }
 ```
@@ -508,7 +485,8 @@ import Quickshell.Io
 import QtQuick
 
 @@Quickshell.Scope {
-  property string time;
+  id: root
+  property string time
 
   @@Quickshell.Variants {
     model: Quickshell.screens
@@ -527,9 +505,7 @@ import QtQuick
 
       @@QtQuick.Text {
         anchors.centerIn: parent
-
+        text: root.time
-        // now just time instead of root.time
-        text: time
       }
     }
   }
@@ -540,8 +516,7 @@ import QtQuick
     running: true
 
     stdout: @@Quickshell.Io.SplitParser {
-      // now just time instead of root.time
+      onRead: data => root.time = data
-      onRead: data => time = data
     }
   }
 
@@ -589,7 +564,7 @@ import QtQuick
 
 @@Quickshell.Scope {
   id: root
-  property string time;
+  property string time
 
   @@Quickshell.Variants {
     model: Quickshell.screens
@@ -609,7 +584,6 @@ import QtQuick
       // the ClockWidget type we just created
       ClockWidget {
         anchors.centerIn: parent
-        // Warning: setting `time: time` will bind time to itself which is not what we want
         time: root.time
       }
     }
@@ -621,7 +595,7 @@ import QtQuick
     running: true
 
     stdout: @@Quickshell.Io.SplitParser {
-      onRead: data => time = data
+      onRead: data => root.time = data
     }
   }
 
@@ -646,7 +620,8 @@ import Quickshell.Io
 import QtQuick
 
 @@Quickshell.Scope {
-  property string time;
+  id: root
+  property string time
 
   @@Quickshell.Io.Process {
     id: dateProc
@@ -654,7 +629,7 @@ import QtQuick
     running: true
 
     stdout: @@Quickshell.Io.SplitParser {
-      onRead: data => time = data
+      onRead: data => root.time = data
     }
   }
 
@@ -721,6 +696,7 @@ import QtQuick
 
 // your singletons should always have Singleton as the type
 @@Quickshell.Singleton {
+  id: root
   property string time
 
   @@Quickshell.Io.Process {
@@ -729,7 +705,7 @@ import QtQuick
     running: true
 
     stdout: @@Quickshell.Io.SplitParser {
-      onRead: data => time = data
+      onRead: data => root.time = data
     }
   }
 
@@ -786,31 +762,39 @@ import Quickshell
 }
 ```
 
-## JavaScript APIs
+## Quickshell Support Libraries
+In addition to calling external processes, Quickshell comes with a large set of support libraries
+for common OS integrations and tasks. These libraries are indexed on the left sidebar.
 
-In addition to calling external processes, a [limited set of javascript interfaces] is available.
+One of these integrations is @@Quickshell.SystemClock, which exposes the system time in an easy to
-We can use this to improve our clock by using the [Date API] instead of calling `date`.
+use way.
 
-[limited set of javascript interfaces]: https://doc.qt.io/qt-6/qtqml-javascript-functionlist.html
+We can use @@Quickshell.SystemClock.date to get a Date object to display. The
-[Date API]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date
+@@QtQml.Qt.formatDateTime() function can be used to easily format the date
+as shown below.
+
+@@Quickshell.SystemClock.precision can be set to `Minutes` to improve battery life if you don't
+show seconds on your clock, as Quickshell will have less work to do.
 
 ```qml
 // Time.qml
 pragma Singleton
 
 import Quickshell
-import Quickshell.Io
 import QtQuick
 
 @@Quickshell.Singleton {
-  property var date: new Date()
+  id: root
-  property string time: date.toLocaleString(Qt.locale())
+  // an expression can be broken across multiple lines using {}
+  readonly property string time: {
+    // The passed format string matches the default output of
+    // the `date` command.
+    Qt.formatDateTime(clock.date, "ddd MMM d hh:mm:ss AP t yyyy")
+  }
 
-  @@QtQml.Timer {
+  @@Quickshell.SystemClock {
-    interval: 1000
+    id: clock
-    running: true
+    precision: SystemClock.Seconds
-    repeat: true
-    onTriggered: date = new Date()
   }
 }
 ```