@marlinjai/clearify 1.20.0 → 2.1.0

package/dist/node/core/config.d.ts

@@ -37,7 +37,6 @@ declare const ClearifyDataSchema: z.ZodObject<{
         projects: z.ZodDefault<z.ZodArray<z.ZodObject<{
             name: z.ZodString;
             description: z.ZodString;
-            href: z.ZodOptional<z.ZodString>;
             repo: z.ZodOptional<z.ZodString>;
             status: z.ZodDefault<z.ZodEnum<{
                 active: "active";
@@ -48,20 +47,33 @@ declare const ClearifyDataSchema: z.ZodObject<{
             icon: z.ZodOptional<z.ZodString>;
             tags: z.ZodOptional<z.ZodArray<z.ZodString>>;
             group: z.ZodOptional<z.ZodString>;
-            mode: z.ZodOptional<z.ZodEnum<{
-                link: "link";
-                embed: "embed";
-                inject: "inject";
-            }>>;
-            git: z.ZodOptional<z.ZodObject<{
+            source: z.ZodDiscriminatedUnion<[z.ZodObject<{
+                kind: z.ZodLiteral<"none">;
+            }, z.core.$strip>, z.ZodObject<{
+                kind: z.ZodLiteral<"git">;
                 repo: z.ZodString;
                 ref: z.ZodOptional<z.ZodString>;
                 path: z.ZodOptional<z.ZodString>;
                 sparse: z.ZodOptional<z.ZodBoolean>;
-            }, z.core.$strip>>;
-            embedSections: z.ZodOptional<z.ZodUnion<readonly [z.ZodLiteral<"all">, z.ZodLiteral<"public">, z.ZodArray<z.ZodString>]>>;
-            injectInto: z.ZodOptional<z.ZodString>;
-            docsPath: z.ZodOptional<z.ZodString>;
+            }, z.core.$strip>, z.ZodObject<{
+                kind: z.ZodLiteral<"url">;
+                url: z.ZodString;
+            }, z.core.$strip>, z.ZodObject<{
+                kind: z.ZodLiteral<"inline">;
+                markdown: z.ZodString;
+            }, z.core.$strip>], "kind">;
+            placement: z.ZodDiscriminatedUnion<[z.ZodObject<{
+                kind: z.ZodLiteral<"card">;
+                href: z.ZodString;
+            }, z.core.$strip>, z.ZodObject<{
+                kind: z.ZodLiteral<"tab">;
+                sections: z.ZodOptional<z.ZodUnion<readonly [z.ZodLiteral<"all">, z.ZodLiteral<"public">, z.ZodArray<z.ZodString>]>>;
+            }, z.core.$strip>, z.ZodObject<{
+                kind: z.ZodLiteral<"nested">;
+                into: z.ZodString;
+                docsPath: z.ZodOptional<z.ZodString>;
+                group: z.ZodOptional<z.ZodString>;
+            }, z.core.$strip>], "kind">;
         }, z.core.$strip>>>;
         scan: z.ZodOptional<z.ZodString>;
         cacheDir: z.ZodOptional<z.ZodString>;

package/dist/node/core/config.js

@@ -8,7 +8,7 @@ import {
   resolveSections,
   scanHubProjects,
   writeDataConfig
-} from "../chunk-2WML2D77.js";
+} from "../chunk-ZWF6VCSQ.js";
 import "../chunk-AJBCHKBP.js";
 import {
   defineConfig

package/dist/node/core/llms-txt.d.ts

@@ -0,0 +1,54 @@
+import { ClearifyConfig } from '../types/index.js';
+
+/**
+ * A doc entry as consumed by the llms.txt generators. Produced from the
+ * scanned section data by callers (e.g. the build pipeline) so these
+ * functions stay pure string builders.
+ */
+interface LlmsDocEntry {
+    /** Page title (from frontmatter or derived). */
+    title: string;
+    /** Route path on the site, e.g. `/getting-started`. */
+    routePath: string;
+    /** Section label the page belongs to, e.g. `Documentation`. */
+    sectionLabel: string;
+    /** Raw markdown source (frontmatter optional, handled by the generator). */
+    markdown: string;
+    /**
+     * Optional flag. When true the page goes under the `## Optional` bucket at
+     * the end of llms.txt rather than the main section list. Use for auxiliary
+     * content like a changelog or roadmap.
+     */
+    optional?: boolean;
+}
+/**
+ * Generate the `llms.txt` index file content.
+ *
+ * Format:
+ *   # {name}
+ *
+ *   > {tagline}
+ *
+ *   ## {Section label}
+ *
+ *   - [Title](https://site/path): first-paragraph summary
+ *   ...
+ *
+ *   ## Optional
+ *   - [Title](https://site/path): summary
+ */
+declare function generateLlmsTxt(config: ClearifyConfig, docs: LlmsDocEntry[]): string;
+/**
+ * Generate the `llms-full.txt` bundle file content. Concatenates the entire
+ * markdown body of every doc under an H2 with a `Source:` line, so an LLM
+ * with no browsing can ingest the whole site from one file.
+ */
+declare function generateLlmsFullTxt(config: ClearifyConfig, docs: LlmsDocEntry[]): string;
+/**
+ * Read a markdown file from disk. Returned as-is, including frontmatter.
+ * Exists here so callers in the build pipeline stay thin and the unit tests
+ * can stub in-memory markdown without touching the filesystem.
+ */
+declare function readMarkdownFile(filePath: string): string;
+
+export { type LlmsDocEntry, generateLlmsFullTxt, generateLlmsTxt, readMarkdownFile };

package/dist/node/core/llms-txt.js

@@ -0,0 +1,10 @@
+import {
+  generateLlmsFullTxt,
+  generateLlmsTxt,
+  readMarkdownFile
+} from "../chunk-TVDWHKQF.js";
+export {
+  generateLlmsFullTxt,
+  generateLlmsTxt,
+  readMarkdownFile
+};

package/dist/node/{hub-register-7NF5BP3E.js → hub-register-QB73GUF2.js}

@@ -79,6 +79,7 @@ async function secretExists(token, owner, repo, name) {
   const res = await ghApiFetch(url, { headers: { Authorization: `token ${token}` } });
   return res.status === 200;
 }
+var __internal = { encryptSecret };
 async function promptSecretMode() {
   const { createInterface } = await import("readline");
   const rl = createInterface({ input: process.stdin, output: process.stdout });
@@ -212,12 +213,13 @@ async function updateHubRegistry(token, hub, project) {
     name: project.name,
     description: project.description,
     status: "active",
-    mode: "embed",
-    git: {
+    source: {
+      kind: "git",
       repo: project.gitRepoUrl,
       ref: project.gitRef,
       path: project.docsPath
-    }
+    },
+    placement: { kind: "tab" }
   };
   if (existingIdx >= 0) {
     currentData.hub.projects[existingIdx] = entry;
@@ -396,5 +398,6 @@ function printSuccessFooter(currentRepo) {
 `);
 }
 export {
+  __internal,
   registerWithHub
 };

package/dist/node/node/build.js

@@ -1,11 +1,12 @@
 import {
   buildSite
-} from "../chunk-XR4WG237.js";
+} from "../chunk-PZA4UAFG.js";
 import "../chunk-PRTER35L.js";
 import "../chunk-SCZZB7OE.js";
-import "../chunk-GWYMXKDL.js";
+import "../chunk-TVDWHKQF.js";
+import "../chunk-Q5FUAK6J.js";
 import "../chunk-B2Q23JW3.js";
-import "../chunk-2WML2D77.js";
+import "../chunk-ZWF6VCSQ.js";
 import "../chunk-AJBCHKBP.js";
 import "../chunk-V7LLYIRO.js";
 import "../chunk-CTL4YL7C.js";

package/dist/node/node/check.js

@@ -1,8 +1,8 @@
 import {
   checkFrontmatter,
   checkLinks
-} from "../chunk-HZRIVY25.js";
-import "../chunk-2WML2D77.js";
+} from "../chunk-GZE6QLJT.js";
+import "../chunk-ZWF6VCSQ.js";
 import "../chunk-AJBCHKBP.js";
 import "../chunk-V7LLYIRO.js";
 import "../chunk-CTL4YL7C.js";

package/dist/node/node/index.js

@@ -1,25 +1,26 @@
 import {
   buildSite
-} from "../chunk-XR4WG237.js";
+} from "../chunk-PZA4UAFG.js";
 import {
   remarkMermaidToComponent
 } from "../chunk-PRTER35L.js";
 import "../chunk-SCZZB7OE.js";
+import "../chunk-TVDWHKQF.js";
 import {
   clearifyPlugin
-} from "../chunk-GWYMXKDL.js";
+} from "../chunk-Q5FUAK6J.js";
 import "../chunk-B2Q23JW3.js";
 import {
   init
-} from "../chunk-JZZ2BNIL.js";
+} from "../chunk-GPBEDIOY.js";
 import {
   checkFrontmatter,
   checkLinks
-} from "../chunk-HZRIVY25.js";
+} from "../chunk-GZE6QLJT.js";
 import {
   loadUserConfig,
   resolveConfig
-} from "../chunk-2WML2D77.js";
+} from "../chunk-ZWF6VCSQ.js";
 import "../chunk-AJBCHKBP.js";
 import "../chunk-V7LLYIRO.js";
 import "../chunk-CTL4YL7C.js";

package/dist/node/node/init.js

@@ -1,6 +1,6 @@
 import {
   init
-} from "../chunk-JZZ2BNIL.js";
+} from "../chunk-GPBEDIOY.js";
 export {
   init
 };

package/dist/node/types/index.d.ts

@@ -58,10 +58,16 @@ interface ClearifyConfig {
         [key: string]: string | undefined;
     };
     hub?: HubConfig;
-    hubProject?: Omit<HubProject, 'name'>;
+    hubProject?: HubProjectPartial;
     customCss?: string;
     headTags?: string[];
     includeReadme?: boolean;
+    /**
+     * When true (default), `clearify build` writes `llms.txt` and
+     * `llms-full.txt` into the output directory for AI agents and crawlers.
+     * Requires `siteUrl` to be set. Set to `false` to skip generation.
+     */
+    generateLlmsTxt?: boolean;
 }
 interface NavigationItem {
     label: string;
@@ -92,10 +98,54 @@ interface RouteEntry {
     componentPath?: string;
     redirectTo?: string;
 }
+/**
+ * Where a hub project's content comes from.
+ *
+ * `none`: no content pulled, card links out only.
+ * `git`: sparse-clone a repo subdirectory.
+ * `url`: reserved for future remote-docs fetch, not implemented.
+ * `inline`: reserved for future inline markdown, not implemented.
+ */
+type HubProjectSource = {
+    kind: 'none';
+} | {
+    kind: 'git';
+    repo: string;
+    /** branch, tag, or SHA. Default: 'main' */
+    ref?: string;
+    /** subdirectory to sparse-checkout. Default: 'docs/public' */
+    path?: string;
+    /** defaults to true when path is set */
+    sparse?: boolean;
+} | {
+    kind: 'url';
+    url: string;
+} | {
+    kind: 'inline';
+    markdown: string;
+};
+/**
+ * How a hub project shows up in the hub UI.
+ *
+ * `card`: grid entry that links to an external href.
+ * `tab`: full tab in the hub nav, rendering the cloned sections.
+ * `nested`: folded into an existing hub section as a subfolder.
+ */
+type HubProjectPlacement = {
+    kind: 'card';
+    href: string;
+} | {
+    kind: 'tab';
+    sections?: 'all' | 'public' | string[];
+} | {
+    kind: 'nested';
+    into: string;
+    docsPath?: string;
+    group?: string;
+};
 interface HubProject {
     name: string;
     description: string;
-    href?: string;
     repo?: string;
     status?: 'active' | 'beta' | 'planned' | 'deprecated';
     icon?: string;
@@ -103,11 +153,25 @@ interface HubProject {
     group?: string;
     hubUrl?: string;
     hubName?: string;
-    mode?: 'link' | 'embed' | 'inject';
-    git?: RemoteGitSource;
-    embedSections?: 'all' | 'public' | string[];
-    injectInto?: string;
-    docsPath?: string;
+    source: HubProjectSource;
+    placement: HubProjectPlacement;
+}
+/**
+ * The subset of HubProject fields a sub-project can declare about itself in
+ * `clearify.config.ts`. The hub scanner composes this with the sub-project's
+ * `siteUrl` and assigns `source` + `placement` on its own side.
+ */
+interface HubProjectPartial {
+    description: string;
+    repo?: string;
+    status?: 'active' | 'beta' | 'planned' | 'deprecated';
+    icon?: string;
+    tags?: string[];
+    group?: string;
+    /** URL of the parent hub site, used by the Sidebar back-link. */
+    hubUrl?: string;
+    /** Display name for the Sidebar back-link. Default: 'Hub'. */
+    hubName?: string;
 }
 interface HubConfig {
     projects: HubProject[];
@@ -135,4 +199,4 @@ interface ClearifyDataConfig {
 }
 declare function defineConfig(config: Partial<ClearifyConfig>): Partial<ClearifyConfig>;
 
-export { type ClearifyConfig, type ClearifyDataConfig, type DocCategory, type HubConfig, type HubProject, type NavigationItem, type PageFrontmatter, type RemoteGitSource, type ResolvedSection, type RouteEntry, type SectionConfig, type SectionNavigation, defineConfig };
+export { type ClearifyConfig, type ClearifyDataConfig, type DocCategory, type HubConfig, type HubProject, type HubProjectPartial, type HubProjectPlacement, type HubProjectSource, type NavigationItem, type PageFrontmatter, type RemoteGitSource, type ResolvedSection, type RouteEntry, type SectionConfig, type SectionNavigation, defineConfig };

package/dist/node/vite-plugin/index.js

@@ -1,8 +1,8 @@
 import {
   clearifyPlugin
-} from "../chunk-GWYMXKDL.js";
+} from "../chunk-Q5FUAK6J.js";
 import "../chunk-B2Q23JW3.js";
-import "../chunk-2WML2D77.js";
+import "../chunk-ZWF6VCSQ.js";
 import "../chunk-AJBCHKBP.js";
 import "../chunk-V7LLYIRO.js";
 import "../chunk-CTL4YL7C.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@marlinjai/clearify",
-  "version": "1.20.0",
+  "version": "2.1.0",
   "description": "An open-source documentation site generator. Turn markdown into beautiful docs.",
   "type": "module",
   "bin": {
@@ -28,7 +28,8 @@
     "postbuild": "node scripts/generate-schema.mjs",
     "dev:self": "node bin/clearify.js dev",
     "prepare": "husky",
-    "release": "semantic-release"
+    "release": "semantic-release",
+    "test": "vitest run"
   },
   "dependencies": {
     "@inquirer/password": "^5.0.11",
@@ -82,7 +83,8 @@
     "puppeteer": "^24.37.2",
     "semantic-release": "^25.0.3",
     "tsup": "^8.3.6",
-    "typescript": "^5.7.3"
+    "typescript": "^5.7.3",
+    "vitest": "^4.1.4"
   },
   "packageManager": "pnpm@9.15.0",
   "license": "MIT",

package/src/theme/Sidebar.tsx

@@ -1,13 +1,13 @@
 import React, { useState, useEffect, useRef } from 'react';
 import { Link, useLocation, useNavigate } from 'react-router-dom';
 import clsx from 'clsx';
-import type { NavigationItem, SectionNavigation, HubProject } from '../types/index.js';
+import type { NavigationItem, SectionNavigation, HubProjectPartial } from '../types/index.js';
 
 interface SidebarProps {
   sections: SectionNavigation[];
   open: boolean;
   onClose: () => void;
-  hubProject?: Omit<HubProject, 'name'>;
+  hubProject?: HubProjectPartial;
 }
 
 function findActiveSection(pathname: string, sections: SectionNavigation[]): string {