@blaaiz/docs-core 0.4.0 → 0.5.0

package/dist/index.d.cts

@@ -645,6 +645,21 @@ interface PlannedApiGroup {
     /** 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.
  *
@@ -668,11 +683,10 @@ interface DocsTreePlan {
     /** Fully-known meta files: the root, doc tab folders, and doc groups. */
     readonly metas: readonly PlannedMeta[];
     /**
-     * Doc pages declared inside API tabs. The plan cannot place them in the
-     * generated folders, so the generator reports them instead of dropping them
-     * silently; they stay reachable at their own URLs.
+     * Doc pages declared inside API tabs, each linked into its group's meta at
+     * its declared position.
      */
-    readonly apiTabDocPages: readonly string[];
+    readonly apiDocLinks: readonly PlannedApiDocLink[];
 }
 /**
  * Options for {@link planDocsTree}.
@@ -1280,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 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 };
+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

@@ -645,6 +645,21 @@ interface PlannedApiGroup {
     /** 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.
  *
@@ -668,11 +683,10 @@ interface DocsTreePlan {
     /** Fully-known meta files: the root, doc tab folders, and doc groups. */
     readonly metas: readonly PlannedMeta[];
     /**
-     * Doc pages declared inside API tabs. The plan cannot place them in the
-     * generated folders, so the generator reports them instead of dropping them
-     * silently; they stay reachable at their own URLs.
+     * Doc pages declared inside API tabs, each linked into its group's meta at
+     * its declared position.
      */
-    readonly apiTabDocPages: readonly string[];
+    readonly apiDocLinks: readonly PlannedApiDocLink[];
 }
 /**
  * Options for {@link planDocsTree}.
@@ -1280,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 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 };
+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-JHN5XQPU.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.4.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.