nimbus-docs 0.1.3 → 0.1.5

package/dist/types.d.ts

@@ -1,3 +1,5 @@
+import { a as SeverityConfig, i as Severity, n as DiagnosticFix, r as RuleCode, t as Diagnostic } from "./diagnostic-DZf0z79l.js";
+
 //#region src/types.d.ts
 /**
  * Public type surface for `nimbus-docs/types`.
@@ -7,8 +9,6 @@ interface NimbusConfig {
   site: string;
   title: string;
   description?: string;
-  /** Short text or symbol (max ~2 chars) used in the header logo. */
-  logo: string;
   locale?: string;
   /** Label for the "Home" breadcrumb / root link. */
   homeLabel?: string;
@@ -16,8 +16,6 @@ interface NimbusConfig {
   github?: string | null;
   /** Edit-link URL pattern. `{path}` is replaced with the doc's repo path. */
   editPattern?: string | null;
-  /** Footer text. */
-  footer?: string;
   /**
    * Site-wide social/OG fallback image. Site-relative (e.g. `/og.png`) or
    * absolute URL. Used when a page doesn't supply its own `socialImage`
@@ -29,6 +27,14 @@ interface NimbusConfig {
   /** Site-wide head elements (meta, link, script, style). */
   head?: HeadElement[];
   sidebar?: SidebarConfig;
+  /**
+   * Site-wide chrome toggles. Both fields default to `true` (render).
+   * Per-page frontmatter (`sidebar: false`, `tableOfContents: false`) can
+   * override the site-wide default in the "off" direction. Merge is AND:
+   * chrome renders only when BOTH the site-wide flag AND the per-page
+   * field agree. There is no per-page opt-in to override a site-wide
+   * `false` — if you've turned a column off site-wide, it stays off.
+   */
   features?: FeaturesConfig;
   /**
    * Search backend. Absent means Pagefind. `false` disables framework search
@@ -93,7 +99,12 @@ interface VersionPageRef {
   version: string;
   /** Page slug (entry.id) within the collection. */
   slug: string;
-  /** Resolved URL path with leading slash, no trailing slash. */
+  /**
+   * Resolved URL path under the site, browser-href form: leading slash
+   * and a trailing slash on HTML document routes (`/v1/foo/`). Consumers
+   * (`<link rel="alternate">`, `<link rel="canonical">`, version picker)
+   * render this directly into `<a href>` / `<link href>`.
+   */
   url: string;
 }
 /**
@@ -130,11 +141,25 @@ interface VersionStatus {
   isDeprecated: boolean;
   isHidden: boolean;
 }
+/**
+ * Site-wide chrome toggles. Each field is a kill switch for one
+ * piece of the docs layout that the user might want hidden everywhere.
+ * Per-page frontmatter (`sidebar: false`, `tableOfContents: false`) can
+ * additionally turn a column off for individual pages even when the
+ * site-wide flag is `true`.
+ *
+ * Kept intentionally narrow — fields here exist because they need to
+ * thread through layout + header + mobile dialog (non-trivial to remove
+ * by user-side edits alone). Everything else that "could be a feature
+ * flag" is instead handled by editing user-owned files (delete the
+ * `<Pagination />` from `DocsLayout.astro`, drop `editPattern` to hide
+ * edit links, etc.).
+ */
 interface FeaturesConfig {
-  search?: boolean;
-  editLinks?: boolean;
-  pagination?: boolean;
-  toc?: boolean;
+  /** Render the sidebar column site-wide. Default `true`. */
+  sidebar?: boolean;
+  /** Render the table-of-contents column site-wide. Default `true`. */
+  tableOfContents?: boolean;
 }
 interface SearchConfig {
   provider?: "pagefind" | "custom";
@@ -320,7 +345,6 @@ interface BannerProps {
  * Every field is something the Nimbus framework knows how to handle:
  *   - `head` entries get concatenated with `config.head` in the layout.
  *   - `noindex` emits `<meta name="robots" content="noindex">`.
- *   - `aiDeprioritize` signals AI crawlers via the conventional meta.
  *   - `title` / `description` populate `<title>` / `<meta name="description">`.
  */
 interface BasePageProps {
@@ -330,8 +354,6 @@ interface BasePageProps {
   head?: HeadElement[];
   /** Emit `<meta name="robots" content="noindex">`. */
   noindex?: boolean;
-  /** Signal AI crawlers to deprioritize this page. */
-  aiDeprioritize?: boolean;
   /** Absolute or site-relative URL for this page's markdown variant. */
   markdownUrl?: string;
   /**
@@ -377,25 +399,44 @@ interface BasePageProps {
  * project-specific extras.
  */
 interface DocsPageProps extends BasePageProps {
-  /** Layout variant. `"splash"` skips the sidebar / TOC chrome. */
-  template?: "doc" | "splash";
-  /** Hide the search index entry for this page. */
-  pagefind?: boolean;
+  /**
+   * Layout mode. `"custom"` skips all chrome (sidebar, TOC, pagination) —
+   * the framework gets out of the way for landing pages and custom layouts.
+   * Per-key toggles (`sidebar: false`, `tableOfContents: false`, etc.) can
+   * override individual pieces regardless of mode.
+   */
+  mode?: "doc" | "custom";
+  /**
+   * Whether the page is in the site search index. When undefined, derives
+   * from `noindex`: a non-crawlable page is by default not searchable.
+   */
+  searchable?: boolean;
   /** Don't render in production; treat as `noindex` in dev. */
   draft?: boolean;
   /** URL pointing at this page's source on the repo host (computed from `config.editPattern`). */
   editUrl?: string;
   /** Optional top-of-page banner. */
   banner?: BannerProps;
-  /** From `getSidebar()`. */
-  sidebar: SidebarItem[];
-  /** From `getTOC()`. */
-  headings: TOCItem[];
+  /**
+   * From `getSidebar()`. Pass `false` when the page opted out via
+   * `sidebar: false` in frontmatter — the layout treats `false` as
+   * "suppress all sidebar chrome" (desktop rail, mobile dialog, and the
+   * header menu button that opens it). An empty array still renders the
+   * column shell.
+   */
+  sidebar: SidebarItem[] | false;
+  /**
+   * From `getTOC()`. Pass `false` when the page opted out via
+   * `tableOfContents: false` in frontmatter — the layout treats `false`
+   * as "suppress the TOC rail entirely" rather than rendering an empty
+   * column.
+   */
+  headings: TOCItem[] | false;
   /** From `getBreadcrumbs()`. */
   breadcrumbs: Breadcrumb[];
   /** From `getPrevNext()`. */
   prevNext: PrevNext;
 }
 //#endregion
-export { BadgeVariant, BannerProps, BasePageProps, Breadcrumb, DocsPageProps, FeaturesConfig, HeadElement, NimbusConfig, PrevNext, PrevNextLink, PrevNextOverrides, ResolvedVersions, SearchConfig, SearchProvider, SearchResult, SidebarBadge, SidebarConfig, SidebarConfigItem, SidebarExternalLinkItem, SidebarGroupItem, SidebarItem, SidebarLinkItem, SidebarSection, TOCItem, VersionAlternateRecord, VersionAlternatesTable, VersionPageRef, VersionStatus, VersionsConfig };
+export { BadgeVariant, BannerProps, BasePageProps, Breadcrumb, type Diagnostic, type DiagnosticFix, DocsPageProps, FeaturesConfig, HeadElement, NimbusConfig, PrevNext, PrevNextLink, PrevNextOverrides, ResolvedVersions, type RuleCode, SearchConfig, SearchProvider, SearchResult, type Severity, type SeverityConfig, SidebarBadge, SidebarConfig, SidebarConfigItem, SidebarExternalLinkItem, SidebarGroupItem, SidebarItem, SidebarLinkItem, SidebarSection, TOCItem, VersionAlternateRecord, VersionAlternatesTable, VersionPageRef, VersionStatus, VersionsConfig };
 //# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","names":[],"sources":["../src/types.ts"],"mappings":"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"}
+{"version":3,"file":"types.d.ts","names":[],"sources":["../src/types.ts"],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nimbus-docs",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "private": false,
   "type": "module",
   "description": "Docs, for humans and agents",
@@ -66,16 +66,32 @@
     "@clack/prompts": "^0.9.1",
     "@shikijs/transformers": "^4.1.0",
     "@vercel/detect-agent": "^1.2.3",
-    "mri": "^1.2.0"
+    "mri": "^1.2.0",
+    "satteri": "^0.6.3",
+    "yaml": "^2.7.1"
   },
   "devDependencies": {
+    "@shikijs/types": "^4.1.0",
     "astro": "^6.4.0",
+    "github-slugger": "^2.0.0",
+    "remark-lint-emphasis-marker": "^4.0.1",
+    "remark-lint-fenced-code-flag": "^4.2.0",
+    "remark-lint-heading-increment": "^4.0.1",
+    "remark-lint-no-duplicate-headings": "^4.0.1",
+    "remark-lint-no-heading-punctuation": "^4.0.1",
+    "remark-lint-no-literal-urls": "^4.0.1",
+    "remark-lint-no-multiple-toplevel-headings": "^4.0.1",
+    "remark-lint-unordered-list-marker-style": "^4.0.1",
     "tsdown": "^0.20.3",
-    "typescript": "^5.8.3"
+    "tsx": "^4.22.3",
+    "typescript": "^5.8.3",
+    "unified": "^11.0.5",
+    "vfile": "^6.0.3"
   },
   "scripts": {
     "build": "tsdown",
     "dev": "tsdown --watch",
-    "typecheck": "tsc --noEmit"
+    "typecheck": "tsc --noEmit",
+    "test": "node --import tsx --test \"test/**/*.test.ts\""
   }
 }

package/src/components/NimbusHead.astro

@@ -43,8 +43,6 @@ export interface Props {
   description?: string;
   /** Emit `<meta name="robots" content="noindex">`. */
   noindex?: boolean;
-  /** Emit `<meta name="ai-deprioritize" content="true">`. */
-  aiDeprioritize?: boolean;
   /** Absolute or site-relative URL for the markdown variant of this page. */
   markdownUrl?: string;
   /**
@@ -73,7 +71,6 @@ const {
   title,
   description,
   noindex,
-  aiDeprioritize,
   markdownUrl,
   socialImage,
   lastUpdated,
@@ -209,7 +206,6 @@ const mergedHead = [...(config.head ?? []), ...pageHead];
 <meta name="generator" content={Astro.generator} />
 {resolvedDescription && <meta name="description" content={resolvedDescription} />}
 {noindex && <meta name="robots" content="noindex" />}
-{aiDeprioritize && <meta name="ai-deprioritize" content="true" />}
 
 <link rel="icon" type={faviconType} href={faviconHref} />
 {hasSite && canonical && <link rel="canonical" href={canonical} />}