@marlinjai/clearify 1.10.0 → 1.11.1

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-EKN6DWXT.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(
@@ -222,11 +245,13 @@ When making changes to this project, keep the documentation in sync:
 
 1. **Changelog** \u2014 After any user-facing change, add a bullet under \`## [Unreleased]\` in \`CHANGELOG.md\` using [Keep a Changelog](https://keepachangelog.com/) format (\`Added\`, \`Changed\`, \`Fixed\`, \`Removed\`).
 
-2. **Docs pages** \u2014 When a feature or behavior changes, update the relevant page in \`docs/public/\`. If a new feature has no page, create one.
+2. **Roadmap** \u2014 When a planned feature is implemented, move it from \`Planned\` or \`In Progress\` to \`Completed\` in \`ROADMAP.md\`. When new work is decided, add it to \`Planned\`.
+
+3. **Docs pages** \u2014 When a feature or behavior changes, update the relevant page in \`docs/public/\`. If a new feature has no page, create one.
 
-3. **Config docs** \u2014 When config options are added or changed, update \`docs/public/configuration.md\` with the new option, type, default, and description.
+4. **Config docs** \u2014 When config options are added or changed, update \`docs/public/configuration.md\` with the new option, type, default, and description.
 ${hasInternal ? `
-4. **Architecture decisions** \u2014 For significant design decisions, add an entry to \`docs/internal/\` explaining the context, decision, and trade-offs.
+5. **Architecture decisions** \u2014 For significant design decisions, add an entry to \`docs/internal/\` explaining the context, decision, and trade-offs.
 ` : ""}`;
       writeFileSync(claudeRulesPath, rulesContent);
       console.log("  Created .claude/rules/clearify-docs.md");

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

@@ -8,7 +8,7 @@ import {
 } from "./chunk-SCZZB7OE.js";
 import {
   clearifyPlugin
-} from "./chunk-2RAA6477.js";
+} from "./chunk-PFX7LHRZ.js";
 import {
   loadUserConfig,
   resolveConfig,
@@ -16,7 +16,7 @@ import {
 } 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;");
 }
@@ -142,9 +155,12 @@ async function buildSite() {
   const ssrOutDir = resolve(outDir, ".ssr");
   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-2RAA6477.js → chunk-PFX7LHRZ.js}

@@ -9,7 +9,7 @@ import {
 } 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);
@@ -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(() => {

package/dist/node/{chunk-QNC5QRIO.js → chunk-QTGT76RY.js}

@@ -40,7 +40,13 @@ function scanDocs(docsDir, exclude = [], basePath = "/") {
         title: data.title ?? toTitleCase(basename(filePath, extname(filePath))),
         description: data.description,
         icon: data.icon,
-        order: data.order
+        order: data.order,
+        summary: data.summary,
+        category: data.category,
+        tags: data.tags,
+        projects: data.projects,
+        status: data.status,
+        date: data.date
       }
     };
   });
@@ -127,20 +133,35 @@ function buildRoutes(docs, sectionId) {
     ...sectionId ? { sectionId } : {}
   }));
 }
-function buildSectionData(section, changelogPath, customNavigation) {
+function buildSectionData(section, rootFiles, customNavigation) {
   const docs = scanDocs(section.docsDir, section.exclude, section.basePath);
-  if (section.basePath === "/" && changelogPath && existsSync(changelogPath)) {
-    const content = readFileSync(changelogPath, "utf-8");
-    const { data } = matter(content);
-    docs.push({
-      filePath: changelogPath,
-      routePath: "/changelog",
-      frontmatter: {
-        title: data.title ?? "Changelog",
-        description: data.description ?? "Release history",
-        order: 9999
-      }
-    });
+  if (section.basePath === "/") {
+    if (rootFiles?.changelogPath && existsSync(rootFiles.changelogPath)) {
+      const content = readFileSync(rootFiles.changelogPath, "utf-8");
+      const { data } = matter(content);
+      docs.push({
+        filePath: rootFiles.changelogPath,
+        routePath: "/changelog",
+        frontmatter: {
+          title: data.title ?? "Changelog",
+          description: data.description ?? "Release history",
+          order: 9999
+        }
+      });
+    }
+    if (rootFiles?.roadmapPath && existsSync(rootFiles.roadmapPath)) {
+      const content = readFileSync(rootFiles.roadmapPath, "utf-8");
+      const { data } = matter(content);
+      docs.push({
+        filePath: rootFiles.roadmapPath,
+        routePath: "/roadmap",
+        frontmatter: {
+          title: data.title ?? "Roadmap",
+          description: data.description ?? "Planned and upcoming features",
+          order: 9998
+        }
+      });
+    }
   }
   const nav = section.basePath === "/" && customNavigation ? customNavigation : buildNavigation(docs, section.basePath);
   const navigation = {

package/dist/node/cli/index.js

@@ -1,5 +1,21 @@
 // src/cli/index.ts
 import cac from "cac";
+import { dirname, join } from "path";
+import { fileURLToPath } from "url";
+import { readFileSync, existsSync } from "fs";
+function findPackageVersion() {
+  let dir = dirname(fileURLToPath(import.meta.url));
+  for (let i = 0; i < 5; i++) {
+    const pkgPath = join(dir, "package.json");
+    if (existsSync(pkgPath)) {
+      const pkg = JSON.parse(readFileSync(pkgPath, "utf-8"));
+      if (pkg.name === "clearify" || pkg.name === "@marlinjai/clearify") return pkg.version;
+    }
+    dir = dirname(dir);
+  }
+  return "0.0.0";
+}
+var version = findPackageVersion();
 var cli = cac("clearify");
 cli.command("dev", "Start development server").option("--port <port>", "Port to listen on").option("--host", "Expose to network").action(async (options) => {
   const { createServer } = await import("../node/index.js");
@@ -22,9 +38,9 @@ cli.command("init", "Scaffold a docs folder").option("--no-internal", "Skip crea
   const { init } = await import("../node/index.js");
   await init({ noInternal: options.noInternal, noClaudeRules: options.noClaudeRules });
 });
-cli.command("check", "Check for broken internal links").action(async () => {
+cli.command("check", "Check for broken internal links and frontmatter issues").option("--frontmatter", "Only run frontmatter validation (skip broken link detection)").action(async (options) => {
   const { checkLinks } = await import("../node/check.js");
-  await checkLinks();
+  await checkLinks({ frontmatterOnly: options.frontmatter });
 });
 cli.command("openapi:generate", "Generate OpenAPI spec from NestJS app").option("--module <path>", "Path to NestJS app module", { default: "./src/app.module.ts" }).option("--output <path>", "Output path for spec file", { default: "./docs/openapi.json" }).option("--title <title>", "API documentation title").option("--description <desc>", "API documentation description").option("--version <version>", "API version").action(async (options) => {
   const { generateSpec } = await import("../presets/nestjs.js");
@@ -37,5 +53,5 @@ cli.command("openapi:generate", "Generate OpenAPI spec from NestJS app").option(
   });
 });
 cli.help();
-cli.version("1.8.0");
+cli.version(version);
 cli.parse();

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

@@ -1,2 +1,2 @@
 import '../types/index.js';
-export { D as DocFile, S as SectionData, b as buildNavigation, a as buildRoutes, c as buildSectionData, s as scanDocs } from './search.js';
+export { D as DocFile, R as RootFileOptions, S as SectionData, b as buildNavigation, a as buildRoutes, c as buildSectionData, s as scanDocs } from './search.js';

package/dist/node/core/navigation.js

@@ -3,7 +3,7 @@ import {
   buildRoutes,
   buildSectionData,
   scanDocs
-} from "../chunk-QNC5QRIO.js";
+} from "../chunk-QTGT76RY.js";
 import "../chunk-5TD7NQIW.js";
 export {
   buildNavigation,

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

@@ -26,6 +26,10 @@ interface SectionData {
     routes: RouteEntry[];
     searchEntries: SearchEntry[];
 }
-declare function buildSectionData(section: ResolvedSection, changelogPath?: string, customNavigation?: NavigationItem[] | null): SectionData;
+interface RootFileOptions {
+    changelogPath?: string;
+    roadmapPath?: string;
+}
+declare function buildSectionData(section: ResolvedSection, rootFiles?: RootFileOptions, customNavigation?: NavigationItem[] | null): SectionData;
 
-export { type DocFile as D, type SectionData as S, type SearchEntry, buildRoutes as a, buildNavigation as b, buildSearchIndex, buildSectionData as c, scanDocs as s };
+export { type DocFile as D, type RootFileOptions as R, type SectionData as S, type SearchEntry, buildRoutes as a, buildNavigation as b, buildSearchIndex, buildSectionData as c, scanDocs as s };

package/dist/node/node/build.js

@@ -1,14 +1,14 @@
 import {
   buildSite
-} from "../chunk-ZNURJXMI.js";
+} from "../chunk-JU53JE4P.js";
 import "../chunk-PRTER35L.js";
 import "../chunk-SCZZB7OE.js";
-import "../chunk-2RAA6477.js";
+import "../chunk-PFX7LHRZ.js";
 import "../chunk-B2Q23JW3.js";
 import "../chunk-PVTUVUBK.js";
 import "../chunk-AJBCHKBP.js";
 import "../chunk-V7LLYIRO.js";
-import "../chunk-QNC5QRIO.js";
+import "../chunk-QTGT76RY.js";
 import "../chunk-5TD7NQIW.js";
 export {
   buildSite

package/dist/node/node/check.d.ts

@@ -1,3 +1,10 @@
-declare function checkLinks(): Promise<void>;
+interface CheckOptions {
+    frontmatterOnly?: boolean;
+}
+declare function checkFrontmatter(): Promise<{
+    errors: number;
+    warnings: number;
+}>;
+declare function checkLinks(options?: CheckOptions): Promise<void>;
 
-export { checkLinks };
+export { type CheckOptions, checkFrontmatter, checkLinks };

package/dist/node/node/check.js

@@ -1,11 +1,13 @@
 import {
+  checkFrontmatter,
   checkLinks
-} from "../chunk-ELRDUSZS.js";
+} from "../chunk-NGWAMBXS.js";
 import "../chunk-PVTUVUBK.js";
 import "../chunk-AJBCHKBP.js";
 import "../chunk-V7LLYIRO.js";
-import "../chunk-QNC5QRIO.js";
+import "../chunk-QTGT76RY.js";
 import "../chunk-5TD7NQIW.js";
 export {
+  checkFrontmatter,
   checkLinks
 };

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

@@ -1,7 +1,7 @@
 import * as vite from 'vite';
 export { buildSite as build } from './build.js';
 export { init } from './init.js';
-export { checkLinks } from './check.js';
+export { checkFrontmatter, checkLinks } from './check.js';
 
 declare function createServer(options?: {
     port?: number;

package/dist/node/node/index.js

@@ -1,27 +1,28 @@
 import {
   buildSite
-} from "../chunk-ZNURJXMI.js";
+} from "../chunk-JU53JE4P.js";
 import {
   remarkMermaidToComponent
 } from "../chunk-PRTER35L.js";
 import "../chunk-SCZZB7OE.js";
 import {
   clearifyPlugin
-} from "../chunk-2RAA6477.js";
+} from "../chunk-PFX7LHRZ.js";
 import "../chunk-B2Q23JW3.js";
 import {
   init
-} from "../chunk-QIAMD2Q6.js";
+} from "../chunk-EKN6DWXT.js";
 import {
+  checkFrontmatter,
   checkLinks
-} from "../chunk-ELRDUSZS.js";
+} from "../chunk-NGWAMBXS.js";
 import {
   loadUserConfig,
   resolveConfig
 } from "../chunk-PVTUVUBK.js";
 import "../chunk-AJBCHKBP.js";
 import "../chunk-V7LLYIRO.js";
-import "../chunk-QNC5QRIO.js";
+import "../chunk-QTGT76RY.js";
 import "../chunk-5TD7NQIW.js";
 
 // src/node/index.ts
@@ -32,8 +33,9 @@ import remarkGfm from "remark-gfm";
 import remarkFrontmatter from "remark-frontmatter";
 import remarkMdxFrontmatter from "remark-mdx-frontmatter";
 import rehypeShiki from "@shikijs/rehype";
-import { resolve } from "path";
+import { resolve, dirname } from "path";
 import { fileURLToPath } from "url";
+import { createRequire } from "module";
 import tailwindcss from "@tailwindcss/vite";
 import { existsSync } from "fs";
 function findPackageRoot() {
@@ -50,9 +52,22 @@ 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 createDevConfig(overrides = {}) {
   const root = resolveClientPath();
   const { userRoot, mermaidStrategy, ...viteOverrides } = overrides;
+  const { alias: dedupeAlias, dedupe } = dedupeResolve();
   return {
     root,
     plugins: [
@@ -79,8 +94,10 @@ function createDevConfig(overrides = {}) {
     },
     resolve: {
       alias: {
-        "@clearify": resolve(root, "..")
-      }
+        "@clearify": resolve(root, ".."),
+        ...dedupeAlias
+      },
+      dedupe
     },
     ...viteOverrides
   };
@@ -103,6 +120,7 @@ async function createServer(options = {}) {
 }
 export {
   buildSite as build,
+  checkFrontmatter,
   checkLinks,
   createServer,
   init

package/dist/node/node/init.js

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

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

@@ -70,11 +70,18 @@ interface NavigationItem {
     badgeColor?: string;
     children?: NavigationItem[];
 }
+type DocCategory = 'documentation' | 'internal' | 'plan' | 'research' | 'decision' | 'roadmap' | 'changelog';
 interface PageFrontmatter {
     title?: string;
     description?: string;
     icon?: string;
     order?: number;
+    summary?: string;
+    category?: DocCategory;
+    tags?: string[];
+    projects?: string[];
+    status?: 'active' | 'superseded' | 'archived';
+    date?: string;
 }
 interface RouteEntry {
     path: string;
@@ -106,4 +113,4 @@ interface HubConfig {
 }
 declare function defineConfig(config: Partial<ClearifyConfig>): Partial<ClearifyConfig>;
 
-export { type ClearifyConfig, type HubConfig, type HubProject, type NavigationItem, type PageFrontmatter, type RemoteGitSource, type ResolvedSection, type RouteEntry, type SectionConfig, type SectionNavigation, defineConfig };
+export { type ClearifyConfig, type DocCategory, type HubConfig, type HubProject, type NavigationItem, type PageFrontmatter, type RemoteGitSource, type ResolvedSection, type RouteEntry, type SectionConfig, type SectionNavigation, defineConfig };

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

@@ -1,11 +1,11 @@
 import {
   clearifyPlugin
-} from "../chunk-2RAA6477.js";
+} from "../chunk-PFX7LHRZ.js";
 import "../chunk-B2Q23JW3.js";
 import "../chunk-PVTUVUBK.js";
 import "../chunk-AJBCHKBP.js";
 import "../chunk-V7LLYIRO.js";
-import "../chunk-QNC5QRIO.js";
+import "../chunk-QTGT76RY.js";
 import "../chunk-5TD7NQIW.js";
 export {
   clearifyPlugin

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@marlinjai/clearify",
-  "version": "1.10.0",
+  "version": "1.11.1",
   "description": "An open-source documentation site generator. Turn markdown into beautiful docs.",
   "type": "module",
   "bin": {
@@ -24,7 +24,9 @@
   ],
   "scripts": {
     "build": "tsup",
-    "dev:self": "node bin/clearify.js dev"
+    "dev:self": "node bin/clearify.js dev",
+    "prepare": "husky",
+    "release": "semantic-release"
   },
   "dependencies": {
     "@mdx-js/react": "^3.1.1",
@@ -63,12 +65,18 @@
     }
   },
   "devDependencies": {
+    "@commitlint/cli": "^20.4.3",
+    "@commitlint/config-conventional": "^20.4.3",
+    "@semantic-release/changelog": "^6.0.3",
+    "@semantic-release/git": "^10.0.1",
     "@types/mdast": "^4.0.4",
     "@types/node": "^25.2.2",
     "@types/react": "^18.3.18",
     "@types/react-dom": "^18.3.5",
     "esbuild": "^0.27.3",
+    "husky": "^9.1.7",
     "puppeteer": "^24.37.2",
+    "semantic-release": "^25.0.3",
     "tsup": "^8.3.6",
     "typescript": "^5.7.3"
   },

package/src/theme/Sidebar.tsx

@@ -449,25 +449,26 @@ function NavItem({ item, depth, onNavigate, expandedGroups, onToggleGroup, group
             display: 'flex',
             alignItems: 'center',
             width: '100%',
-            padding: '0.4rem 0.75rem',
+            padding: depth === 0 ? '0.4rem 0.75rem' : '0.35rem 0.75rem',
+            paddingLeft: `${0.75 + depth * 0.75}rem`,
             background: 'none',
             border: 'none',
             cursor: 'pointer',
-            fontSize: '0.6875rem',
-            fontWeight: 600,
-            textTransform: 'uppercase',
-            letterSpacing: '0.06em',
-            color: 'var(--clearify-text-tertiary)',
-            marginTop: depth === 0 ? '1.25rem' : 0,
+            fontSize: depth === 0 ? '0.6875rem' : '0.75rem',
+            fontWeight: depth === 0 ? 600 : 500,
+            textTransform: depth === 0 ? 'uppercase' : 'none',
+            letterSpacing: depth === 0 ? '0.06em' : '0.01em',
+            color: depth === 0 ? 'var(--clearify-text-tertiary)' : 'var(--clearify-text-secondary)',
+            marginTop: depth === 0 ? '1.25rem' : '0.375rem',
             borderRadius: 'var(--clearify-radius-sm)',
             transition: 'color 0.15s',
           }}
-          onMouseEnter={(e) => (e.currentTarget.style.color = 'var(--clearify-text-secondary)')}
-          onMouseLeave={(e) => (e.currentTarget.style.color = 'var(--clearify-text-tertiary)')}
+          onMouseEnter={(e) => (e.currentTarget.style.color = depth === 0 ? 'var(--clearify-text-secondary)' : 'var(--clearify-text)')}
+          onMouseLeave={(e) => (e.currentTarget.style.color = depth === 0 ? 'var(--clearify-text-tertiary)' : 'var(--clearify-text-secondary)')}
         >
           <svg
-            width="12"
-            height="12"
+            width={depth === 0 ? '12' : '10'}
+            height={depth === 0 ? '12' : '10'}
             viewBox="0 0 24 24"
             fill="none"
             stroke="currentColor"
@@ -479,6 +480,7 @@ function NavItem({ item, depth, onNavigate, expandedGroups, onToggleGroup, group
               transition: 'transform 0.2s cubic-bezier(0.4, 0, 0.2, 1)',
               transform: expanded ? 'rotate(90deg)' : 'rotate(0deg)',
               flexShrink: 0,
+              opacity: depth === 0 ? 1 : 0.7,
             }}
           >
             <polyline points="9 18 15 12 9 6" />

package/dist/node/chunk-ELRDUSZS.js

@@ -1,136 +0,0 @@
-import {
-  loadUserConfig,
-  resolveConfig,
-  resolveSections
-} from "./chunk-PVTUVUBK.js";
-import {
-  scanDocs
-} from "./chunk-QNC5QRIO.js";
-
-// src/node/check.ts
-import { resolve } from "path";
-import { readFileSync, existsSync } from "fs";
-async function checkLinks() {
-  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 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");
-    return;
-  }
-  console.log(`
-  Found ${brokenLinks.length} broken link${brokenLinks.length === 1 ? "" : "s"}:
-`);
-  const byFile = /* @__PURE__ */ new Map();
-  for (const bl of brokenLinks) {
-    const relative = bl.file.replace(userRoot + "/", "");
-    if (!byFile.has(relative)) byFile.set(relative, []);
-    byFile.get(relative).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();
-  }
-  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 {
-  checkLinks
-};