@blaaiz/docs-core 0.3.0 → 0.5.0

package/dist/index.d.cts

@@ -617,15 +617,48 @@ interface PlannedApiPage {
     /** Position within the group. */
     readonly order: number;
 }
+/**
+ * A child folder of a planned API group, at its position among the group's
+ * pages. The generator merges these with the resolved page slugs to write the
+ * group's `meta.json` in declared order.
+ *
+ * @public
+ */
+interface PlannedGroupChild {
+    readonly order: number;
+    /** The child folder's name within the group directory. */
+    readonly folder: string;
+}
 /**
  * A planned API group folder. The generator fills its page order once the
- * operation slugs are known.
+ * operation slugs are known, interleaving {@link PlannedGroupChild} folders at
+ * their declared positions. A group with `root: true` is an API tab's folder.
  *
  * @public
  */
 interface PlannedApiGroup {
     readonly dir: string;
     readonly title: string;
+    readonly children: readonly PlannedGroupChild[];
+    /** Set on an API tab's own folder, so the sidebar scopes to the tab. */
+    readonly root?: boolean;
+    /** The tab's icon, on a `root` group. */
+    readonly icon?: string;
+}
+/**
+ * A doc page declared inside an API tab, at its position among the group's
+ * operations. The generator links it into the group's `meta.json`: the page
+ * keeps living in its own folder, outside the generated tree.
+ *
+ * @public
+ */
+interface PlannedApiDocLink {
+    /** Page path relative to the docs output directory, without extension. */
+    readonly file: string;
+    /** The generated group folder whose meta lists the link. */
+    readonly dir: string;
+    /** Position within the group. */
+    readonly order: number;
 }
 /**
  * A `meta.json` file the plan wants written.
@@ -647,8 +680,13 @@ interface DocsTreePlan {
     readonly specs: readonly string[];
     readonly apiPages: readonly PlannedApiPage[];
     readonly apiGroups: readonly PlannedApiGroup[];
-    /** Fully-known meta files: the root, tab folders, and doc groups. */
+    /** Fully-known meta files: the root, doc tab folders, and doc groups. */
     readonly metas: readonly PlannedMeta[];
+    /**
+     * Doc pages declared inside API tabs, each linked into its group's meta at
+     * its declared position.
+     */
+    readonly apiDocLinks: readonly PlannedApiDocLink[];
 }
 /**
  * Options for {@link planDocsTree}.
@@ -656,23 +694,27 @@ interface DocsTreePlan {
  * @public
  */
 interface PlanDocsTreeOptions {
-    /** Folder for generated API pages. Default `api`. */
+    /** Folder for generated API pages when one tab publishes them. Default `api`. */
     readonly apiDir?: string;
 }
 /**
  * Plan the content tree for a navigation.
  *
  * Conventions (Mintlify-shaped):
- * - A tab whose items reference OpenAPI files becomes the API tab; its groups
- *   become folders under `apiDir`, named by slugified group title.
+ * - A tab whose items reference OpenAPI files becomes an API tab. With one API
+ *   tab its folder is `apiDir`; with several, each tab's folder is its
+ *   slugified title, so tabs never collide. Groups become nested folders named
+ *   by slugified group title, to any depth.
  * - A tab of doc pages becomes the folder its pages share (their first path
- *   segment); a doc group's pages must share one directory.
+ *   segment); a doc group's pages must share one directory. Doc groups nest.
  * - Root-level doc pages (no `/` in the path) are listed in the root meta.
  * - Tab folders get `root: true`, so the sidebar scopes to the active tab.
+ * - Sidebar order is declaration order, pages and groups interleaved.
  *
  * @param navigation - the parsed navigation
  * @param options - the API folder name
  * @returns the plan the generator executes
+ * @throws when two sibling groups slugify to the same folder
  * @public
  */
 declare function planDocsTree(navigation: Navigation, options?: PlanDocsTreeOptions): DocsTreePlan;
