@marlinjai/clearify 1.11.1 → 1.12.0

package/README.md

@@ -1,12 +1,3 @@
----
-title: Clearify
-summary: README for Clearify, an open-source documentation site generator that turns markdown into beautiful docs with zero config, MDX support, Mermaid diagrams, full-text search, OpenAPI rendering, and SSG with SEO.
-category: documentation
-tags: [clearify, documentation, mdx, vite, ssg]
-status: active
-date: 2026-02-07
----
-
 # Clearify
 
 An open-source documentation site generator. Turn markdown into beautiful docs.

package/dist/config-schema.json

@@ -0,0 +1,225 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "properties": {
+    "name": {
+      "type": "string"
+    },
+    "siteUrl": {
+      "type": "string"
+    },
+    "theme": {
+      "type": "object",
+      "properties": {
+        "primaryColor": {
+          "type": "string"
+        },
+        "mode": {
+          "type": "string",
+          "enum": [
+            "light",
+            "dark",
+            "auto"
+          ]
+        }
+      },
+      "additionalProperties": false
+    },
+    "logo": {
+      "type": "object",
+      "properties": {
+        "light": {
+          "type": "string"
+        },
+        "dark": {
+          "type": "string"
+        }
+      },
+      "additionalProperties": false
+    },
+    "links": {
+      "type": "object",
+      "propertyNames": {
+        "type": "string"
+      },
+      "additionalProperties": {
+        "type": "string"
+      }
+    },
+    "sections": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "properties": {
+          "label": {
+            "type": "string"
+          },
+          "docsDir": {
+            "type": "string"
+          },
+          "basePath": {
+            "type": "string"
+          },
+          "draft": {
+            "type": "boolean"
+          },
+          "sitemap": {
+            "type": "boolean"
+          },
+          "exclude": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            }
+          },
+          "git": {
+            "type": "object",
+            "properties": {
+              "repo": {
+                "type": "string"
+              },
+              "ref": {
+                "type": "string"
+              },
+              "path": {
+                "type": "string"
+              },
+              "sparse": {
+                "type": "boolean"
+              }
+            },
+            "required": [
+              "repo"
+            ],
+            "additionalProperties": false
+          }
+        },
+        "required": [
+          "label",
+          "docsDir"
+        ],
+        "additionalProperties": false
+      }
+    },
+    "hub": {
+      "type": "object",
+      "properties": {
+        "projects": {
+          "default": [],
+          "type": "array",
+          "items": {
+            "type": "object",
+            "properties": {
+              "name": {
+                "type": "string"
+              },
+              "description": {
+                "type": "string"
+              },
+              "href": {
+                "type": "string"
+              },
+              "repo": {
+                "type": "string"
+              },
+              "status": {
+                "default": "active",
+                "type": "string",
+                "enum": [
+                  "active",
+                  "beta",
+                  "planned",
+                  "deprecated"
+                ]
+              },
+              "icon": {
+                "type": "string"
+              },
+              "tags": {
+                "type": "array",
+                "items": {
+                  "type": "string"
+                }
+              },
+              "group": {
+                "type": "string"
+              },
+              "mode": {
+                "type": "string",
+                "enum": [
+                  "link",
+                  "embed",
+                  "inject"
+                ]
+              },
+              "git": {
+                "type": "object",
+                "properties": {
+                  "repo": {
+                    "type": "string"
+                  },
+                  "ref": {
+                    "type": "string"
+                  },
+                  "path": {
+                    "type": "string"
+                  },
+                  "sparse": {
+                    "type": "boolean"
+                  }
+                },
+                "required": [
+                  "repo"
+                ],
+                "additionalProperties": false
+              },
+              "embedSections": {
+                "anyOf": [
+                  {
+                    "type": "string",
+                    "const": "all"
+                  },
+                  {
+                    "type": "string",
+                    "const": "public"
+                  },
+                  {
+                    "type": "array",
+                    "items": {
+                      "type": "string"
+                    }
+                  }
+                ]
+              },
+              "injectInto": {
+                "type": "string"
+              },
+              "docsPath": {
+                "type": "string"
+              }
+            },
+            "required": [
+              "name",
+              "description",
+              "status"
+            ],
+            "additionalProperties": false
+          }
+        },
+        "scan": {
+          "type": "string"
+        },
+        "cacheDir": {
+          "type": "string"
+        }
+      },
+      "required": [
+        "projects"
+      ],
+      "additionalProperties": false
+    }
+  },
+  "additionalProperties": false,
+  "$id": "https://docs.lumitra.co/schemas/clearify-data.json",
+  "title": "Clearify Data Config"
+}

