@marlinjai/clearify 1.5.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 MarlinJai
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,81 @@
+# Clearify
+
+An open-source documentation site generator. Turn markdown into beautiful docs.
+
+## Features
+
+- **Zero config** — drop markdown files in `docs/public/` and go
+- **MDX support** — use React components in your docs (Callout, Tabs, Steps, Cards, CodeGroup, Accordion, Badge, Tooltip, Columns, Frame)
+- **Mermaid diagrams** — fenced `mermaid` code blocks render as SVG, with optional build-time pre-rendering via Puppeteer
+- **Built-in search** — instant full-text search across all pages and API endpoints
+- **Dark mode** — automatic light/dark theme switching
+- **Syntax highlighting** — beautiful code blocks with Shiki (dual light/dark themes)
+- **SSG & SEO** — pre-rendered HTML, Open Graph, Twitter Cards, JSON-LD, sitemap, robots.txt
+- **OpenAPI / Scalar** — render API reference docs from an OpenAPI spec, with theme sync and dark mode
+- **Multi-section support** — pill-based section switcher (e.g. public docs + internal docs)
+- **Auto changelog** — drop a `CHANGELOG.md` in your project root, it appears as `/changelog`
+
+## Quick Start
+
+Install Clearify as a dev dependency:
+
+```bash
+npm install @marlinjai/clearify --save-dev
+```
+
+Scaffold your project:
+
+```bash
+npx clearify init
+```
+
+Start the dev server:
+
+```bash
+npx clearify dev
+```
+
+Your docs are live at `http://localhost:4747`.
+
+## Configuration
+
+Customize with `clearify.config.ts`:
+
+```typescript
+import { defineConfig } from '@marlinjai/clearify';
+
+export default defineConfig({
+  name: 'My Project',
+  sections: [
+    { label: 'Docs', docsDir: './docs/public' },
+    { label: 'Internal', docsDir: './docs/internal', basePath: '/internal', draft: true },
+  ],
+  theme: {
+    primaryColor: '#3B82F6',
+    mode: 'auto',
+  },
+  openapi: {
+    spec: './docs/openapi.json',
+  },
+});
+```
+
+## CLI Commands
+
+| Command | Description |
+|---------|-------------|
+| `clearify dev` | Start Vite-powered dev server with HMR |
+| `clearify build` | Build static documentation site |
+| `clearify init` | Scaffold a docs folder (use `--no-internal` to skip internal section) |
+| `clearify check` | Check for broken internal links |
+| `clearify openapi:generate` | Generate OpenAPI spec from a NestJS app |
+
+## Links
+
+- [Documentation](https://github.com/marlinjai/clearify)
+- [GitHub](https://github.com/marlinjai/clearify)
+- [Changelog](./CHANGELOG.md)
+
+## License
+
+[MIT](./LICENSE)

package/bin/clearify.js

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import('../dist/node/cli/index.js');

package/dist/node/chunk-5TD7NQIW.js

@@ -0,0 +1,25 @@
+// src/core/search.ts
+import { readFileSync } from "fs";
+import matter from "gray-matter";
+function stripMarkdown(md) {
+  return md.replace(/^---[\s\S]*?---\n*/m, "").replace(/```[\s\S]*?```/g, "").replace(/`[^`]+`/g, "").replace(/#{1,6}\s/g, "").replace(/\[([^\]]+)\]\([^)]+\)/g, "$1").replace(/!\[([^\]]*)\]\([^)]+\)/g, "$1").replace(/<[^>]+>/g, "").replace(/[*_]{1,3}([^*_]+)[*_]{1,3}/g, "$1").replace(/\s+/g, " ").trim();
+}
+function buildSearchIndex(docs, sectionId, sectionLabel) {
+  return docs.map((doc, i) => {
+    const raw = readFileSync(doc.filePath, "utf-8");
+    const { content } = matter(raw);
+    return {
+      id: i,
+      path: doc.routePath,
+      title: doc.frontmatter.title ?? "",
+      description: doc.frontmatter.description ?? "",
+      content: stripMarkdown(content),
+      ...sectionId ? { sectionId } : {},
+      ...sectionLabel ? { sectionLabel } : {}
+    };
+  });
+}
+
+export {
+  buildSearchIndex
+};

package/dist/node/chunk-B2Q23JW3.js

@@ -0,0 +1,55 @@
+// src/core/openapi-parser.ts
+var HTTP_METHODS = ["get", "post", "put", "delete", "patch"];
+function parseOpenAPISpec(spec) {
+  const tagMap = /* @__PURE__ */ new Map();
+  const tagDescriptions = /* @__PURE__ */ new Map();
+  if (Array.isArray(spec.tags)) {
+    for (const t of spec.tags) {
+      if (t.name && t.description) {
+        tagDescriptions.set(t.name, t.description);
+      }
+    }
+  }
+  const paths = spec.paths ?? {};
+  for (const [path, pathItem] of Object.entries(paths)) {
+    if (!pathItem || typeof pathItem !== "object") continue;
+    for (const method of HTTP_METHODS) {
+      const operation = pathItem[method];
+      if (!operation || typeof operation !== "object") continue;
+      const tags = Array.isArray(operation.tags) && operation.tags.length > 0 ? [operation.tags[0]] : ["Default"];
+      const op = {
+        method: method.toUpperCase(),
+        path,
+        summary: operation.summary ?? operation.description ?? `${method.toUpperCase()} ${path}`,
+        operationId: operation.operationId
+      };
+      for (const tag of tags) {
+        const existing = tagMap.get(tag);
+        if (existing) {
+          existing.push(op);
+        } else {
+          tagMap.set(tag, [op]);
+        }
+      }
+    }
+  }
+  const groups = [];
+  for (const [tag, operations] of tagMap) {
+    operations.sort((a, b) => a.path.localeCompare(b.path));
+    groups.push({
+      tag,
+      description: tagDescriptions.get(tag),
+      operations
+    });
+  }
+  groups.sort((a, b) => {
+    if (a.tag === "Default") return 1;
+    if (b.tag === "Default") return -1;
+    return a.tag.localeCompare(b.tag);
+  });
+  return groups;
+}
+
+export {
+  parseOpenAPISpec
+};

package/dist/node/chunk-CQ4MNGBE.js

@@ -0,0 +1,301 @@
+import {
+  clearPreRenderedMermaidSvgs,
+  remarkMermaidToComponent,
+  setPreRenderedMermaidSvgs
+} from "./chunk-PRTER35L.js";
+import {
+  mermaidContentHash
+} from "./chunk-SCZZB7OE.js";
+import {
+  clearifyPlugin
+} from "./chunk-NXQNNLGC.js";
+import {
+  loadUserConfig,
+  resolveConfig,
+  resolveSections
+} from "./chunk-IBK35HZR.js";
+import {
+  buildSectionData
+} from "./chunk-L24ILRSX.js";
+
+// src/node/build.ts
+import { build as viteBuild } from "vite";
+import react from "@vitejs/plugin-react";
+import mdx from "@mdx-js/rollup";
+import remarkGfm from "remark-gfm";
+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 { writeFileSync, readFileSync, existsSync, mkdirSync, rmSync, copyFileSync } from "fs";
+import { basename } from "path";
+import { fileURLToPath } from "url";
+function findPackageRoot() {
+  let dir = fileURLToPath(new URL(".", import.meta.url));
+  for (let i = 0; i < 10; i++) {
+    if (existsSync(resolve(dir, "package.json"))) return dir;
+    const parent = resolve(dir, "..");
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return process.cwd();
+}
+function resolveClientPath(...segments) {
+  const packageRoot = findPackageRoot();
+  return resolve(packageRoot, "src", "client", ...segments);
+}
+function escapeHtml(str) {
+  return str.replace(/&/g, "&amp;").replace(/"/g, "&quot;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+}
+function generateSitemap(routes, siteUrl) {
+  const base = siteUrl?.replace(/\/$/, "") ?? "";
+  const urls = routes.map((r) => {
+    const loc = base ? `${base}${r.path === "/" ? "/" : r.path + "/"}` : r.path === "/" ? "/" : r.path + "/";
+    return `  <url><loc>${loc}</loc></url>`;
+  });
+  return `<?xml version="1.0" encoding="UTF-8"?>
+<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
+${urls.join("\n")}
+</urlset>`;
+}
+function generateRobotsTxt(siteUrl) {
+  const lines = ["User-agent: *", "Allow: /"];
+  if (siteUrl) {
+    const base = siteUrl.replace(/\/$/, "");
+    lines.push(`Sitemap: ${base}/sitemap.xml`);
+  }
+  return lines.join("\n") + "\n";
+}
+function injectSSR(template, opts) {
+  const siteBase = opts.siteUrl?.replace(/\/$/, "") ?? "";
+  const canonical = siteBase ? `${siteBase}${opts.url}` : opts.url;
+  const escapedTitle = escapeHtml(opts.title);
+  const escapedDesc = escapeHtml(opts.description);
+  const escapedSiteName = escapeHtml(opts.siteName);
+  const headTags = [
+    `<title>${escapedTitle}</title>`,
+    `<meta name="description" content="${escapedDesc}" />`,
+    `<link rel="canonical" href="${canonical}" />`,
+    `<meta property="og:title" content="${escapedTitle}" />`,
+    `<meta property="og:description" content="${escapedDesc}" />`,
+    `<meta property="og:url" content="${canonical}" />`,
+    `<meta property="og:type" content="article" />`,
+    `<meta property="og:site_name" content="${escapedSiteName}" />`,
+    `<meta name="twitter:card" content="summary" />`,
+    `<meta name="twitter:title" content="${escapedTitle}" />`,
+    `<meta name="twitter:description" content="${escapedDesc}" />`,
+    `<script type="application/ld+json">${JSON.stringify({
+      "@context": "https://schema.org",
+      "@type": "Article",
+      headline: opts.title,
+      description: opts.description,
+      url: canonical
+    })}</script>`,
+    ...opts.customCss ? [`<link rel="stylesheet" href="${escapeHtml(opts.customCss)}" />`] : [],
+    ...opts.headTags ?? []
+  ].join("\n    ");
+  return template.replace("<title>Documentation</title>", "").replace("<!--clearify-head-->", headTags).replace("<!--clearify-outlet-->", opts.html).replace('<div id="root">', '<div id="root" data-clearify-ssr="true">');
+}
+function getSharedPlugins(userRoot, options) {
+  const plugins = [
+    tailwindcss(),
+    ...clearifyPlugin({
+      root: userRoot,
+      mermaidSvgs: options?.mermaidSvgs,
+      mermaidStrategy: options?.mermaidStrategy
+    }),
+    { enforce: "pre", ...mdx({
+      providerImportSource: "@mdx-js/react",
+      remarkPlugins: [remarkMermaidToComponent, remarkGfm, remarkFrontmatter, [remarkMdxFrontmatter, { name: "frontmatter" }]],
+      rehypePlugins: [
+        [rehypeShiki, {
+          themes: { light: "github-light", dark: "github-dark" },
+          defaultColor: false
+        }]
+      ]
+    }) },
+    react({ include: /\.(jsx|tsx|md|mdx)$/ })
+  ];
+  if (options?.mermaidStrategy === "build") {
+    plugins.push({
+      name: "clearify-stub-mermaid",
+      enforce: "pre",
+      resolveId(id) {
+        if (id === "mermaid") return "\0stub:mermaid";
+      },
+      load(id) {
+        if (id === "\0stub:mermaid") {
+          return 'export default { initialize() {}, render() { return { svg: "" }; } };';
+        }
+      }
+    });
+  }
+  return plugins;
+}
+async function buildSite() {
+  const userRoot = process.cwd();
+  const root = resolveClientPath();
+  const userConfig = await loadUserConfig(userRoot);
+  const config = resolveConfig(userConfig);
+  const outDir = resolve(userRoot, config.outDir);
+  const ssrOutDir = resolve(outDir, ".ssr");
+  const allSections = resolveSections(config, userRoot);
+  const productionSections = allSections.filter((s) => !s.draft);
+  const changelogPath = resolve(userRoot, "CHANGELOG.md");
+  const sectionDataList = productionSections.map(
+    (section) => buildSectionData(section, changelogPath, config.navigation)
+  );
+  const allRoutes = sectionDataList.flatMap((sd) => sd.routes);
+  if (config.openapi?.spec && config.openapi.generatePages !== false) {
+    const basePath = config.openapi.basePath ?? "/api";
+    const specPath = resolve(userRoot, config.openapi.spec);
+    if (existsSync(specPath)) {
+      allRoutes.push({
+        path: `${basePath}/*`,
+        filePath: "",
+        componentPath: "@clearify/theme/components/OpenAPIPage",
+        frontmatter: { title: "API Reference", description: "API documentation" },
+        sectionId: "api"
+      });
+    }
+  }
+  const mermaidStrategy = config.mermaid?.strategy ?? "client";
+  let mermaidSvgs;
+  if (mermaidStrategy === "build") {
+    console.log("Building documentation site...\n");
+    console.log("  Step 0: Pre-rendering Mermaid diagrams...");
+    const { MermaidRenderer } = await import("./core/mermaid-renderer.js");
+    const cacheDir = resolve(userRoot, "node_modules/.cache/clearify-mermaid");
+    const renderer = new MermaidRenderer({ cacheDir });
+    try {
+      await renderer.launch();
+      const definitions = /* @__PURE__ */ new Map();
+      const mermaidRegex = /```mermaid\s*\n([\s\S]*?)```/g;
+      for (const route of allRoutes) {
+        if (!route.filePath.endsWith(".md") && !route.filePath.endsWith(".mdx")) continue;
+        if (!existsSync(route.filePath)) continue;
+        const content = readFileSync(route.filePath, "utf-8");
+        let match;
+        while ((match = mermaidRegex.exec(content)) !== null) {
+          const def = match[1].trim();
+          const hash = mermaidContentHash(def);
+          definitions.set(hash, def);
+        }
+      }
+      if (definitions.size > 0) {
+        const rendered = await renderer.renderBatch(definitions);
+        mermaidSvgs = {};
+        const svgMap = /* @__PURE__ */ new Map();
+        for (const [hash, data] of rendered) {
+          mermaidSvgs[hash] = data;
+          svgMap.set(hash, data);
+        }
+        setPreRenderedMermaidSvgs(svgMap);
+        console.log(`  Pre-rendered ${rendered.size} Mermaid diagrams`);
+      } else {
+        console.log("  No Mermaid diagrams found.");
+      }
+    } finally {
+      await renderer.close();
+    }
+  } else {
+    console.log("Building documentation site...\n");
+  }
+  console.log("  Step 1: Client build...");
+  const sharedPluginOptions = {
+    mermaidSvgs,
+    mermaidStrategy
+  };
+  const clientConfig = {
+    root,
+    plugins: getSharedPlugins(userRoot, sharedPluginOptions),
+    resolve: {
+      alias: { "@clearify": resolve(root, "..") }
+    },
+    build: {
+      outDir,
+      emptyOutDir: true
+    }
+  };
+  await viteBuild(clientConfig);
+  console.log("  Client build complete.");
+  console.log("  Step 2: SSR build...");
+  const ssrConfig = {
+    root,
+    plugins: getSharedPlugins(userRoot, sharedPluginOptions),
+    resolve: {
+      alias: { "@clearify": resolve(root, "..") }
+    },
+    build: {
+      outDir: ssrOutDir,
+      ssr: resolveClientPath("entry-server.tsx"),
+      emptyOutDir: true
+    }
+  };
+  await viteBuild(ssrConfig);
+  console.log("  SSR build complete.");
+  console.log("  Step 3: Pre-rendering pages...");
+  const template = readFileSync(resolve(outDir, "index.html"), "utf-8");
+  const ssrModule = await import(resolve(ssrOutDir, "entry-server.js"));
+  const { render } = ssrModule;
+  let resolvedCustomCssHref;
+  if (config.customCss) {
+    const cssSource = resolve(userRoot, config.customCss);
+    if (existsSync(cssSource)) {
+      const cssFilename = basename(cssSource);
+      copyFileSync(cssSource, resolve(outDir, cssFilename));
+      resolvedCustomCssHref = "/" + cssFilename;
+    }
+  }
+  for (const route of allRoutes) {
+    const renderPath = route.path.endsWith("/*") ? route.path.slice(0, -2) : route.path;
+    try {
+      const { html, head } = await render(renderPath);
+      const page = injectSSR(template, {
+        html,
+        title: head.title,
+        description: head.description,
+        url: renderPath,
+        siteName: head.siteName,
+        siteUrl: config.siteUrl,
+        customCss: resolvedCustomCssHref,
+        headTags: config.headTags
+      });
+      if (renderPath === "/") {
+        writeFileSync(resolve(outDir, "index.html"), page);
+      } else {
+        const dir = resolve(outDir, renderPath.replace(/^\//, ""));
+        mkdirSync(dir, { recursive: true });
+        writeFileSync(resolve(dir, "index.html"), page);
+      }
+      console.log(`    Pre-rendered: ${renderPath}`);
+    } catch (err) {
+      console.warn(`    Failed to pre-render ${renderPath}:`, err instanceof Error ? err.message : err);
+    }
+  }
+  writeFileSync(resolve(outDir, "robots.txt"), generateRobotsTxt(config.siteUrl));
+  console.log("  Generated robots.txt");
+  const sitemapSections = new Set(
+    productionSections.filter((s) => s.sitemap).map((s) => s.id)
+  );
+  if (config.openapi?.spec && config.openapi.generatePages !== false) {
+    sitemapSections.add("api");
+  }
+  const sitemapRoutes = allRoutes.filter((r) => !r.sectionId || sitemapSections.has(r.sectionId)).map((r) => ({ ...r, path: r.path.endsWith("/*") ? r.path.slice(0, -2) : r.path }));
+  const sitemap = generateSitemap(sitemapRoutes, config.siteUrl);
+  writeFileSync(resolve(outDir, "sitemap.xml"), sitemap);
+  console.log("  Generated sitemap.xml");
+  rmSync(ssrOutDir, { recursive: true, force: true });
+  console.log("  Cleaned up SSR build artifacts.");
+  if (mermaidStrategy === "build") {
+    clearPreRenderedMermaidSvgs();
+  }
+  console.log(`
+Build complete! Output in ${config.outDir}/
+`);
+}
+
+export {
+  buildSite
+};