@@ -1252,4 +1294,4 @@ declare class OpenApiMergeError extends Error {
  */
 declare function mergeOpenApiDocuments(inputs: readonly unknown[], options: MergeOpenApiOptions): OpenApiDocument;
 
-export { AiConfig, type AiMessage, type AskAiDocumentsSource, type AskAiRoute, type AskAiRouteOptions, type AskAiSource, type AuthGateOptions, type BuildSitemapOptions, type CreateMarkdownRouteOptions, type CreateTryItProxyOptions, DocsConfig, type DocsMetadata, type DocsRobots, type DocsSitemapEntry, type DocsTreePlan, type EmailSignInOptions, type FetchLike, type GoogleAuthHandlers, type GoogleAuthOptions, type IndexedDocument, InvalidNavigationError, type MarkdownRoute, type MdxReader, type MdxToMarkdownOptions, type MergeOpenApiOptions, Navigation, OpenApiDocument, OpenApiInfo, OpenApiMergeError, type OpenApiOperationRef, OpenApiServer, type PageSeo, type PlanDocsTreeOptions, type PlannedApiGroup, type PlannedApiPage, type PlannedMeta, ProxyTargetError, SESSION_COOKIE, type SearchDocument, type SearchIndex, type SearchResult, type SecretSignInOptions, type SessionPayload, type SignOutOptions, type SiteAuth, type SiteAuthOptions, type SitemapChangeFrequency, type SitemapEntry, ThemeConfig, type TryItEnvelope, type TryItProxyRoute, assertAllowedTarget, buildMetadata, buildRobots, buildSearchIndex, buildSessionCookie, buildSitemap, buildThemeCss, clearSessionCookie, createAskAiRoute, createAuthGate, createEmailSignIn, createGoogleAuth, createMarkdownRoute, createSecretSignIn, createSignOut, createSiteAuth, createTryItProxy, createTryItProxyRoute, isAllowedEmail, mdxToMarkdown, mergeOpenApiDocuments, openApiOperationToMarkdown, parseNavigation, planDocsTree, readCookie, searchIndex, signSession, unwrapProxyTarget, verifySession };
+export { AiConfig, type AiMessage, type AskAiDocumentsSource, type AskAiRoute, type AskAiRouteOptions, type AskAiSource, type AuthGateOptions, type BuildSitemapOptions, type CreateMarkdownRouteOptions, type CreateTryItProxyOptions, DocsConfig, type DocsMetadata, type DocsRobots, type DocsSitemapEntry, type DocsTreePlan, type EmailSignInOptions, type FetchLike, type GoogleAuthHandlers, type GoogleAuthOptions, type IndexedDocument, InvalidNavigationError, type MarkdownRoute, type MdxReader, type MdxToMarkdownOptions, type MergeOpenApiOptions, Navigation, OpenApiDocument, OpenApiInfo, OpenApiMergeError, type OpenApiOperationRef, OpenApiServer, type PageSeo, type PlanDocsTreeOptions, type PlannedApiDocLink, type PlannedApiGroup, type PlannedApiPage, type PlannedGroupChild, type PlannedMeta, ProxyTargetError, SESSION_COOKIE, type SearchDocument, type SearchIndex, type SearchResult, type SecretSignInOptions, type SessionPayload, type SignOutOptions, type SiteAuth, type SiteAuthOptions, type SitemapChangeFrequency, type SitemapEntry, ThemeConfig, type TryItEnvelope, type TryItProxyRoute, assertAllowedTarget, buildMetadata, buildRobots, buildSearchIndex, buildSessionCookie, buildSitemap, buildThemeCss, clearSessionCookie, createAskAiRoute, createAuthGate, createEmailSignIn, createGoogleAuth, createMarkdownRoute, createSecretSignIn, createSignOut, createSiteAuth, createTryItProxy, createTryItProxyRoute, isAllowedEmail, mdxToMarkdown, mergeOpenApiDocuments, openApiOperationToMarkdown, parseNavigation, planDocsTree, readCookie, searchIndex, signSession, unwrapProxyTarget, verifySession };

package/dist/index.d.ts

@@ -617,15 +617,48 @@ interface PlannedApiPage {
     /** Position within the group. */
     readonly order: number;
 }
+/**
+ * A child folder of a planned API group, at its position among the group's
+ * pages. The generator merges these with the resolved page slugs to write the
+ * group's `meta.json` in declared order.
+ *
+ * @public
+ */
+interface PlannedGroupChild {
+    readonly order: number;
+    /** The child folder's name within the group directory. */
+    readonly folder: string;
+}
 /**
  * A planned API group folder. The generator fills its page order once the
- * operation slugs are known.
+ * operation slugs are known, interleaving {@link PlannedGroupChild} folders at
+ * their declared positions. A group with `root: true` is an API tab's folder.
  *
  * @public
  */
 interface PlannedApiGroup {
     readonly dir: string;
     readonly title: string;
+    readonly children: readonly PlannedGroupChild[];
+    /** Set on an API tab's own folder, so the sidebar scopes to the tab. */
+    readonly root?: boolean;
+    /** The tab's icon, on a `root` group. */
+    readonly icon?: string;
+}
+/**
+ * A doc page declared inside an API tab, at its position among the group's
+ * operations. The generator links it into the group's `meta.json`: the page
+ * keeps living in its own folder, outside the generated tree.
+ *
+ * @public
+ */
+interface PlannedApiDocLink {
+    /** Page path relative to the docs output directory, without extension. */
+    readonly file: string;
+    /** The generated group folder whose meta lists the link. */
+    readonly dir: string;
+    /** Position within the group. */
+    readonly order: number;
 }
 /**
  * A `meta.json` file the plan wants written.
@@ -647,8 +680,13 @@ interface DocsTreePlan {
     readonly specs: readonly string[];
     readonly apiPages: readonly PlannedApiPage[];
     readonly apiGroups: readonly PlannedApiGroup[];
-    /** Fully-known meta files: the root, tab folders, and doc groups. */
+    /** Fully-known meta files: the root, doc tab folders, and doc groups. */
     readonly metas: readonly PlannedMeta[];
+    /**
+     * Doc pages declared inside API tabs, each linked into its group's meta at
+     * its declared position.
+     */
+    readonly apiDocLinks: readonly PlannedApiDocLink[];
 }
 /**
  * Options for {@link planDocsTree}.
@@ -656,23 +694,27 @@ interface DocsTreePlan {
  * @public
  */
 interface PlanDocsTreeOptions {
-    /** Folder for generated API pages. Default `api`. */
+    /** Folder for generated API pages when one tab publishes them. Default `api`. */
     readonly apiDir?: string;
 }
 /**
  * Plan the content tree for a navigation.
  *
  * Conventions (Mintlify-shaped):
- * - A tab whose items reference OpenAPI files becomes the API tab; its groups
- *   become folders under `apiDir`, named by slugified group title.
+ * - A tab whose items reference OpenAPI files becomes an API tab. With one API
+ *   tab its folder is `apiDir`; with several, each tab's folder is its
+ *   slugified title, so tabs never collide. Groups become nested folders named
+ *   by slugified group title, to any depth.
  * - A tab of doc pages becomes the folder its pages share (their first path
- *   segment); a doc group's pages must share one directory.
+ *   segment); a doc group's pages must share one directory. Doc groups nest.
  * - Root-level doc pages (no `/` in the path) are listed in the root meta.
  * - Tab folders get `root: true`, so the sidebar scopes to the active tab.
+ * - Sidebar order is declaration order, pages and groups interleaved.
  *
  * @param navigation - the parsed navigation
  * @param options - the API folder name
  * @returns the plan the generator executes
+ * @throws when two sibling groups slugify to the same folder
  * @public
  */
 declare function planDocsTree(navigation: Navigation, options?: PlanDocsTreeOptions): DocsTreePlan;