package/dist/node/{chunk-PVTUVUBK.js → chunk-2WLFSQS7.js}

@@ -6,7 +6,7 @@ import {
 import { z } from "zod";
 import { resolve, basename, dirname } from "path";
 import { pathToFileURL } from "url";
-import { existsSync, readFileSync, rmSync } from "fs";
+import { existsSync, readFileSync, writeFileSync, renameSync, mkdirSync, rmSync, symlinkSync, readdirSync, statSync } from "fs";
 import { tmpdir } from "os";
 import { randomBytes } from "crypto";
 var NavigationItemSchema = z.lazy(
@@ -51,13 +51,15 @@ var HubProjectSchema = z.object({
   icon: z.string().optional(),
   tags: z.array(z.string()).optional(),
   group: z.string().optional(),
-  mode: z.enum(["link", "embed"]).optional(),
+  mode: z.enum(["link", "embed", "inject"]).optional(),
   git: RemoteGitSourceSchema.optional(),
   embedSections: z.union([
     z.literal("all"),
     z.literal("public"),
     z.array(z.string())
-  ]).optional()
+  ]).optional(),
+  injectInto: z.string().optional(),
+  docsPath: z.string().optional()
 });
 var HubProjectPartialSchema = z.object({
   description: z.string(),
@@ -100,6 +102,52 @@ var ClearifyConfigSchema = z.object({
   customCss: z.string().optional(),
   headTags: z.array(z.string()).optional()
 });
+var ClearifyDataSchema = z.object({
+  name: z.string().optional(),
+  siteUrl: z.string().optional(),
+  theme: z.object({
+    primaryColor: z.string().optional(),
+    mode: z.enum(["light", "dark", "auto"]).optional()
+  }).optional(),
+  logo: z.object({
+    light: z.string().optional(),
+    dark: z.string().optional()
+  }).optional(),
+  links: z.record(z.string(), z.string()).optional(),
+  sections: z.array(SectionConfigSchema).optional(),
+  hub: HubConfigSchema
+});
+function deepMergeJsonWins(base, json) {
+  const result = { ...base };
+  for (const key of Object.keys(json)) {
+    const jsonVal = json[key];
+    if (jsonVal === void 0) continue;
+    const baseVal = base[key];
+    if (baseVal !== null && jsonVal !== null && typeof baseVal === "object" && typeof jsonVal === "object" && !Array.isArray(baseVal) && !Array.isArray(jsonVal)) {
+      result[key] = deepMergeJsonWins(baseVal, jsonVal);
+    } else {
+      result[key] = jsonVal;
+    }
+  }
+  return result;
+}
+function loadDataConfig(root) {
+  const dataPath = resolve(root, "clearify.data.json");
+  if (!existsSync(dataPath)) return {};
+  try {
+    const raw = JSON.parse(readFileSync(dataPath, "utf-8"));
+    return ClearifyDataSchema.parse(raw);
+  } catch {
+    return {};
+  }
+}
+function writeDataConfig(root, data) {
+  const validated = ClearifyDataSchema.parse(data);
+  const dataPath = resolve(root, "clearify.data.json");
+  const tmpPath = dataPath + ".tmp";
+  writeFileSync(tmpPath, JSON.stringify(validated, null, 2) + "\n", "utf-8");
+  renameSync(tmpPath, dataPath);
+}
 var defaultConfig = {
   name: "Documentation",
   docsDir: "./docs",
@@ -176,20 +224,24 @@ async function loadUserConfig(root) {
     "clearify.config.js",
     "clearify.config.mjs"
   ];
+  let tsConfig = {};
   for (const file of configFiles) {
     const configPath = resolve(root, file);
     if (existsSync(configPath)) {
       try {
         if (file.endsWith(".ts")) {
-          return await loadTsConfig(configPath);
+          tsConfig = await loadTsConfig(configPath);
+        } else {
+          const mod = await import(pathToFileURL(configPath).href);
+          tsConfig = mod.default ?? mod;
         }
-        const mod = await import(pathToFileURL(configPath).href);
-        return mod.default ?? mod;
+        break;
       } catch {
       }
     }
   }
-  return {};
+  const jsonData = loadDataConfig(root);
+  return deepMergeJsonWins(tsConfig, jsonData);
 }
 function resolveConfig(userConfig = {}, root) {
   const parsed = ClearifyConfigSchema.parse(userConfig);
@@ -247,8 +299,43 @@ async function resolveSections(config, root) {
     }
   ];
 }
+function buildStagingOverlay(stagingDir, originalDir, injections) {
+  if (existsSync(stagingDir)) {
+    rmSync(stagingDir, { recursive: true, force: true });
+  }
+  mkdirSync(stagingDir, { recursive: true });
+  const ancestorDirs = /* @__PURE__ */ new Set();
+  for (const targetRelPath of injections.keys()) {
+    const parts = targetRelPath.split("/");
+    for (let i = 1; i <= parts.length; i++) {
+      ancestorDirs.add(parts.slice(0, i).join("/"));
+    }
+  }
+  function mirrorDir(srcDir, destDir, relPrefix) {
+    if (!existsSync(srcDir)) return;
+    const entries = readdirSync(srcDir);
+    for (const entry of entries) {
+      const srcPath = resolve(srcDir, entry);
+      const destPath = resolve(destDir, entry);
+      const relPath = relPrefix ? `${relPrefix}/${entry}` : entry;
+      if (ancestorDirs.has(relPath) && statSync(srcPath).isDirectory()) {
+        mkdirSync(destPath, { recursive: true });
+        mirrorDir(srcPath, destPath, relPath);
+      } else {
+        symlinkSync(srcPath, destPath);
+      }
+    }
+  }
+  mirrorDir(originalDir, stagingDir, "");
+  for (const [relPath, sourcePath] of injections) {
+    const destPath = resolve(stagingDir, relPath);
+    const parentDir = dirname(destPath);
+    mkdirSync(parentDir, { recursive: true });
+    symlinkSync(sourcePath, destPath);
+  }
+}
 async function scanHubProjects(config, root) {
-  if (!config.hub?.scan && !config.hub?.projects?.some((p) => p.mode === "embed")) {
+  if (!config.hub?.scan && !config.hub?.projects?.some((p) => p.mode === "embed" || p.mode === "inject")) {
     return config;
   }
   const scannedProjects = [];
@@ -320,10 +407,69 @@ async function scanHubProjects(config, root) {
       );
     }
   }
-  const finalSections = [...config.sections ?? [], ...embedSections];
+  const injectionsBySection = /* @__PURE__ */ new Map();
+  for (const project of merged) {
+    if (project.mode !== "inject" || !project.git) continue;
+    const cacheDir = config.hub?.cacheDir ? resolve(root, config.hub.cacheDir) : resolve(root, "node_modules/.cache/clearify-remote");
+    try {
+      const { resolveRemoteSource } = await import("./core/remote.js");
+      const { localPath, cached } = await resolveRemoteSource(project.git, cacheDir);
+      const docsPath = project.docsPath ?? "docs";
+      const absoluteDocsPath = resolve(localPath, docsPath);
+      if (!existsSync(absoluteDocsPath)) {
+        console.warn(
+          `  \u26A0 Hub inject "${project.name}": docs path "${docsPath}" not found in cloned repo.`
+        );
+        continue;
+      }
+      const targetLabel = project.injectInto;
+      if (!targetLabel) {
+        console.warn(`  \u26A0 Hub inject "${project.name}": missing injectInto field.`);
+        continue;
+      }
+      if (!injectionsBySection.has(targetLabel)) {
+        injectionsBySection.set(targetLabel, /* @__PURE__ */ new Map());
+      }
+      const slugifiedName = slugify(project.name);
+      const relPath = project.group ? `projects/${project.group}/${slugifiedName}` : `projects/${slugifiedName}`;
+      injectionsBySection.get(targetLabel).set(relPath, absoluteDocsPath);
+      console.log(
+        `  Hub inject "${project.name}": ${cached ? "cached" : "cloned"} \u2192 ${relPath}`
+      );
+    } catch (err) {
+      console.warn(
+        `  \u26A0 Hub inject "${project.name}" failed:`,
+        err instanceof Error ? err.message : err
+      );
+    }
+  }
+  let modifiedSections = config.sections ? [...config.sections] : void 0;
+  if (injectionsBySection.size > 0 && modifiedSections) {
+    for (const [sectionLabel, injections] of injectionsBySection) {
+      const sectionIdx = modifiedSections.findIndex((s) => s.label === sectionLabel);
+      if (sectionIdx === -1) {
+        console.warn(`  \u26A0 Hub inject: target section "${sectionLabel}" not found.`);
+        continue;
+      }
+      const section = modifiedSections[sectionIdx];
+      const sectionId = slugify(section.label);
+      const originalDocsDir = section.docsDir.startsWith("/") ? section.docsDir : resolve(root, section.docsDir);
+      const stagingDir = resolve(root, `node_modules/.cache/clearify-inject/${sectionId}`);
+      buildStagingOverlay(stagingDir, originalDocsDir, injections);
+      modifiedSections[sectionIdx] = {
+        ...section,
+        docsDir: stagingDir
+      };
+      console.log(
+        `  Hub inject: staging overlay for "${sectionLabel}" \u2192 ${stagingDir}`
+      );
+    }
+  }
+  const finalSections = [...modifiedSections ?? config.sections ?? [], ...embedSections];
+  const sectionsChanged = embedSections.length > 0 || injectionsBySection.size > 0;
   return {
     ...config,
-    ...embedSections.length > 0 ? { sections: finalSections } : {},
+    ...sectionsChanged ? { sections: finalSections } : {},
     hub: {
       ...config.hub,
       projects: merged
@@ -332,6 +478,10 @@ async function scanHubProjects(config, root) {
 }
 
 export {
+  ClearifyDataSchema,
+  deepMergeJsonWins,
+  loadDataConfig,
+  writeDataConfig,
   defaultConfig,
   loadUserConfig,
   resolveConfig,

package/dist/node/{chunk-NGWAMBXS.js → chunk-6XHVO5AO.js}

@@ -2,7 +2,7 @@ import {
   loadUserConfig,
   resolveConfig,
   resolveSections
-} from "./chunk-PVTUVUBK.js";
+} from "./chunk-2WLFSQS7.js";
 import {
   scanDocs
 } from "./chunk-QTGT76RY.js";

package/dist/node/{chunk-JU53JE4P.js → chunk-6YAEHWC7.js}

@@ -8,12 +8,12 @@ import {
 } from "./chunk-SCZZB7OE.js";
 import {
   clearifyPlugin
-} from "./chunk-PFX7LHRZ.js";
+} from "./chunk-XYS5SV4M.js";
 import {
   loadUserConfig,
   resolveConfig,
   resolveSections
-} from "./chunk-PVTUVUBK.js";
+} from "./chunk-2WLFSQS7.js";
 import {
   buildSectionData
 } from "./chunk-QTGT76RY.js";
@@ -246,6 +246,12 @@ async function buildSite() {
       alias: { "@clearify": resolve(root, "..") },
       dedupe
     },
+    ssr: {
+      // Bundle all deps into the SSR output so pre-rendering works in any
+      // host project, even if it doesn't have react/react-router installed.
+      // The SSR bundle is temporary and deleted after pre-rendering.
+      noExternal: true
+    },
     build: {
       outDir: ssrOutDir,
       ssr: resolveClientPath("entry-server.tsx"),

package/dist/node/{chunk-PFX7LHRZ.js → chunk-XYS5SV4M.js}

@@ -2,18 +2,23 @@ import {
   parseOpenAPISpec
 } from "./chunk-B2Q23JW3.js";
 import {
+  ClearifyDataSchema,
+  deepMergeJsonWins,
+  loadDataConfig,
   loadUserConfig,
   resolveConfig,
   resolveSections,
-  scanHubProjects
-} from "./chunk-PVTUVUBK.js";
+  scanHubProjects,
+  writeDataConfig
+} from "./chunk-2WLFSQS7.js";
 import {
   buildSectionData
 } from "./chunk-QTGT76RY.js";
 
 // src/vite-plugin/index.ts
-import { resolve } from "path";
-import { existsSync, readFileSync } from "fs";
+import { resolve, dirname } from "path";
+import { fileURLToPath } from "url";
+import { existsSync, readFileSync, readdirSync, statSync } from "fs";
 import { dereference } from "@scalar/openapi-parser";
 var VIRTUAL_CONFIG = "virtual:clearify/config";
 var RESOLVED_VIRTUAL_CONFIG = "\0" + VIRTUAL_CONFIG;
@@ -29,6 +34,8 @@ var VIRTUAL_OPENAPI_SPEC = "virtual:clearify/openapi-spec";
 var RESOLVED_VIRTUAL_OPENAPI_SPEC = "\0" + VIRTUAL_OPENAPI_SPEC;
 var VIRTUAL_HUB = "virtual:clearify/hub";
 var RESOLVED_VIRTUAL_HUB = "\0" + VIRTUAL_HUB;
+var VIRTUAL_ADMIN_ENABLED = "virtual:clearify/admin-enabled";
+var RESOLVED_VIRTUAL_ADMIN_ENABLED = "\0" + VIRTUAL_ADMIN_ENABLED;
 function findFirstNavPath(items) {
   for (const item of items) {
     if (item.path) return item.path;
@@ -241,6 +248,7 @@ ${routeEntries.join(",\n")}
       if (id === VIRTUAL_MERMAID_SVGS) return RESOLVED_VIRTUAL_MERMAID_SVGS;
       if (id === VIRTUAL_OPENAPI_SPEC) return RESOLVED_VIRTUAL_OPENAPI_SPEC;
       if (id === VIRTUAL_HUB) return RESOLVED_VIRTUAL_HUB;
+      if (id === VIRTUAL_ADMIN_ENABLED) return RESOLVED_VIRTUAL_ADMIN_ENABLED;
       return null;
     },
     async load(id) {
@@ -266,6 +274,10 @@ ${routeEntries.join(",\n")}
         const hubData = config.hub ?? null;
         return `export default ${JSON.stringify(hubData)};`;
       }
+      if (id === RESOLVED_VIRTUAL_ADMIN_ENABLED) {
+        const enabled = resolvedViteConfig.command === "serve";
+        return `export default ${enabled};`;
+      }
       return null;
     },
     configureServer(server) {
@@ -410,6 +422,118 @@ ${routeEntries.join(",\n")}
           });
         }
       });
