@marlinjai/clearify 1.5.0

package/dist/node/chunk-GFD54GNO.js

@@ -0,0 +1,223 @@
+// src/node/init.ts
+import { resolve } from "path";
+import { existsSync, mkdirSync, writeFileSync } from "fs";
+async function init(options = {}) {
+  const cwd = process.cwd();
+  const publicDir = resolve(cwd, "docs/public");
+  const internalDir = resolve(cwd, "docs/internal");
+  const configPath = resolve(cwd, "clearify.config.ts");
+  console.log("\n  Initializing Clearify...\n");
+  if (!existsSync(publicDir)) {
+    mkdirSync(publicDir, { recursive: true });
+    console.log("  Created docs/public/");
+  } else {
+    console.log("  docs/public/ already exists, skipping");
+  }
+  const indexPath = resolve(publicDir, "index.md");
+  if (!existsSync(indexPath)) {
+    writeFileSync(
+      indexPath,
+      `---
+title: Welcome
+description: Welcome to your documentation
+order: 0
+---
+
+# Welcome
+
+Welcome to your documentation site, powered by **Clearify**.
+
+## Getting Started
+
+Edit this file at \`docs/public/index.md\` to update your home page.
+
+## Features
+
+- Write docs in **Markdown** or **MDX**
+- Built-in **search** across all pages
+- **Dark mode** support out of the box
+- **Syntax highlighting** with Shiki
+- **Zero config** \u2014 just add markdown files
+
+## Next Steps
+
+- Add more pages to the \`docs/public/\` folder
+- Create subfolders for organized navigation
+- Customize with \`clearify.config.ts\`
+`
+    );
+    console.log("  Created docs/public/index.md");
+  }
+  const gettingStartedPath = resolve(publicDir, "getting-started.md");
+  if (!existsSync(gettingStartedPath)) {
+    writeFileSync(
+      gettingStartedPath,
+      `---
+title: Getting Started
+description: How to get started with your documentation
+order: 1
+---
+
+# Getting Started
+
+## Adding Pages
+
+Create \`.md\` or \`.mdx\` files in the \`docs/public/\` folder. Each file becomes a page.
+
+## Organizing with Folders
+
+Create subfolders to group related pages:
+
+\`\`\`
+docs/
+\u251C\u2500\u2500 public/
+\u2502   \u251C\u2500\u2500 index.md              # Home page
+\u2502   \u251C\u2500\u2500 getting-started.md    # This page
+\u2502   \u2514\u2500\u2500 guides/
+\u2502       \u251C\u2500\u2500 installation.md
+\u2502       \u2514\u2500\u2500 configuration.md
+\u2514\u2500\u2500 internal/                 # Design docs, roadmaps
+    \u2514\u2500\u2500 index.md
+\`\`\`
+
+Folders automatically become navigation groups.
+
+## Frontmatter
+
+Control page metadata with frontmatter:
+
+\`\`\`yaml
+---
+title: My Page Title
+description: A brief description
+order: 1
+---
+\`\`\`
+
+## Running the Dev Server
+
+\`\`\`bash
+npx clearify dev
+\`\`\`
+
+## Building for Production
+
+\`\`\`bash
+npx clearify build
+\`\`\`
+
+This outputs a static site to \`docs-dist/\`.
+`
+    );
+    console.log("  Created docs/public/getting-started.md");
+  }
+  if (!options.noInternal) {
+    if (!existsSync(internalDir)) {
+      mkdirSync(internalDir, { recursive: true });
+      console.log("  Created docs/internal/");
+    } else {
+      console.log("  docs/internal/ already exists, skipping");
+    }
+    const internalIndexPath = resolve(internalDir, "index.md");
+    if (!existsSync(internalIndexPath)) {
+      writeFileSync(
+        internalIndexPath,
+        `---
+title: Internal Docs
+description: Internal documentation \u2014 design docs, roadmaps, and architecture
+order: 0
+---
+
+# Internal Docs
+
+This section is for internal documentation that isn't published to your public site.
+
+## What goes here?
+
+- **Design documents** \u2014 technical designs and proposals
+- **Roadmaps** \u2014 planned features and milestones
+- **Architecture decisions** \u2014 ADRs and context for past choices
+- **Meeting notes** \u2014 decisions and action items
+
+> This section is marked as \`draft\` and won't be included in production builds.
+`
+      );
+      console.log("  Created docs/internal/index.md");
+    }
+  }
+  const changelogPath = resolve(cwd, "CHANGELOG.md");
+  if (!existsSync(changelogPath)) {
+    const today = (/* @__PURE__ */ new Date()).toISOString().slice(0, 10);
+    writeFileSync(
+      changelogPath,
+      `# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] - ${today}
+
+### Added
+
+- Initial project setup
+- Documentation site powered by Clearify
+`
+    );
+    console.log("  Created CHANGELOG.md");
+  } else {
+    console.log("  CHANGELOG.md already exists, skipping");
+  }
+  if (!existsSync(configPath)) {
+    if (options.noInternal) {
+      writeFileSync(
+        configPath,
+        `import { defineConfig } from 'clearify';
+
+export default defineConfig({
+  name: 'My Documentation',
+  docsDir: './docs/public',
+  theme: {
+    primaryColor: '#3B82F6',
+    mode: 'auto',
+  },
+});
+`
+      );
+    } else {
+      writeFileSync(
+        configPath,
+        `import { defineConfig } from 'clearify';
+
+export default defineConfig({
+  name: 'My Documentation',
+  sections: [
+    { label: 'Docs', docsDir: './docs/public' },
+    { label: 'Internal', docsDir: './docs/internal', basePath: '/internal', draft: true },
+  ],
+  theme: {
+    primaryColor: '#3B82F6',
+    mode: 'auto',
+  },
+});
+`
+      );
+    }
+    console.log("  Created clearify.config.ts");
+  } else {
+    console.log("  clearify.config.ts already exists, skipping");
+  }
+  console.log(`
+  Done! Next steps:
+
+    npx clearify dev        Start the dev server
+    npx clearify build      Build for production
+`);
+}
+
+export {
+  init
+};

