nimbus-docs 0.1.2 → 0.1.4

package/dist/types.d.ts

@@ -7,8 +7,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 +14,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 +25,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
@@ -130,11 +134,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";
@@ -254,6 +272,16 @@ interface SidebarGroupItem {
   badge?: SidebarBadge;
   children: SidebarItem[];
   _indexId?: string;
+  /**
+   * Internal: the URL prefix where this group's content lives, when
+   * derived from an `autogenerate` config item. `deriveSidebarSections`
+   * uses this as the section's href instead of the first link's href —
+   * so a `Components` group autogenerated from a collection mounted at
+   * `/components` links the section tab to `/components` (the landing
+   * page) rather than `/components/accordion` (the alphabetically-first
+   * child).
+   */
+  _prefix?: string;
 }
 type SidebarItem = SidebarLinkItem | SidebarExternalLinkItem | SidebarGroupItem;
 interface TOCItem {
@@ -310,7 +338,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 {
@@ -320,8 +347,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;
   /**
@@ -367,20 +392,39 @@ 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()`. */

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.2",
+  "version": "0.1.4",
   "private": false,
   "type": "module",
   "description": "Docs, for humans and agents",

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,
@@ -136,17 +133,39 @@ const canonical = Astro.site
 
 const fullTitle = title !== config.title ? `${title} | ${config.title}` : title;
 const resolvedDescription = description ?? config.description;
-const faviconHref = `${import.meta.env.BASE_URL}favicon.svg`;
 const lang = config.locale ?? "en";
 
 const isHomePage = Astro.url.pathname === "/";
 const ogType = isHomePage ? "website" : "article";
 
 // `process.cwd()` resolves to the consumer's project root at build time.
-// The check lets users drop a `public/opengraph.png` and have it picked
-// up as the default social image without touching config.
-const userOpenGraphImage = join(process.cwd(), "public", "opengraph.png");
-const defaultSocialImage = existsSync(userOpenGraphImage) ? "/opengraph.png" : "/og.png";
+// The checks below let users drop files into `public/` and have them
+// picked up automatically — no config touch needed.
+const publicDir = join(process.cwd(), "public");
+
+// Favicon precedence: svg > ico > png. The first file that exists wins;
+// when none exists we still emit the svg link so users who drop one in
+// later don't need to touch the layout.
+const faviconCandidates: ReadonlyArray<{ file: string; type: string }> = [
+  { file: "favicon.svg", type: "image/svg+xml" },
+  { file: "favicon.ico", type: "image/x-icon" },
+  { file: "favicon.png", type: "image/png" },
+];
+const matchedFavicon =
+  faviconCandidates.find((c) => existsSync(join(publicDir, c.file))) ??
+  faviconCandidates[0];
+const faviconHref = `${import.meta.env.BASE_URL}${matchedFavicon.file}`;
+const faviconType = matchedFavicon.type;
+
+// Social image precedence: page prop > config > `public/opengraph.png` >
+// `public/logo.png` > generated `/og.png` fallback.
+const userOpenGraphImage = join(publicDir, "opengraph.png");
+const userLogoImage = join(publicDir, "logo.png");
+const defaultSocialImage = existsSync(userOpenGraphImage)
+  ? "/opengraph.png"
+  : existsSync(userLogoImage)
+    ? "/logo.png"
+    : "/og.png";
 const socialImagePath = socialImage ?? config.socialImage ?? defaultSocialImage;
 const ogImage = socialImagePath
   ? Astro.site
@@ -187,9 +206,8 @@ 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="image/svg+xml" href={faviconHref} />
+<link rel="icon" type={faviconType} href={faviconHref} />
 {hasSite && canonical && <link rel="canonical" href={canonical} />}
 {hasSite && <link rel="sitemap" href="/sitemap-index.xml" />}
 {markdownUrl && !isHiddenVersion && (