Restructure docs page with groups

packages/app-vscode/package.json

@@ -1219,7 +1219,7 @@
           }
         },
         "cursorless.experimental.hatStability": {
-          "markdownDescription": "As you scroll, edit, and move your cursor, this setting determines how much Cursorless will move hats around to ensure that the best hats are near the cursor.  See https://www.cursorless.org/docs/user/hatAssignment/",
+          "markdownDescription": "As you scroll, edit, and move your cursor, this setting determines how much Cursorless will move hats around to ensure that the best hats are near the cursor.  See https://www.cursorless.org/docs/user/hat-assignment/",
           "type": "string",
           "default": "balanced",
           "enum": [

packages/app-web-docs/docusaurus.config.mts

@@ -6,6 +6,7 @@ import type { Root } from "mdast";
 import { themes } from "prism-react-renderer";
 import type { Transformer } from "unified";
 import { visit } from "unist-util-visit";
+import { sidebarItemsGenerator } from "./sidebarItemsGenerator.ts";
 
 // oxlint-disable-next-line unicorn/prefer-import-meta-properties
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
@@ -152,6 +153,7 @@ const config: Config = {
           editUrl:
             "https://github.com/cursorless-dev/cursorless/edit/main/packages/app-web-docs/",
           sidebarPath: require.resolve("./sidebar.js"),
+          sidebarItemsGenerator,
           beforeDefaultRemarkPlugins: [
             remarkPluginFixLinksToRepositoryArtifacts,
           ],

packages/app-web-docs/sidebarItemsGenerator.ts

@@ -0,0 +1,118 @@
+import type * as ClassicPreset from "@docusaurus/preset-classic";
+
+type DocsOptions = Exclude<ClassicPreset.Options["docs"], false | undefined>;
+type SidebarItemsGenerator = NonNullable<DocsOptions["sidebarItemsGenerator"]>;
+
+interface Group {
+  label: string;
+  items: string[];
+}
+
+const items: (Group | string)[] = [
+  "Cursorless",
+  {
+    label: "Getting started",
+    items: ["Installation", "How-to guides"],
+  },
+  {
+    label: "Reference",
+    items: ["Actions", "Modifiers", "Scopes", "Destinations"],
+  },
+  "Supported languages",
+  {
+    label: "Customization",
+    items: ["Customization", "Hat assignment", "Visual Accessibility"],
+  },
+  {
+    label: "Tools",
+    items: ["Cursorless sidebar", "Scope visualizer", "Local command history"],
+  },
+  {
+    label: "Advanced",
+    items: ["Unicode support", "Experimental features"],
+  },
+  {
+    label: "Project",
+    items: ["Updating", "Glossary", "Release notes"],
+  },
+];
+
+export const sidebarItemsGenerator: SidebarItemsGenerator = async ({
+  defaultSidebarItemsGenerator,
+  ...args
+}) => {
+  const generatedItems = await defaultSidebarItemsGenerator(args);
+
+  type NormalizedSidebarItem = (typeof generatedItems)[number];
+
+  if (args.item.dirName !== "user") {
+    return generatedItems;
+  }
+
+  const docsById = new Map(args.docs.map((doc) => [doc.id, doc]));
+  const remainingItems = generatedItems.slice();
+
+  function getLabel(item: (typeof generatedItems)[number]) {
+    if (item.type === "doc" || item.type === "ref") {
+      const doc = docsById.get(item.id);
+      return doc?.frontMatter.sidebar_label ?? doc?.title;
+    }
+    if ("label" in item) {
+      return item.label;
+    }
+    throw new Error(`Unexpected sidebar item type: ${item.type}`);
+  }
+
+  function takeItem(label: string): NormalizedSidebarItem {
+    const index = remainingItems.findIndex(
+      (item) => getLabel(item)?.toLowerCase() === label.toLowerCase(),
+    );
+    const item = remainingItems[index];
+    if (item == null) {
+      throw new Error(`Missing generated sidebar item '${label}'`);
+    }
+    remainingItems.splice(index, 1);
+    return item;
+  }
+
+  function createGroup(group: Group): NormalizedSidebarItem {
+    const items = group.items.map(takeItem);
+    const linkIndex = items.findIndex(
+      (item) => item.type === "doc" && getLabel(item) === group.label,
+    );
+    const [link] = linkIndex === -1 ? [] : items.splice(linkIndex, 1);
+
+    return {
+      type: "category",
+      label: group.label,
+      collapsible: false,
+      collapsed: false,
+      ...(link?.type === "doc" ? { link: { type: "doc", id: link.id } } : {}),
+      items,
+    };
+  }
+
+  const groupedItems = items.map((item): NormalizedSidebarItem => {
+    if (typeof item === "string") {
+      return takeItem(item);
+    }
+    return createGroup(item);
+  });
+
+  if (remainingItems.length > 0) {
+    const remainingJson = remainingItems
+      .map((item) => {
+        if (item.type === "category") {
+          const { items, ...rest } = item;
+          return JSON.stringify(rest);
+        }
+        return JSON.stringify(item);
+      })
+      .join(", ");
+    throw new Error(
+      `Unassigned generated user sidebar items: ${remainingJson}`,
+    );
+  }
+
+  return groupedItems;
+};

packages/app-web-docs/src/docs/user/languages/components/Language.tsx → packages/app-web-docs/src/docs/components/Language.tsx

@@ -1,7 +1,7 @@
 import React from "react";
-import { DynamicTOC } from "../../../components/DynamicTOC";
-import { ScopeVisualizer } from "../../../components/ScopeVisualizer";
-import { ScrollToHashId } from "../../../components/ScrollToHashId";
+import { DynamicTOC } from "./DynamicTOC";
+import { ScopeVisualizer } from "./ScopeVisualizer";
+import { ScrollToHashId } from "./ScrollToHashId";
 
 interface Props {
   languageId: string;

packages/app-web-docs/src/docs/contributing/adding-a-new-language.md

@@ -43,7 +43,7 @@ Follow the instructions in [Adding a new scope](./adding-a-new-scope.md) to defi
 Create a `.mdx` file in [`languages`](../user/languages) with the `Language` react component. The file should be named after your language, eg `java.mdx`
 
 ```md
-import { Language } from "./components/Language";
+import { Language } from "@site/src/docs/components/Language";
 
 # Java
 

packages/app-web-docs/src/docs/user/README.md

@@ -1,9 +1,8 @@
 ---
 slug: /
-sidebar_position: 1
 ---
 
-# Cursorless documentation
+# Cursorless
 
 Welcome to Cursorless! You may find it helpful to start with the [tutorial videos](https://www.youtube.com/watch?v=5mAzHGM2M0k&list=PLXv2sppxeoQZz49evjy4T0QJRIgc_JPqs).
 
@@ -69,7 +68,7 @@ The following colors are supported. Note that to target the default (gray) hat y
 
 You can enable or disable colors in your VSCode settings, by searching for [`cursorless.hatEnablement.colors`](vscode://settings/cursorless.hatEnablement.colors) and checking the box next to the internal ID for the given shape as listed above. To navigate to your VSCode settings, either say "show settings", or go to File --> Preferences --> Settings.
 
-You can also tweak the visible colors for any of these colors in your VSCode settings, by searching for [`cursorless.colors`](vscode://settings/cursorless.colors) and changing the hex color code next to the internal ID for the given shape as listed above. Note that you can configure different colors for dark and light themes. See our [visual accessibility guide](visualAccessibility.md) for more on visual accessibility.
+You can also tweak the visible colors for any of these colors in your VSCode settings, by searching for [`cursorless.colors`](vscode://settings/cursorless.colors) and changing the hex color code next to the internal ID for the given shape as listed above. Note that you can configure different colors for dark and light themes. See our [visual accessibility guide](visual-accessibility.md) for more on visual accessibility.
 
 If you find these color names unintuitive / tough to remember, their
 spoken forms can be [customized](customization.md) like any other spoken form

packages/app-web-docs/src/docs/user/actions/_category_.json

@@ -0,0 +1,3 @@
+{
+  "label": "Actions"
+}

packages/app-web-docs/src/docs/user/experimental/_category_.json

@@ -0,0 +1,3 @@
+{
+  "label": "Experimental features"
+}

packages/app-web-docs/src/docs/user/how-to.md

@@ -10,7 +10,7 @@ To replace a target with the contents of the clipboard, say `"paste to <target>"
 
 :::info
 
-`"to <target>"` is an example of a Destination. See [Destinations](reference/destinations.md) for more information.
+`"to <target>"` is an example of a Destination. See [Destinations](destinations.md) for more information.
 
 :::
 
@@ -84,6 +84,6 @@ See the [Talon-side api docs](./customization.md#cursorless-public-api) for more
 
 :::info
 
-Notice how we use `cursorless_create_destination` to create a destination for the result of the transformation. The `cursorless_insert` action expects a destination, so that it knows whether to replace, insert before, or insert after the target. See [Destinations](reference/destinations.md) for more information.
+Notice how we use `cursorless_create_destination` to create a destination for the result of the transformation. The `cursorless_insert` action expects a destination, so that it knows whether to replace, insert before, or insert after the target. See [Destinations](destinations.md) for more information.
 
 :::

packages/app-web-docs/src/docs/user/languages/README.md

@@ -1,4 +1,4 @@
-# Languages
+# Supported languages
 
 Cursorless supports a wide range of languages, though our level of support varies a bit
 from language to language. See the sidebar for information about how well we support various

packages/app-web-docs/src/docs/user/languages/c.mdx

@@ -1,4 +1,4 @@
-import { Language } from "./components/Language";
+import { Language } from "@site/src/docs/components/Language";
 
 # C
 

packages/app-web-docs/src/docs/user/languages/clojure.mdx

@@ -1,4 +1,4 @@
-import { Language } from "./components/Language";
+import { Language } from "@site/src/docs/components/Language";
 
 # Clojure
 

packages/app-web-docs/src/docs/user/languages/cpp.mdx

@@ -1,4 +1,4 @@
-import { Language } from "./components/Language";
+import { Language } from "@site/src/docs/components/Language";
 
 # C++
 

packages/app-web-docs/src/docs/user/languages/csharp.mdx

@@ -2,7 +2,7 @@
 sidebar_label: C#
 ---
 
-import { Language } from "./components/Language";
+import { Language } from "@site/src/docs/components/Language";
 
 # C#
 

packages/app-web-docs/src/docs/user/languages/css.mdx

@@ -1,4 +1,4 @@
-import { Language } from "./components/Language";
+import { Language } from "@site/src/docs/components/Language";
 
 # CSS
 

packages/app-web-docs/src/docs/user/languages/dart.mdx

@@ -1,4 +1,4 @@
-import { Language } from "./components/Language";
+import { Language } from "@site/src/docs/components/Language";
 
 # Dart
 

packages/app-web-docs/src/docs/user/languages/go.mdx

@@ -1,4 +1,4 @@
-import { Language } from "./components/Language";
+import { Language } from "@site/src/docs/components/Language";
 
 # Go
 

packages/app-web-docs/src/docs/user/languages/html.mdx

@@ -1,4 +1,4 @@
-import { Language } from "./components/Language";
+import { Language } from "@site/src/docs/components/Language";
 
 # HTML
 

packages/app-web-docs/src/docs/user/languages/java.mdx

@@ -1,4 +1,4 @@
-import { Language } from "./components/Language";
+import { Language } from "@site/src/docs/components/Language";
 
 # Java
 

packages/app-web-docs/src/docs/user/languages/javascript.mdx

@@ -1,4 +1,4 @@
-import { Language } from "./components/Language";
+import { Language } from "@site/src/docs/components/Language";
 
 # JavaScript
 

packages/app-web-docs/src/docs/user/languages/javascriptreact.mdx

@@ -1,4 +1,4 @@
-import { Language } from "./components/Language";
+import { Language } from "@site/src/docs/components/Language";
 
 # JavaScript React
 

packages/app-web-docs/src/docs/user/languages/json.mdx

@@ -1,4 +1,4 @@
-import { Language } from "./components/Language";
+import { Language } from "@site/src/docs/components/Language";
 
 # JSON
 

packages/app-web-docs/src/docs/user/languages/jsonc.mdx

@@ -2,7 +2,7 @@
 sidebar_label: JSONC
 ---
 
-import { Language } from "./components/Language";
+import { Language } from "@site/src/docs/components/Language";
 
 # JSON with comments (JSONC)
 

packages/app-web-docs/src/docs/user/languages/jsonl.mdx

@@ -2,7 +2,7 @@
 sidebar_label: JSONL
 ---
 
-import { Language } from "./components/Language";
+import { Language } from "@site/src/docs/components/Language";
 
 # JSON lines (JSONL)
 

packages/app-web-docs/src/docs/user/languages/kotlin.mdx

@@ -1,4 +1,4 @@
-import { Language } from "./components/Language";
+import { Language } from "@site/src/docs/components/Language";
 
 # Kotlin
 

packages/app-web-docs/src/docs/user/languages/latex.mdx

@@ -1,4 +1,4 @@
-import { Language } from "./components/Language";
+import { Language } from "@site/src/docs/components/Language";
 
 # Latex
 

packages/app-web-docs/src/docs/user/languages/lua.mdx

@@ -1,4 +1,4 @@
-import { Language } from "./components/Language";
+import { Language } from "@site/src/docs/components/Language";
 
 # Lua
 

packages/app-web-docs/src/docs/user/languages/markdown.mdx

@@ -1,4 +1,4 @@
-import { Language } from "./components/Language";
+import { Language } from "@site/src/docs/components/Language";
 
 # Markdown
 

packages/app-web-docs/src/docs/user/languages/php.mdx

@@ -1,4 +1,4 @@
-import { Language } from "./components/Language";
+import { Language } from "@site/src/docs/components/Language";
 
 # PHP
 

packages/app-web-docs/src/docs/user/languages/plaintext.mdx

@@ -1,4 +1,4 @@
-import { Language } from "./components/Language";
+import { Language } from "@site/src/docs/components/Language";
 
 # Plaintext
 

packages/app-web-docs/src/docs/user/languages/properties.mdx

@@ -1,4 +1,4 @@
-import { Language } from "./components/Language";
+import { Language } from "@site/src/docs/components/Language";
 
 # Properties
 

packages/app-web-docs/src/docs/user/languages/python.mdx

@@ -1,4 +1,4 @@
-import { Language } from "./components/Language";
+import { Language } from "@site/src/docs/components/Language";
 
 # Python
 

packages/app-web-docs/src/docs/user/languages/r.mdx

@@ -1,4 +1,4 @@
-import { Language } from "./components/Language";
+import { Language } from "@site/src/docs/components/Language";
 
 # R
 

packages/app-web-docs/src/docs/user/languages/ruby.mdx

@@ -1,4 +1,4 @@
-import { Language } from "./components/Language";
+import { Language } from "@site/src/docs/components/Language";
 
 # Ruby
 

packages/app-web-docs/src/docs/user/languages/rust.mdx

@@ -1,4 +1,4 @@
-import { Language } from "./components/Language";
+import { Language } from "@site/src/docs/components/Language";
 
 # Rust
 

packages/app-web-docs/src/docs/user/languages/scala.mdx

@@ -1,4 +1,4 @@
-import { Language } from "./components/Language";
+import { Language } from "@site/src/docs/components/Language";
 
 # Scala
 

packages/app-web-docs/src/docs/user/languages/scm.mdx

@@ -2,7 +2,7 @@
 sidebar_label: Tree sitter query
 ---
 
-import { Language } from "./components/Language";
+import { Language } from "@site/src/docs/components/Language";
 
 # Tree sitter query (SCM)
 

packages/app-web-docs/src/docs/user/languages/scss.mdx

@@ -1,4 +1,4 @@
-import { Language } from "./components/Language";
+import { Language } from "@site/src/docs/components/Language";
 
 # SCSS