@solutiondesk/help 1.14.0 → 1.15.1

package/README.md

@@ -29,7 +29,7 @@ const { page } = await help.page("guides/login"); // one page with its text
 
 | Method | API | Returns |
 | --- | --- | --- |
-| `site({ lang })` | `GET …/site` | The site (`name`, `languages`, `websiteUrl`) and its navigation tree: pages, folders (with index page, `root` tab, `defaultOpen`, `collapsible`), separators and links. Empty folders are left out. |
+| `site({ lang })` | `GET …/site` | The site (`name`, `languages`, `websiteUrl`) and its navigation tree: pages, folders (with index page, `root` tab, `group`, `defaultOpen`, `collapsible`), separators and links. Empty folders are left out. |
 | `pages({ lang })` | `GET …/pages` | Every visible page without its text, in reading order (for builds and sitemaps). |
 | `page(path, { lang, redirect })` | `GET …/page?path=` | One page: `markdown`, `html`, `headings`, `blocks`, `breadcrumbs`, `previous`/`next`. The home page has the path `""`. |
 | `pageMarkdown(path, { lang })` | `GET …/page.md?path=` | One page as plain Markdown. |
@@ -103,8 +103,9 @@ The navigation becomes the files Fumadocs knows from a content folder:
 | SolutionDesk | Fumadocs |
 | --- | --- |
 | page `guides/login` | `guides/login.mdx` (`slugs: ["guides", "login"]`) |
-| home page | `index.mdx` (always at the top) |
+| home page | `index.mdx` at the top, or `(core)/index.mdx` when it is a top-level group's own page |
 | folder `guides` | `guides/meta.json` with `title`, `icon`, `root`, `defaultOpen`, `collapsible`, `pages` |
+| group folder `core` (adds no address part) | `(core)/` — a Fumadocs folder group, so `(core)/sign-up/index.mdx` is still `sign-up` |
 | folder's own page | `guides/index.mdx` (`pagesIndex: "index"`, so it also works for `root` tabs) |
 | any other page with the slug `index` | `guides/index_.mdx` (`slugs: ["guides", "index"]`), so it never collides with the folder's own page |
 | order of the top level | `meta.json` (`title` = site name) |

package/dist/fumadocs.d.ts

@@ -12,7 +12,8 @@ import { TOCItemType } from 'fumadocs-core/toc';
  * preview token names. Absent values are `null`, never a missing key.
  *
  * Paths: a page's path is its folder slugs plus its slug, without leading or