@@ -1252,4 +1294,4 @@ declare class OpenApiMergeError extends Error {
  */
 declare function mergeOpenApiDocuments(inputs: readonly unknown[], options: MergeOpenApiOptions): OpenApiDocument;
 
-export { AiConfig, type AiMessage, type AskAiDocumentsSource, type AskAiRoute, type AskAiRouteOptions, type AskAiSource, type AuthGateOptions, type BuildSitemapOptions, type CreateMarkdownRouteOptions, type CreateTryItProxyOptions, DocsConfig, type DocsMetadata, type DocsRobots, type DocsSitemapEntry, type DocsTreePlan, type EmailSignInOptions, type FetchLike, type GoogleAuthHandlers, type GoogleAuthOptions, type IndexedDocument, InvalidNavigationError, type MarkdownRoute, type MdxReader, type MdxToMarkdownOptions, type MergeOpenApiOptions, Navigation, OpenApiDocument, OpenApiInfo, OpenApiMergeError, type OpenApiOperationRef, OpenApiServer, type PageSeo, type PlanDocsTreeOptions, type PlannedApiGroup, type PlannedApiPage, type PlannedMeta, ProxyTargetError, SESSION_COOKIE, type SearchDocument, type SearchIndex, type SearchResult, type SecretSignInOptions, type SessionPayload, type SignOutOptions, type SiteAuth, type SiteAuthOptions, type SitemapChangeFrequency, type SitemapEntry, ThemeConfig, type TryItEnvelope, type TryItProxyRoute, assertAllowedTarget, buildMetadata, buildRobots, buildSearchIndex, buildSessionCookie, buildSitemap, buildThemeCss, clearSessionCookie, createAskAiRoute, createAuthGate, createEmailSignIn, createGoogleAuth, createMarkdownRoute, createSecretSignIn, createSignOut, createSiteAuth, createTryItProxy, createTryItProxyRoute, isAllowedEmail, mdxToMarkdown, mergeOpenApiDocuments, openApiOperationToMarkdown, parseNavigation, planDocsTree, readCookie, searchIndex, signSession, unwrapProxyTarget, verifySession };
+export { AiConfig, type AiMessage, type AskAiDocumentsSource, type AskAiRoute, type AskAiRouteOptions, type AskAiSource, type AuthGateOptions, type BuildSitemapOptions, type CreateMarkdownRouteOptions, type CreateTryItProxyOptions, DocsConfig, type DocsMetadata, type DocsRobots, type DocsSitemapEntry, type DocsTreePlan, type EmailSignInOptions, type FetchLike, type GoogleAuthHandlers, type GoogleAuthOptions, type IndexedDocument, InvalidNavigationError, type MarkdownRoute, type MdxReader, type MdxToMarkdownOptions, type MergeOpenApiOptions, Navigation, OpenApiDocument, OpenApiInfo, OpenApiMergeError, type OpenApiOperationRef, OpenApiServer, type PageSeo, type PlanDocsTreeOptions, type PlannedApiDocLink, type PlannedApiGroup, type PlannedApiPage, type PlannedGroupChild, type PlannedMeta, ProxyTargetError, SESSION_COOKIE, type SearchDocument, type SearchIndex, type SearchResult, type SecretSignInOptions, type SessionPayload, type SignOutOptions, type SiteAuth, type SiteAuthOptions, type SitemapChangeFrequency, type SitemapEntry, ThemeConfig, type TryItEnvelope, type TryItProxyRoute, assertAllowedTarget, buildMetadata, buildRobots, buildSearchIndex, buildSessionCookie, buildSitemap, buildThemeCss, clearSessionCookie, createAskAiRoute, createAuthGate, createEmailSignIn, createGoogleAuth, createMarkdownRoute, createSecretSignIn, createSignOut, createSiteAuth, createTryItProxy, createTryItProxyRoute, isAllowedEmail, mdxToMarkdown, mergeOpenApiDocuments, openApiOperationToMarkdown, parseNavigation, planDocsTree, readCookie, searchIndex, signSession, unwrapProxyTarget, verifySession };

package/dist/index.js

@@ -1,3 +1,3 @@
-export { AI_PROVIDER_MODELS, AI_PROVIDER_NAMES, AiConfigError, DocsConfigError, InvalidNavigationError, OpenApiMergeError, ProxyTargetError, SESSION_COOKIE, assertAllowedTarget, buildMetadata, buildRobots, buildSearchIndex, buildSessionCookie, buildSitemap, buildThemeCss, clearSessionCookie, createAskAiRoute, createAuthGate, createEmailSignIn, createGoogleAuth, createMarkdownRoute, createSecretSignIn, createSignOut, createSiteAuth, createTryItProxy, createTryItProxyRoute, defineDocsConfig, isAllowedEmail, mdxToMarkdown, mergeOpenApiDocuments, openApiOperationToMarkdown, parseNavigation, planDocsTree, readCookie, resolveAiConfig, searchIndex, signSession, unwrapProxyTarget, validateDocsConfig, verifySession } from './chunk-ICDBGTIJ.js';
+export { AI_PROVIDER_MODELS, AI_PROVIDER_NAMES, AiConfigError, DocsConfigError, InvalidNavigationError, OpenApiMergeError, ProxyTargetError, SESSION_COOKIE, assertAllowedTarget, buildMetadata, buildRobots, buildSearchIndex, buildSessionCookie, buildSitemap, buildThemeCss, clearSessionCookie, createAskAiRoute, createAuthGate, createEmailSignIn, createGoogleAuth, createMarkdownRoute, createSecretSignIn, createSignOut, createSiteAuth, createTryItProxy, createTryItProxyRoute, defineDocsConfig, isAllowedEmail, mdxToMarkdown, mergeOpenApiDocuments, openApiOperationToMarkdown, parseNavigation, planDocsTree, readCookie, resolveAiConfig, searchIndex, signSession, unwrapProxyTarget, validateDocsConfig, verifySession } from './chunk-ZWDLAW5M.js';
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blaaiz/docs-core",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "description": "Neutral, self-hostable documentation framework core — navigation parsing, OpenAPI merging, MDX doc components, and a hardened try-it proxy. Config and content live in each consuming site.",
   "keywords": [
     "documentation",

package/skills/SKILL.md

@@ -264,6 +264,11 @@ them is a one-file change:
   carrying the `home-*` classes from `@blaaiz/docs-core/styles/home.css`.
   Clicking a link enters the sidebar shell under `/docs`. Sites scaffolded by
   `create-docs-core` ship this shape.
+
+  In an `.mdx` file, never wrap loose text in a literal `<p>`: MDX wraps
+  multi-line text in its own paragraph element, which nests `<p>` inside
+  `<p>` and breaks hydration. Use a `<div>` with the same class.
+
 - **No landing**: the file is a three-line `redirect('/docs')` and readers
   land directly in the docs.