package/dist/node/chunk-IBK35HZR.js

@@ -0,0 +1,194 @@
+// src/core/config.ts
+import { z } from "zod";
+import { resolve, basename } from "path";
+import { pathToFileURL } from "url";
+import { existsSync, readFileSync, rmSync } from "fs";
+import { tmpdir } from "os";
+import { randomBytes } from "crypto";
+var NavigationItemSchema = z.lazy(
+  () => z.object({
+    label: z.string(),
+    path: z.string().optional(),
+    icon: z.string().optional(),
+    badge: z.string().optional(),
+    badgeColor: z.string().optional(),
+    children: z.array(NavigationItemSchema).optional()
+  })
+);
+var SectionConfigSchema = z.object({
+  label: z.string(),
+  docsDir: z.string(),
+  basePath: z.string().optional(),
+  draft: z.boolean().optional(),
+  sitemap: z.boolean().optional(),
+  exclude: z.array(z.string()).optional()
+});
+var MermaidConfigSchema = z.object({
+  strategy: z.enum(["client", "build"]).default("client")
+}).default({ strategy: "client" });
+var OpenAPIConfigSchema = z.object({
+  spec: z.string(),
+  basePath: z.string().default("/api"),
+  generatePages: z.boolean().default(true)
+}).optional();
+var ClearifyConfigSchema = z.object({
+  name: z.string().default("Documentation"),
+  docsDir: z.string().default("./docs"),
+  outDir: z.string().default("./docs-dist"),
+  port: z.number().default(4747),
+  siteUrl: z.string().optional(),
+  theme: z.object({
+    primaryColor: z.string().default("#3B82F6"),
+    mode: z.enum(["light", "dark", "auto"]).default("auto")
+  }).default({ primaryColor: "#3B82F6", mode: "auto" }),
+  logo: z.object({
+    light: z.string().optional(),
+    dark: z.string().optional()
+  }).optional(),
+  sections: z.array(SectionConfigSchema).optional(),
+  navigation: z.array(NavigationItemSchema).nullable().default(null),
+  exclude: z.array(z.string()).default([]),
+  mermaid: MermaidConfigSchema,
+  openapi: OpenAPIConfigSchema,
+  links: z.record(z.string(), z.string()).optional(),
+  customCss: z.string().optional(),
+  headTags: z.array(z.string()).optional()
+});
+var defaultConfig = {
+  name: "Documentation",
+  docsDir: "./docs",
+  outDir: "./docs-dist",
+  port: 4747,
+  theme: {
+    primaryColor: "#3B82F6",
+    mode: "auto"
+  },
+  navigation: null
+};
+function detectProjectName(root) {
+  const pkgPath = resolve(root, "package.json");
+  if (existsSync(pkgPath)) {
+    try {
+      const pkg = JSON.parse(readFileSync(pkgPath, "utf-8"));
+      if (pkg.name) {
+        const raw = pkg.name.replace(/^@[^/]+\//, "");
+        return raw.replace(/[-_]/g, " ").replace(/\b\w/g, (c) => c.toUpperCase());
+      }
+    } catch {
+    }
+  }
+  const dirName = basename(root);
+  return dirName.replace(/[-_]/g, " ").replace(/\b\w/g, (c) => c.toUpperCase());
+}
+async function loadTsConfig(configPath) {
+  const { build } = await import("esbuild");
+  const tmpId = randomBytes(4).toString("hex");
+  const outFile = resolve(tmpdir(), `clearify-config-${tmpId}.mjs`);
+  try {
+    await build({
+      entryPoints: [configPath],
+      outfile: outFile,
+      bundle: true,
+      format: "esm",
+      platform: "node",
+      write: true,
+      // Bundle the clearify import (defineConfig is a trivial identity fn),
+      // but keep everything else external so we don't pull in user deps.
+      plugins: [{
+        name: "externalize-except-clearify",
+        setup(build2) {
+          build2.onResolve({ filter: /.*/ }, (args) => {
+            if (args.path.startsWith(".") || args.path.startsWith("/") || args.path === "clearify") {
+              return void 0;
+            }
+            return { path: args.path, external: true };
+          });
+        }
+      }]
+    });
+    const mod = await import(pathToFileURL(outFile).href);
+    return mod.default ?? mod;
+  } finally {
+    try {
+      rmSync(outFile, { force: true });
+    } catch {
+    }
+  }
+}
+async function loadUserConfig(root) {
+  const configFiles = [
+    "clearify.config.ts",
+    "clearify.config.js",
+    "clearify.config.mjs"
+  ];
+  for (const file of configFiles) {
+    const configPath = resolve(root, file);
+    if (existsSync(configPath)) {
+      try {
+        if (file.endsWith(".ts")) {
+          return await loadTsConfig(configPath);
+        }
+        const mod = await import(pathToFileURL(configPath).href);
+        return mod.default ?? mod;
+      } catch {
+      }
+    }
+  }
+  return {};
+}
+function resolveConfig(userConfig = {}, root) {
+  const parsed = ClearifyConfigSchema.parse(userConfig);
+  if (!userConfig.name && root) {
+    parsed.name = detectProjectName(root);
+  }
+  return parsed;
+}
+function slugify(str) {
+  return str.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "");
+}
+function resolveSections(config, root) {
+  if (config.sections && config.sections.length > 0) {
+    const sections = config.sections.map((s, i) => {
+      const id = slugify(s.label);
+      const draft = s.draft ?? false;
+      const basePath = s.basePath ?? (i === 0 ? "/" : "/" + id);
+      const sitemap = s.sitemap ?? !draft;
+      const exclude = [...config.exclude ?? [], ...s.exclude ?? []];
+      return {
+        id,
+        label: s.label,
+        docsDir: resolve(root, s.docsDir),
+        basePath,
+        draft,
+        sitemap,
+        exclude
+      };
+    });
+    const seen = /* @__PURE__ */ new Set();
+    for (const s of sections) {
+      if (seen.has(s.basePath)) {
+        throw new Error(`Duplicate section basePath: "${s.basePath}"`);
+      }
+      seen.add(s.basePath);
+    }
+    return sections;
+  }
+  return [
+    {
+      id: "default",
+      label: config.name,
+      docsDir: resolve(root, config.docsDir),
+      basePath: "/",
+      draft: false,
+      sitemap: true,
+      exclude: config.exclude ?? []
+    }
+  ];
+}
+
+export {
+  defaultConfig,
+  loadUserConfig,
+  resolveConfig,
+  resolveSections
+};