+      const dataJsonPath = resolve(userRoot, "clearify.data.json");
+      server.watcher.add(dataJsonPath);
+      server.watcher.on("change", (changedPath) => {
+        if (changedPath === dataJsonPath) {
+          for (const resolvedId of [
+            RESOLVED_VIRTUAL_CONFIG,
+            RESOLVED_VIRTUAL_ROUTES,
+            RESOLVED_VIRTUAL_NAVIGATION,
+            RESOLVED_VIRTUAL_SEARCH_INDEX
+          ]) {
+            const mod = server.moduleGraph.getModuleById(resolvedId);
+            if (mod) server.moduleGraph.invalidateModule(mod);
+          }
+          server.ws.send({ type: "full-reload" });
+        }
+      });
+      function readJsonBody(req) {
+        return new Promise((resolve2, reject) => {
+          const chunks = [];
+          req.on("data", (chunk) => chunks.push(chunk));
+          req.on("end", () => {
+            try {
+              resolve2(JSON.parse(Buffer.concat(chunks).toString()));
+            } catch {
+              reject(new Error("Invalid JSON"));
+            }
+          });
+          req.on("error", reject);
+        });
+      }
+      server.middlewares.use(async (req, res, next) => {
+        const url = req.url?.split("?") ?? [""];
+        const pathname = url[0];
+        const query = new URLSearchParams(url[1] ?? "");
+        if (!pathname.startsWith("/__clearify/api/")) return next();
+        res.setHeader("Content-Type", "application/json");
+        try {
+          if (req.method === "GET" && pathname === "/__clearify/api/config") {
+            res.end(JSON.stringify(config));
+            return;
+          }
+          if (req.method === "GET" && pathname === "/__clearify/api/config/data") {
+            const data = loadDataConfig(userRoot);
+            res.end(JSON.stringify(data));
+            return;
+          }
+          if (req.method === "PUT" && pathname === "/__clearify/api/config/data") {
+            const body = await readJsonBody(req);
+            const result = ClearifyDataSchema.safeParse(body);
+            if (!result.success) {
+              res.statusCode = 400;
+              res.end(JSON.stringify({ error: "Validation failed", issues: result.error.issues }));
+              return;
+            }
+            writeDataConfig(userRoot, body);
+            res.end(JSON.stringify({ ok: true }));
+            return;
+          }
+          if (req.method === "PATCH" && pathname === "/__clearify/api/config/data") {
+            const body = await readJsonBody(req);
+            const existing = loadDataConfig(userRoot);
+            const merged = deepMergeJsonWins(existing, body);
+            const result = ClearifyDataSchema.safeParse(merged);
+            if (!result.success) {
+              res.statusCode = 400;
+              res.end(JSON.stringify({ error: "Validation failed", issues: result.error.issues }));
+              return;
+            }
+            writeDataConfig(userRoot, merged);
+            res.end(JSON.stringify({ ok: true }));
+            return;
+          }
+          if (req.method === "GET" && pathname === "/__clearify/api/config/schema") {
+            const pkgDir = dirname(fileURLToPath(import.meta.url));
+            const schemaPath = resolve(pkgDir, "../../dist/config-schema.json");
+            if (existsSync(schemaPath)) {
+              res.end(readFileSync(schemaPath, "utf-8"));
+            } else {
+              res.statusCode = 404;
+              res.end(JSON.stringify({ error: "Schema file not found" }));
+            }
+            return;
+          }
+          if (req.method === "GET" && pathname === "/__clearify/api/fs/dirs") {
+            const rootParam = query.get("root") ?? ".";
+            const target = resolve(userRoot, rootParam);
+            if (!target.startsWith(userRoot)) {
+              res.statusCode = 403;
+              res.end(JSON.stringify({ error: "Path outside project root" }));
+              return;
+            }
+            if (!existsSync(target)) {
+              res.end(JSON.stringify({ dirs: [] }));
+              return;
+            }
+            const dirs = readdirSync(target).filter((entry) => {
+              try {
+                return statSync(resolve(target, entry)).isDirectory();
+              } catch {
+                return false;
+              }
+            });
+            res.end(JSON.stringify({ dirs }));
+            return;
+          }
+          res.statusCode = 404;
+          res.end(JSON.stringify({ error: "Not found" }));
+        } catch (err) {
+          res.statusCode = err.message === "Invalid JSON" ? 400 : 500;
+          res.end(JSON.stringify({ error: err.message ?? "Internal server error" }));
+        }
+      });
       return () => {
         server.middlewares.use((req, _res, next) => {
           if (req.method !== "GET" || !req.headers.accept?.includes("text/html")) {