- * trailing slash (`guides/login`); the site's home page has the path `""`.
+ * trailing slash (`guides/login`) — a `group` folder adds no slug; the site's
+ * home page has the path `""`.
  */
 /** The doc site itself. */
 interface HelpPublicSite {
@@ -43,12 +44,17 @@ interface HelpPublicTreeFolder {
     /** Stable node id. */
     id: string;
     slug: string;
-    /** The folder's path (its index page, if any, lives here). */
+    /** The folder's path (its index page, if any, lives here; a group's is its parent's). */
     path: string;
     title: string;
     icon: string | null;
     /** A tab (top level only; Fumadocs `root`). */
     root: boolean;
+    /**
+     * Adds no segment to its pages' paths (Fumadocs `(name)` folder): `path` is
+     * the parent's, a top-level group's index page is the home (`""`).
+     */
+    group: boolean;
     defaultOpen: boolean;
     collapsible: boolean;
     /** The folder's own page, shown at the folder's path; null without one. */
@@ -570,8 +576,10 @@ interface HelpFilesOptions {
 /**
  * The Fumadocs virtual files for one language of the site: a `.mdx` page file
  * per page (a folder's own page as `<folder>/index.mdx`, the home page as
- * `index.mdx` at the top, any other page named `index` as `index_.mdx`) and a
- * `meta.json` per folder plus one at the top that fixes the order. Every file
+ * `index.mdx` at the top or in a top-level group, any other page named `index`
+ * as `index_.mdx`) and a `meta.json` per folder plus one at the top that fixes
+ * the order. A group folder is a `(slug)/` directory, so Fumadocs gives its
+ * pages the same addresses as the tree (no segment for the group). Every file
  * path is unique. Exported for custom setups; `createHelpSource` uses it.
  */
 declare function helpTreeToFiles(payload: HelpPublicSitePayload, options: HelpFilesOptions): HelpVirtualFile[];

package/dist/fumadocs.js

@@ -519,12 +519,13 @@ var pageFileName = (page) => {
   const name = lastSegment(page.path);
   return name === "index" ? "index_" : name;
 };
+var folderDirName = (folder) => folder.group ? `(${folder.slug})` : folder.slug;
 function helpMetaEntry(node) {
   switch (node.type) {
     case "page":
       return pageFileName(node);
     case "folder":
-      return node.slug;
+      return folderDirName(node);
     case "separator": {
       const title = node.title?.replace(/---/g, "\u2013").trim();
       if (!title) return "---";
@@ -577,9 +578,9 @@ function helpTreeToFiles(payload, options) {
   const addChildren = (nodes, dir) => {
     for (const node of nodes) {
       if (node.type === "page") {
-        addPage(node, node.path ? join(dir, ext(pageFileName(node), "mdx")) : ext("index", "mdx"));
+        addPage(node, join(dir, ext(pageFileName(node), "mdx")));
       } else if (node.type === "folder") {
-        addFolder(node, join(dir, node.slug));
+        addFolder(node, join(dir, folderDirName(node)));
       }
     }
   };

package/dist/index.d.cts

@@ -139,7 +139,8 @@ declare function verifyWebhookSignature(secret: string, rawBody: WebhookBody, he
  * preview token names. Absent values are `null`, never a missing key.
  *
  * Paths: a page's path is its folder slugs plus its slug, without leading or
- * trailing slash (`guides/login`); the site's home page has the path `""`.
+ * trailing slash (`guides/login`) — a `group` folder adds no slug; the site's
+ * home page has the path `""`.
  */
 /** The doc site itself. */
 interface HelpPublicSite {
@@ -170,12 +171,17 @@ interface HelpPublicTreeFolder {
     /** Stable node id. */
     id: string;
     slug: string;
-    /** The folder's path (its index page, if any, lives here). */
+    /** The folder's path (its index page, if any, lives here; a group's is its parent's). */
     path: string;
     title: string;
     icon: string | null;
     /** A tab (top level only; Fumadocs `root`). */
     root: boolean;
+    /**
+     * Adds no segment to its pages' paths (Fumadocs `(name)` folder): `path` is
+     * the parent's, a top-level group's index page is the home (`""`).
+     */
+    group: boolean;
     defaultOpen: boolean;
     collapsible: boolean;
     /** The folder's own page, shown at the folder's path; null without one. */

package/dist/index.d.ts

@@ -139,7 +139,8 @@ declare function verifyWebhookSignature(secret: string, rawBody: WebhookBody, he
  * preview token names. Absent values are `null`, never a missing key.
  *
  * Paths: a page's path is its folder slugs plus its slug, without leading or
- * trailing slash (`guides/login`); the site's home page has the path `""`.
+ * trailing slash (`guides/login`) — a `group` folder adds no slug; the site's
+ * home page has the path `""`.
  */
 /** The doc site itself. */
 interface HelpPublicSite {
@@ -170,12 +171,17 @@ interface HelpPublicTreeFolder {
     /** Stable node id. */
     id: string;
     slug: string;
-    /** The folder's path (its index page, if any, lives here). */
+    /** The folder's path (its index page, if any, lives here; a group's is its parent's). */
     path: string;
     title: string;
     icon: string | null;
     /** A tab (top level only; Fumadocs `root`). */
     root: boolean;
+    /**
+     * Adds no segment to its pages' paths (Fumadocs `(name)` folder): `path` is
+     * the parent's, a top-level group's index page is the home (`""`).
+     */
+    group: boolean;
     defaultOpen: boolean;
     collapsible: boolean;
     /** The folder's own page, shown at the folder's path; null without one. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@solutiondesk/help",
-  "version": "1.14.0",
+  "version": "1.15.1",
   "description": "Typed, zero-dependency client for the SolutionDesk public help center API, plus a Fumadocs adapter: navigation, pages, search, previews, llms.txt and webhook verification.",
   "keywords": [
     "solutiondesk",