package/dist/node/chunk-L24ILRSX.js

@@ -0,0 +1,125 @@
+import {
+  buildSearchIndex
+} from "./chunk-5TD7NQIW.js";
+
+// src/core/navigation.ts
+import { resolve, relative, basename, dirname, extname } from "path";
+import { readFileSync, existsSync } from "fs";
+import matter from "gray-matter";
+import { globbySync } from "globby";
+function toTitleCase(str) {
+  return str.replace(/[-_]/g, " ").replace(/\b\w/g, (c) => c.toUpperCase());
+}
+function fileToRoutePath(filePath, docsDir, basePath = "/") {
+  const rel = relative(docsDir, filePath);
+  const ext = extname(rel);
+  const withoutExt = rel.slice(0, -ext.length);
+  let routePath;
+  if (withoutExt === "index") routePath = "/";
+  else if (withoutExt.endsWith("/index")) routePath = "/" + withoutExt.slice(0, -"/index".length);
+  else routePath = "/" + withoutExt;
+  if (basePath === "/") return routePath;
+  const prefix = basePath.replace(/\/$/, "");
+  return routePath === "/" ? prefix : prefix + routePath;
+}
+function scanDocs(docsDir, exclude = [], basePath = "/") {
+  const absDocsDir = resolve(docsDir);
+  const files = globbySync("**/*.{md,mdx}", {
+    cwd: absDocsDir,
+    ignore: ["**/node_modules/**", "**/_*", "**/_*/**", ...exclude],
+    absolute: true
+  });
+  return files.map((filePath) => {
+    const content = readFileSync(filePath, "utf-8");
+    const { data } = matter(content);
+    const routePath = fileToRoutePath(filePath, absDocsDir, basePath);
+    return {
+      filePath,
+      routePath,
+      frontmatter: {
+        title: data.title ?? toTitleCase(basename(filePath, extname(filePath))),
+        description: data.description,
+        icon: data.icon,
+        order: data.order
+      }
+    };
+  });
+}
+function buildNavigation(docs, basePath = "/") {
+  const rootDir = basePath === "/" ? "/" : basePath.replace(/\/$/, "");
+  const groups = /* @__PURE__ */ new Map();
+  for (const doc of docs) {
+    const dir = dirname(doc.routePath);
+    if (!groups.has(dir)) groups.set(dir, []);
+    groups.get(dir).push(doc);
+  }
+  for (const files of groups.values()) {
+    files.sort((a, b) => {
+      const orderA = a.frontmatter.order ?? 999;
+      const orderB = b.frontmatter.order ?? 999;
+      if (orderA !== orderB) return orderA - orderB;
+      return a.routePath.localeCompare(b.routePath);
+    });
+  }
+  const nav = [];
+  const rootFiles = groups.get(rootDir) ?? [];
+  for (const doc of rootFiles) {
+    if (doc.routePath === rootDir || doc.routePath === "/") continue;
+    const item = { label: doc.frontmatter.title, path: doc.routePath };
+    if (doc.frontmatter.icon) item.icon = doc.frontmatter.icon;
+    nav.push(item);
+  }
+  const dirs = [...groups.keys()].filter((d) => d !== rootDir).sort();
+  for (const dir of dirs) {
+    const files = groups.get(dir);
+    const label = toTitleCase(basename(dir));
+    const children = files.map((doc) => {
+      const child = { label: doc.frontmatter.title, path: doc.routePath };
+      if (doc.frontmatter.icon) child.icon = doc.frontmatter.icon;
+      return child;
+    });
+    nav.push({ label, children });
+  }
+  return nav;
+}
+function buildRoutes(docs, sectionId) {
+  return docs.map((doc) => ({
+    path: doc.routePath,
+    filePath: doc.filePath,
+    frontmatter: doc.frontmatter,
+    ...sectionId ? { sectionId } : {}
+  }));
+}
+function buildSectionData(section, changelogPath, 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
+      }
+    });
+  }
+  const nav = section.basePath === "/" && customNavigation ? customNavigation : buildNavigation(docs, section.basePath);
+  const navigation = {
+    id: section.id,
+    label: section.label,
+    basePath: section.basePath,
+    navigation: nav
+  };
+  const routes = buildRoutes(docs, section.id);
+  const searchEntries = buildSearchIndex(docs, section.id, section.label);
+  return { section, docs, navigation, routes, searchEntries };
+}
+
+export {
+  scanDocs,
+  buildNavigation,
+  buildRoutes,
+  buildSectionData
+};