site: add autogenerated section support

docs/nix/render_options/__init__.py

@@ -431,7 +431,7 @@ def produce_inventory_docs() -> None:
     output = """# Inventory Submodule
 This provides an overview of the available options of the `inventory` model.
 
-It can be set via the `inventory` attribute of the [`clan`](../../reference/options/clan_inventory.md) function, or via the [`clan.inventory`](../../reference/options/clan_inventory.md) attribute of flake-parts.
+It can be set via the `inventory` attribute of the [`clan`](../../reference/options/clan.md) function, or via the [`clan.inventory`](../../reference/options/clan_inventory.md) attribute of flake-parts.
 
 """
     # Inventory options are already included under the clan attribute

site/src/routes/docs/settings.ts

@@ -14,7 +14,7 @@ export const navLinks: NavLink[] = [
       },
       {
         label: "Options",
-        items: ["reference/options/clan"],
+        autogenerate: { directory: "reference/options" },
       },
     ],
   },

site/src/routes/docs/utils.ts

@@ -16,6 +16,12 @@ export type NavLink =
       collapsed?: boolean;
       badge?: Badge;
     }
+  | {
+      label: string;
+      autogenerate: { directory: string };
+      collapsed?: boolean;
+      badge?: Badge;
+    }
   | {
       label?: string;
       slug: string;
@@ -82,6 +88,63 @@ export async function normalizeNavLink(
         external: false,
       };
     }
+    if ("autogenerate" in navLink) {
+      const dir = navLink.autogenerate.directory;
+      const articleEntries = Object.entries(articles).filter(([key]) =>
+        key.startsWith(dir + "/"),
+      );
+
+      const frontmatters = await Promise.all(
+        articleEntries.map(async ([key, article]) => ({
+          key,
+          frontmatter: (await article()).frontmatter,
+        })),
+      );
+
+      let titleMissing = false;
+      // Check frontmatter for title
+      for (const item of frontmatters) {
+        if (!item.frontmatter.title) {
+          console.error(
+            `Missing title in frontmatter for autogenerated doc: ${item.key}`,
+          );
+          titleMissing = true;
+        }
+      }
+      if (titleMissing) throw new Error("Aborting due to errors.");
+
+      const items: NormalizedNavLink[] = await Promise.all(
+        frontmatters
+          .sort((a, b) => {
+            const orderA = a.frontmatter.order;
+            const orderB = b.frontmatter.order;
+            if (orderA != null && orderB != null) {
+              return orderA - orderB;
+            }
+            if (orderA != null) {
+              return -1;
+            }
+            if (orderB != null) {
+              return 1;
+            }
+            const titleA = a.frontmatter.title ?? a.key;
+            const titleB = a.frontmatter.title ?? a.key;
+            return titleA.localeCompare(titleB.title);
+          })
+          .map((item) =>
+            normalizeNavLink({
+              label: item.frontmatter.title,
+              link: `/docs/${item.key}`,
+            }),
+          ),
+      );
+      return {
+        label: navLink.label ?? dir.split("/").slice(-1)[0],
+        items,
+        collapsed: !!navLink.collapsed,
+        badge: normalizeBadge(navLink.badge),
+      };
+    }
     return {
       ...navLink,
       badge: normalizeBadge(navLink.badge),