@marlinjai/clearify 1.9.0 → 1.11.0

package/README.md

@@ -1,3 +1,12 @@
+---
+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/node/{chunk-QIAMD2Q6.js → chunk-3CW4MOO4.js}

@@ -171,6 +171,29 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   } else {
     console.log("  CHANGELOG.md already exists, skipping");
   }
+  const roadmapPath = resolve(cwd, "ROADMAP.md");
+  if (!existsSync(roadmapPath)) {
+    writeFileSync(
+      roadmapPath,
+      `# Roadmap
+
+## Planned
+
+<!-- Decided features, ready to be worked on -->
+
+## In Progress
+
+<!-- Currently being implemented -->
+
+## Completed
+
+<!-- Done \u2014 move to CHANGELOG.md on release -->
+`
+    );
+    console.log("  Created ROADMAP.md");
+  } else {
+    console.log("  ROADMAP.md already exists, skipping");
+  }
   if (!existsSync(configPath)) {
     if (options.noInternal) {
       writeFileSync(

package/dist/node/chunk-AJBCHKBP.js

@@ -0,0 +1,105 @@
+// src/core/remote.ts
+import { execSync } from "child_process";
+import { existsSync, mkdirSync } from "fs";
+import { resolve } from "path";
+function repoSlug(repo, ref) {
+  return repo.replace(/^(https?:\/\/|git@)/, "").replace(/\.git$/, "").replace(/[/:@]/g, "-").replace(/-+/g, "-").replace(/^-|-$/g, "") + "--" + ref;
+}
+function isPinnedRef(ref) {
+  return /^[0-9a-f]{40}$/i.test(ref) || /^v?\d+\.\d+/.test(ref);
+}
+async function resolveRemoteSource(source, cacheDir) {
+  const ref = source.ref ?? "main";
+  const slug = repoSlug(source.repo, ref);
+  const localPath = resolve(cacheDir, slug);
+  const sparse = source.sparse !== false;
+  mkdirSync(cacheDir, { recursive: true });
+  if (existsSync(resolve(localPath, ".git"))) {
+    if (!isPinnedRef(ref)) {
+      try {
+        execSync(`git -C ${JSON.stringify(localPath)} fetch origin ${ref} --depth 1`, {
+          stdio: "pipe",
+          timeout: 3e4
+        });
+        execSync(`git -C ${JSON.stringify(localPath)} checkout FETCH_HEAD`, {
+          stdio: "pipe"
+        });
+      } catch (err) {
+        console.warn(
+          `  \u26A0 Failed to update remote "${source.repo}" (ref: ${ref}), using stale cache.`,
+          err instanceof Error ? err.message : ""
+        );
+      }
+    }
+    const commit2 = getHeadCommit(localPath);
+    return { localPath, resolvedCommit: commit2, cached: true };
+  }
+  try {
+    if (sparse && source.path) {
+      execSync(
+        `git clone --no-checkout --depth 1 --branch ${ref} ${source.repo} ${JSON.stringify(localPath)}`,
+        { stdio: "pipe", timeout: 6e4 }
+      );
+      execSync(`git -C ${JSON.stringify(localPath)} sparse-checkout init --cone`, {
+        stdio: "pipe"
+      });
+      execSync(`git -C ${JSON.stringify(localPath)} sparse-checkout set ${source.path}`, {
+        stdio: "pipe"
+      });
+      execSync(`git -C ${JSON.stringify(localPath)} checkout`, { stdio: "pipe" });
+    } else {
+      execSync(
+        `git clone --depth 1 --branch ${ref} ${source.repo} ${JSON.stringify(localPath)}`,
+        { stdio: "pipe", timeout: 6e4 }
+      );
+    }
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    throw new Error(
+      `Failed to clone remote repo "${source.repo}" (ref: ${ref}): ${msg}`
+    );
+  }
+  const commit = getHeadCommit(localPath);
+  return { localPath, resolvedCommit: commit, cached: false };
+}
+function getHeadCommit(repoPath) {
+  try {
+    return execSync(`git -C ${JSON.stringify(repoPath)} rev-parse HEAD`, {
+      encoding: "utf-8",
+      stdio: "pipe"
+    }).trim();
+  } catch {
+    return "unknown";
+  }
+}
+async function resolveRemoteSections(sections, cacheDir) {
+  const results = [];
+  for (const section of sections) {
+    if (!section.git) {
+      results.push(section);
+      continue;
+    }
+    const { localPath, cached } = await resolveRemoteSource(section.git, cacheDir);
+    const absoluteDocsDir = resolve(localPath, section.docsDir);
+    if (!existsSync(absoluteDocsDir)) {
+      throw new Error(
+        `Remote section "${section.label}": docs directory "${section.docsDir}" not found in cloned repo "${section.git.repo}".`
+      );
+    }
+    console.log(
+      `  Remote section "${section.label}": ${cached ? "cached" : "cloned"} \u2192 ${absoluteDocsDir}`
+    );
+    results.push({
+      ...section,
+      docsDir: absoluteDocsDir,
+      git: void 0
+      // Already resolved — docsDir is now absolute
+    });
+  }
+  return results;
+}
+
+export {
+  resolveRemoteSource,
+  resolveRemoteSections
+};

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

@@ -8,15 +8,15 @@ import {
 } from "./chunk-SCZZB7OE.js";
 import {
   clearifyPlugin
-} from "./chunk-IF6GI4WU.js";
+} from "./chunk-PFX7LHRZ.js";
 import {
   loadUserConfig,
   resolveConfig,
   resolveSections
-} from "./chunk-PQMKRFBQ.js";
+} from "./chunk-PVTUVUBK.js";
 import {
   buildSectionData
-} from "./chunk-QNC5QRIO.js";
+} from "./chunk-QTGT76RY.js";
 
 // src/node/build.ts
 import { build as viteBuild } from "vite";
@@ -27,10 +27,11 @@ import remarkFrontmatter from "remark-frontmatter";
 import remarkMdxFrontmatter from "remark-mdx-frontmatter";
 import rehypeShiki from "@shikijs/rehype";
 import tailwindcss from "@tailwindcss/vite";
-import { resolve } from "path";
+import { resolve, dirname } from "path";
 import { writeFileSync, readFileSync, existsSync, mkdirSync, rmSync, copyFileSync } from "fs";
 import { basename } from "path";
 import { fileURLToPath } from "url";
+import { createRequire } from "module";
 function findPackageRoot() {
   let dir = fileURLToPath(new URL(".", import.meta.url));
   for (let i = 0; i < 10; i++) {
@@ -45,6 +46,18 @@ function resolveClientPath(...segments) {
   const packageRoot = findPackageRoot();
   return resolve(packageRoot, "src", "client", ...segments);
 }
+function dedupeResolve() {
+  const require2 = createRequire(import.meta.url);
+  const dedupePkgs = ["@mdx-js/react", "react", "react-dom", "react-router-dom"];
+  const alias = {};
+  for (const pkg of dedupePkgs) {
+    try {
+      alias[pkg] = dirname(require2.resolve(`${pkg}/package.json`));
+    } catch {
+    }
+  }
+  return { alias, dedupe: dedupePkgs };
+}
 function escapeHtml(str) {
   return str.replace(/&/g, "&amp;").replace(/"/g, "&quot;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
 }
@@ -140,11 +153,14 @@ async function buildSite() {
   const config = resolveConfig(userConfig);
   const outDir = resolve(userRoot, config.outDir);
   const ssrOutDir = resolve(outDir, ".ssr");
-  const allSections = resolveSections(config, userRoot);
+  const allSections = await resolveSections(config, userRoot);
   const productionSections = allSections.filter((s) => !s.draft);
-  const changelogPath = resolve(userRoot, "CHANGELOG.md");
+  const rootFiles = {
+    changelogPath: resolve(userRoot, "CHANGELOG.md"),
+    roadmapPath: resolve(userRoot, "ROADMAP.md")
+  };
   const sectionDataList = productionSections.map(
-    (section) => buildSectionData(section, changelogPath, config.navigation)
+    (section) => buildSectionData(section, rootFiles, config.navigation)
   );
   const allRoutes = sectionDataList.flatMap((sd) => sd.routes);
   if (config.openapi?.spec && config.openapi.generatePages !== false) {
@@ -207,11 +223,13 @@ async function buildSite() {
     mermaidSvgs,
     mermaidStrategy
   };
+  const { alias: dedupeAlias, dedupe } = dedupeResolve();
   const clientConfig = {
     root,
     plugins: getSharedPlugins(userRoot, sharedPluginOptions),
     resolve: {
-      alias: { "@clearify": resolve(root, "..") }
+      alias: { "@clearify": resolve(root, ".."), ...dedupeAlias },
+      dedupe
     },
     build: {
       outDir,
@@ -225,7 +243,8 @@ async function buildSite() {
     root,
     plugins: getSharedPlugins(userRoot, sharedPluginOptions),
     resolve: {
-      alias: { "@clearify": resolve(root, "..") }
+      alias: { "@clearify": resolve(root, "..") },
+      dedupe
     },
     build: {
       outDir: ssrOutDir,

package/dist/node/chunk-NGWAMBXS.js

@@ -0,0 +1,264 @@
+import {
+  loadUserConfig,
+  resolveConfig,
+  resolveSections
+} from "./chunk-PVTUVUBK.js";
+import {
+  scanDocs
+} from "./chunk-QTGT76RY.js";
+
+// src/node/check.ts
+import { resolve, relative } from "path";
+import { readFileSync, existsSync } from "fs";
+import matter from "gray-matter";
+var VALID_CATEGORIES = [
+  "documentation",
+  "internal",
+  "plan",
+  "research",
+  "decision",
+  "roadmap",
+  "changelog"
+];
+var VALID_STATUSES = ["active", "superseded", "archived"];
+function isStrictPath(filePath) {
+  const normalized = filePath.replace(/\\/g, "/");
+  return /\/docs\/plans(\/|$)/.test(normalized) || /\/docs\/internal(\/|$)/.test(normalized);
+}
+function validateFrontmatter(doc, userRoot) {
+  const issues = [];
+  const rel = relative(userRoot, doc.filePath);
+  const strict = isStrictPath(doc.filePath);
+  let rawFm = {};
+  try {
+    const content = readFileSync(doc.filePath, "utf-8");
+    rawFm = matter(content).data;
+  } catch {
+    rawFm = {};
+  }
+  if (strict) {
+    if (!rawFm.title) {
+      issues.push({ file: rel, field: "title", message: "missing required field", severity: "error" });
+    }
+    if (!rawFm.summary) {
+      issues.push({ file: rel, field: "summary", message: "missing required field", severity: "error" });
+    }
+    if (!rawFm.category) {
+      issues.push({ file: rel, field: "category", message: "missing required field", severity: "error" });
+    }
+  } else {
+    if (!rawFm.title) {
+      issues.push({ file: rel, field: "title", message: "missing required field", severity: "error" });
+    }
+    if (!rawFm.summary) {
+      issues.push({ file: rel, field: "summary", message: "recommended field missing", severity: "warning" });
+    }
+    if (!rawFm.category) {
+      issues.push({ file: rel, field: "category", message: "recommended field missing", severity: "warning" });
+    }
+  }
+  if (rawFm.category !== void 0) {
+    if (!VALID_CATEGORIES.includes(rawFm.category)) {
+      issues.push({
+        file: rel,
+        field: "category",
+        message: `invalid value "${rawFm.category}" (allowed: ${VALID_CATEGORIES.join(", ")})`,
+        severity: "error"
+      });
+    }
+  }
+  if (rawFm.status !== void 0) {
+    if (!VALID_STATUSES.includes(rawFm.status)) {
+      issues.push({
+        file: rel,
+        field: "status",
+        message: `invalid value "${rawFm.status}" (allowed: ${VALID_STATUSES.join(", ")})`,
+        severity: "error"
+      });
+    }
+  }
+  if (rawFm.tags !== void 0 && !Array.isArray(rawFm.tags)) {
+    issues.push({ file: rel, field: "tags", message: "must be an array", severity: "error" });
+  }
+  if (rawFm.projects !== void 0 && !Array.isArray(rawFm.projects)) {
+    issues.push({ file: rel, field: "projects", message: "must be an array", severity: "error" });
+  }
+  return issues;
+}
+async function checkFrontmatter() {
+  const userRoot = process.cwd();
+  const userConfig = await loadUserConfig(userRoot);
+  const config = resolveConfig(userConfig, userRoot);
+  const sections = await resolveSections(config, userRoot);
+  const allDocs = [];
+  for (const section of sections) {
+    const docs = scanDocs(section.docsDir, section.exclude, section.basePath);
+    allDocs.push(...docs);
+  }
+  const allIssues = [];
+  for (const doc of allDocs) {
+    const issues = validateFrontmatter(doc, userRoot);
+    allIssues.push(...issues);
+  }
+  const errors = allIssues.filter((i) => i.severity === "error");
+  const warnings = allIssues.filter((i) => i.severity === "warning");
+  if (allIssues.length === 0) {
+    console.log("\n  Frontmatter: all files valid.\n");
+    return { errors: 0, warnings: 0 };
+  }
+  console.log(`
+  Frontmatter validation: ${errors.length} error(s), ${warnings.length} warning(s)
+`);
+  const fileCol = Math.max(4, ...allIssues.map((i) => i.file.length));
+  const fieldCol = Math.max(5, ...allIssues.map((i) => i.field.length));
+  const msgCol = Math.max(7, ...allIssues.map((i) => i.message.length));
+  const sevCol = 7;
+  const header = `  ${"File".padEnd(fileCol)}  ${"Field".padEnd(fieldCol)}  ${"Severity".padEnd(sevCol)}  ${"Message".padEnd(msgCol)}`;
+  const separator = `  ${"\u2500".repeat(fileCol)}  ${"\u2500".repeat(fieldCol)}  ${"\u2500".repeat(sevCol)}  ${"\u2500".repeat(msgCol)}`;
+  console.log(header);
+  console.log(separator);
+  for (const issue of allIssues) {
+    const sev = issue.severity === "error" ? "ERROR  " : "warning";
+    console.log(`  ${issue.file.padEnd(fileCol)}  ${issue.field.padEnd(fieldCol)}  ${sev}  ${issue.message}`);
+  }
+  console.log();
+  return { errors: errors.length, warnings: warnings.length };
+}
+async function checkLinks(options = {}) {
+  const fmResult = await checkFrontmatter();
+  if (options.frontmatterOnly) {
+    if (fmResult.errors > 0) {
+      process.exitCode = 1;
+    }
+    return;
+  }
+  const userRoot = process.cwd();
+  const userConfig = await loadUserConfig(userRoot);
+  const config = resolveConfig(userConfig, userRoot);
+  const sections = await resolveSections(config, userRoot);
+  const validRoutes = /* @__PURE__ */ new Set();
+  const allDocs = [];
+  for (const section of sections) {
+    const docs = scanDocs(section.docsDir, section.exclude, section.basePath);
+    for (const doc of docs) {
+      validRoutes.add(doc.routePath);
+      allDocs.push(doc);
+    }
+  }
+  validRoutes.add("/");
+  const changelogPath = resolve(userRoot, "CHANGELOG.md");
+  if (existsSync(changelogPath)) {
+    validRoutes.add("/changelog");
+  }
+  const roadmapPath = resolve(userRoot, "ROADMAP.md");
+  if (existsSync(roadmapPath)) {
+    validRoutes.add("/roadmap");
+  }
+  const expandedRoutes = new Set(validRoutes);
+  for (const route of validRoutes) {
+    expandedRoutes.add(route.replace(/\/$/, ""));
+    if (route !== "/") expandedRoutes.add(route + "/");
+  }
+  const mdLinkRegex = /\[(?:[^\]]*)\]\(([^)]+)\)/g;
+  const hrefRegex = /href=["']([^"']+)["']/g;
+  const brokenLinks = [];
+  for (const doc of allDocs) {
+    if (!existsSync(doc.filePath)) continue;
+    const content = readFileSync(doc.filePath, "utf-8");
+    const lines = content.split("\n");
+    for (let i = 0; i < lines.length; i++) {
+      const line = lines[i];
+      const lineNum = i + 1;
+      if (line.trimStart().startsWith("```")) continue;
+      for (const regex of [mdLinkRegex, hrefRegex]) {
+        regex.lastIndex = 0;
+        let match;
+        while ((match = regex.exec(line)) !== null) {
+          const rawLink = match[1].split(/[\s"'#]/)[0];
+          if (!rawLink || rawLink.startsWith("http://") || rawLink.startsWith("https://") || rawLink.startsWith("#") || rawLink.startsWith("mailto:") || rawLink.startsWith("tel:") || rawLink.startsWith("//") || rawLink.startsWith("{") || rawLink.startsWith("data:")) {
+            continue;
+          }
+          if (/\.(png|jpe?g|gif|svg|webp|ico|pdf|zip|tar|gz)$/i.test(rawLink)) {
+            continue;
+          }
+          let normalized = rawLink;
+          normalized = normalized.replace(/\.(mdx?|html?)$/, "");
+          if (!normalized.startsWith("/")) {
+            const docDir = doc.routePath.substring(0, doc.routePath.lastIndexOf("/")) || "/";
+            normalized = docDir === "/" ? "/" + normalized : docDir + "/" + normalized;
+          }
+          const check = normalized === "/" ? "/" : normalized.replace(/\/$/, "");
+          const checkNoIndex = check.replace(/\/index$/, "") || "/";
+          if (!expandedRoutes.has(check) && !expandedRoutes.has(checkNoIndex)) {
+            const suggestion = findClosest(check, validRoutes);
+            brokenLinks.push({
+              file: doc.filePath,
+              line: lineNum,
+              link: rawLink,
+              ...suggestion ? { suggestion } : {}
+            });
+          }
+        }
+      }
+    }
+  }
+  if (brokenLinks.length === 0) {
+    console.log("\n  No broken links found.\n");
+  } else {
+    console.log(`
+  Found ${brokenLinks.length} broken link${brokenLinks.length === 1 ? "" : "s"}:
+`);
+    const byFile = /* @__PURE__ */ new Map();
+    for (const bl of brokenLinks) {
+      const rel = bl.file.replace(userRoot + "/", "");
+      if (!byFile.has(rel)) byFile.set(rel, []);
+      byFile.get(rel).push(bl);
+    }
+    for (const [file, links] of byFile) {
+      console.log(`  ${file}`);
+      for (const link of links) {
+        const suggestion = link.suggestion ? ` (did you mean ${link.suggestion}?)` : "";
+        console.log(`    line ${link.line}: ${link.link}${suggestion}`);
+      }
+      console.log();
+    }
+  }
+  if (brokenLinks.length > 0 || fmResult.errors > 0) {
+    process.exitCode = 1;
+  }
+}
+function findClosest(target, routes) {
+  let best;
+  let bestScore = Infinity;
+  const targetSegments = target.split("/").filter(Boolean);
+  for (const route of routes) {
+    const routeSegments = route.split("/").filter(Boolean);
+    const dist = levenshtein(target, route);
+    const common = targetSegments.filter((s) => routeSegments.includes(s)).length;
+    const score = dist - common * 2;
+    if (score < bestScore) {
+      bestScore = score;
+      best = route;
+    }
+  }
+  if (best && bestScore < target.length * 0.6) return best;
+  return void 0;
+}
+function levenshtein(a, b) {
+  const m = a.length;
+  const n = b.length;
+  const dp = Array.from({ length: m + 1 }, () => Array(n + 1).fill(0));
+  for (let i = 0; i <= m; i++) dp[i][0] = i;
+  for (let j = 0; j <= n; j++) dp[0][j] = j;
+  for (let i = 1; i <= m; i++) {
+    for (let j = 1; j <= n; j++) {
+      dp[i][j] = a[i - 1] === b[j - 1] ? dp[i - 1][j - 1] : 1 + Math.min(dp[i - 1][j], dp[i][j - 1], dp[i - 1][j - 1]);
+    }
+  }
+  return dp[m][n];
+}
+
+export {
+  checkFrontmatter,
+  checkLinks
+};

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

@@ -6,10 +6,10 @@ import {
   resolveConfig,
   resolveSections,
   scanHubProjects
-} from "./chunk-PQMKRFBQ.js";
+} from "./chunk-PVTUVUBK.js";
 import {
   buildSectionData
-} from "./chunk-QNC5QRIO.js";
+} from "./chunk-QTGT76RY.js";
 
 // src/vite-plugin/index.ts
 import { resolve } from "path";
@@ -49,10 +49,16 @@ function clearifyPlugin(options = {}) {
   let allSectionNavigations;
   let allSearchEntries;
   let mermaidSvgData = options.mermaidSvgs ?? {};
+  function getRootFiles() {
+    return {
+      changelogPath: resolve(userRoot, "CHANGELOG.md"),
+      roadmapPath: resolve(userRoot, "ROADMAP.md")
+    };
+  }
   async function refreshDocs() {
-    const changelogPath = resolve(userRoot, "CHANGELOG.md");
+    const rootFiles = getRootFiles();
     sectionDataList = visibleSections.map(
-      (section) => buildSectionData(section, changelogPath, config.navigation)
+      (section) => buildSectionData(section, rootFiles, config.navigation)
     );
     allRoutes = sectionDataList.flatMap((sd) => sd.routes);
     allSectionNavigations = sectionDataList.map((sd) => sd.navigation);
@@ -222,7 +228,7 @@ ${routeEntries.join(",\n")}
       const userConfig = await loadUserConfig(userRoot);
       config = resolveConfig(userConfig, userRoot);
       config = await scanHubProjects(config, userRoot);
-      const allSections = resolveSections(config, userRoot);
+      const allSections = await resolveSections(config, userRoot);
       const isDev = resolvedViteConfig.command === "serve";
       visibleSections = isDev ? allSections : allSections.filter((s) => !s.draft);
       await refreshDocs();
@@ -266,9 +272,11 @@ ${routeEntries.join(",\n")}
       for (const section of visibleSections) {
         server.watcher.add(section.docsDir);
       }
-      const changelogPath = resolve(userRoot, "CHANGELOG.md");
-      if (existsSync(changelogPath)) {
-        server.watcher.add(changelogPath);
+      const rootFiles = getRootFiles();
+      for (const rootFile of [rootFiles.changelogPath, rootFiles.roadmapPath]) {
+        if (rootFile && existsSync(rootFile)) {
+          server.watcher.add(rootFile);
+        }
       }
       if (config.openapi?.spec) {
         const openapiPath = resolve(userRoot, config.openapi.spec);
@@ -385,9 +393,10 @@ ${routeEntries.join(",\n")}
         });
       }
       server.watcher.on("all", (event, path) => {
-        const isChangelog = path === changelogPath;
+        const isChangelog = path === rootFiles.changelogPath;
+        const isRoadmap = path === rootFiles.roadmapPath;
         const isInSection = visibleSections.some((s) => path.startsWith(s.docsDir));
-        if (!isChangelog && !isInSection) return;
+        if (!isChangelog && !isRoadmap && !isInSection) return;
         if (!path.endsWith(".md") && !path.endsWith(".mdx")) return;
         if (event === "add" || event === "unlink" || event === "change") {
           refreshDocs().then(() => {