@marlinjai/clearify 1.8.0 → 1.10.0

package/README.md

@@ -20,19 +20,19 @@ An open-source documentation site generator. Turn markdown into beautiful docs.
 Install Clearify as a dev dependency:
 
 ```bash
-npm install @marlinjai/clearify --save-dev
+pnpm add -D @marlinjai/clearify
 ```
 
 Scaffold your project:
 
 ```bash
-npx clearify init
+pnpm exec clearify init
 ```
 
 Start the dev server:
 
 ```bash
-npx clearify dev
+pnpm exec clearify dev
 ```
 
 Your docs are live at `http://localhost:4747`.

package/dist/node/{chunk-3WWPYCGQ.js → chunk-2RAA6477.js}

@@ -6,10 +6,10 @@ import {
   resolveConfig,
   resolveSections,
   scanHubProjects
-} from "./chunk-YMRRZEYA.js";
+} from "./chunk-PVTUVUBK.js";
 import {
   buildSectionData
-} from "./chunk-6PUBRHS7.js";
+} from "./chunk-QNC5QRIO.js";
 
 // src/vite-plugin/index.ts
 import { resolve } from "path";
@@ -222,7 +222,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();

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-4BOXMNVR.js → chunk-ELRDUSZS.js}

@@ -2,10 +2,10 @@ import {
   loadUserConfig,
   resolveConfig,
   resolveSections
-} from "./chunk-YMRRZEYA.js";
+} from "./chunk-PVTUVUBK.js";
 import {
   scanDocs
-} from "./chunk-6PUBRHS7.js";
+} from "./chunk-QNC5QRIO.js";
 
 // src/node/check.ts
 import { resolve } from "path";
@@ -14,7 +14,7 @@ async function checkLinks() {
   const userRoot = process.cwd();
   const userConfig = await loadUserConfig(userRoot);
   const config = resolveConfig(userConfig, userRoot);
-  const sections = resolveSections(config, userRoot);
+  const sections = await resolveSections(config, userRoot);
   const validRoutes = /* @__PURE__ */ new Set();
   const allDocs = [];
   for (const section of sections) {

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

@@ -1,3 +1,7 @@
+import {
+  resolveRemoteSections
+} from "./chunk-AJBCHKBP.js";
+
 // src/core/config.ts
 import { z } from "zod";
 import { resolve, basename, dirname } from "path";
@@ -15,13 +19,20 @@ var NavigationItemSchema = z.lazy(
     children: z.array(NavigationItemSchema).optional()
   })
 );
+var RemoteGitSourceSchema = z.object({
+  repo: z.string(),
+  ref: z.string().optional(),
+  path: z.string().optional(),
+  sparse: z.boolean().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()
+  exclude: z.array(z.string()).optional(),
+  git: RemoteGitSourceSchema.optional()
 });
 var MermaidConfigSchema = z.object({
   strategy: z.enum(["client", "build"]).default("client")
@@ -38,7 +49,15 @@ var HubProjectSchema = z.object({
   repo: z.string().optional(),
   status: z.enum(["active", "beta", "planned", "deprecated"]).default("active"),
   icon: z.string().optional(),
-  tags: z.array(z.string()).optional()
+  tags: z.array(z.string()).optional(),
+  group: z.string().optional(),
+  mode: z.enum(["link", "embed"]).optional(),
+  git: RemoteGitSourceSchema.optional(),
+  embedSections: z.union([
+    z.literal("all"),
+    z.literal("public"),
+    z.array(z.string())
+  ]).optional()
 });
 var HubProjectPartialSchema = z.object({
   description: z.string(),
@@ -46,11 +65,15 @@ var HubProjectPartialSchema = z.object({
   repo: z.string().optional(),
   status: z.enum(["active", "beta", "planned", "deprecated"]).default("active"),
   icon: z.string().optional(),
-  tags: z.array(z.string()).optional()
+  tags: z.array(z.string()).optional(),
+  group: z.string().optional(),
+  hubUrl: z.string().optional(),
+  hubName: z.string().optional()
 }).optional();
 var HubConfigSchema = z.object({
   projects: z.array(HubProjectSchema).default([]),
-  scan: z.string().optional()
+  scan: z.string().optional(),
+  cacheDir: z.string().optional()
 }).optional();
 var ClearifyConfigSchema = z.object({
   name: z.string().default("Documentation"),
@@ -178,18 +201,25 @@ function resolveConfig(userConfig = {}, root) {
 function slugify(str) {
   return str.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "");
 }
-function resolveSections(config, root) {
+async function resolveSections(config, root) {
   if (config.sections && config.sections.length > 0) {
-    const sections = config.sections.map((s, i) => {
+    const hasRemote = config.sections.some((s) => s.git);
+    let resolvedInputs = config.sections;
+    if (hasRemote) {
+      const cacheDir = resolve(root, "node_modules/.cache/clearify-remote");
+      resolvedInputs = await resolveRemoteSections(config.sections, cacheDir);
+    }
+    const sections = resolvedInputs.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 ?? []];
+      const docsDir = s.docsDir.startsWith("/") ? s.docsDir : resolve(root, s.docsDir);
       return {
         id,
         label: s.label,
-        docsDir: resolve(root, s.docsDir),
+        docsDir,
         basePath,
         draft,
         sitemap,
@@ -218,36 +248,82 @@ function resolveSections(config, root) {
   ];
 }
 async function scanHubProjects(config, root) {
-  if (!config.hub?.scan) return config;
-  const { globbySync } = await import("globby");
-  const pattern = config.hub.scan;
-  const configPaths = globbySync(pattern, { cwd: root, absolute: true });
+  if (!config.hub?.scan && !config.hub?.projects?.some((p) => p.mode === "embed")) {
+    return config;
+  }
   const scannedProjects = [];
-  for (const configPath of configPaths) {
-    try {
-      const childConfig = await loadUserConfig(dirname(configPath));
-      if (!childConfig.hubProject) continue;
-      const name = childConfig.name ?? basename(dirname(configPath));
-      const hp = childConfig.hubProject;
-      scannedProjects.push({
-        name,
-        description: hp.description,
-        href: hp.href ?? childConfig.siteUrl,
-        repo: hp.repo,
-        status: hp.status,
-        icon: hp.icon,
-        tags: hp.tags
-      });
-    } catch {
+  if (config.hub?.scan) {
+    const { globbySync } = await import("globby");
+    const pattern = config.hub.scan;
+    const configPaths = globbySync(pattern, { cwd: root, absolute: true });
+    for (const configPath of configPaths) {
+      try {
+        const childConfig = await loadUserConfig(dirname(configPath));
+        if (!childConfig.hubProject) continue;
+        const name = childConfig.name ?? basename(dirname(configPath));
+        const hp = childConfig.hubProject;
+        scannedProjects.push({
+          name,
+          description: hp.description,
+          href: hp.href ?? childConfig.siteUrl,
+          repo: hp.repo,
+          status: hp.status,
+          icon: hp.icon,
+          tags: hp.tags,
+          group: hp.group
+        });
+      } catch {
+      }
     }
   }
-  const manualNames = new Set((config.hub.projects ?? []).map((p) => p.name));
+  const manualNames = new Set((config.hub?.projects ?? []).map((p) => p.name));
   const merged = [
     ...scannedProjects.filter((p) => !manualNames.has(p.name)),
-    ...config.hub.projects ?? []
+    ...config.hub?.projects ?? []
   ];
+  const embedSections = [];
+  for (const project of merged) {
+    if (project.mode !== "embed" || !project.git) continue;
+    const cacheDir = config.hub?.cacheDir ? resolve(root, config.hub.cacheDir) : resolve(root, "node_modules/.cache/clearify-remote");
+    try {
+      const { resolveRemoteSource } = await import("./core/remote.js");
+      const { localPath } = await resolveRemoteSource(project.git, cacheDir);
+      const remoteConfig = await loadUserConfig(localPath);
+      const remoteSections = remoteConfig.sections ?? [
+        { label: remoteConfig.name ?? project.name, docsDir: remoteConfig.docsDir ?? "./docs" }
+      ];
+      const filter = project.embedSections ?? "public";
+      const filtered = remoteSections.filter((s) => {
+        if (filter === "all") return true;
+        if (filter === "public") return !s.draft;
+        if (Array.isArray(filter)) return filter.includes(s.label);
+        return true;
+      });
+      for (const s of filtered) {
+        const docsDir = s.docsDir.startsWith("/") ? s.docsDir : resolve(localPath, s.docsDir);
+        const label = s.label === "Documentation" ? project.name : s.label;
+        const id = slugify(label);
+        embedSections.push({
+          label,
+          docsDir,
+          basePath: s.basePath ?? "/" + id,
+          draft: s.draft,
+          sitemap: s.sitemap,
+          exclude: s.exclude
+        });
+      }
+      console.log(`  Hub embed "${project.name}": ${filtered.length} sections pulled`);
+    } catch (err) {
+      console.warn(
+        `  \u26A0 Hub embed "${project.name}" failed:`,
+        err instanceof Error ? err.message : err
+      );
+    }
+  }
+  const finalSections = [...config.sections ?? [], ...embedSections];
   return {
     ...config,
+    ...embedSections.length > 0 ? { sections: finalSections } : {},
     hub: {
       ...config.hub,
       projects: merged

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

@@ -47,9 +47,20 @@ function scanDocs(docsDir, exclude = [], basePath = "/") {
 }
 function buildNavigation(docs, basePath = "/") {
   const rootDir = basePath === "/" ? "/" : basePath.replace(/\/$/, "");
-  const groups = /* @__PURE__ */ new Map();
+  const indexPages = /* @__PURE__ */ new Map();
+  const nonIndexDocs = [];
   for (const doc of docs) {
     if (doc.routePath === rootDir || doc.routePath === "/") continue;
+    const parentDir = dirname(doc.routePath);
+    const fileName = basename(doc.filePath, extname(doc.filePath));
+    if (fileName === "index") {
+      indexPages.set(doc.routePath, doc);
+    } else {
+      nonIndexDocs.push(doc);
+    }
+  }
+  const groups = /* @__PURE__ */ new Map();
+  for (const doc of nonIndexDocs) {
     const dir = dirname(doc.routePath);
     if (!groups.has(dir)) groups.set(dir, []);
     groups.get(dir).push(doc);
@@ -62,25 +73,51 @@ function buildNavigation(docs, basePath = "/") {
       return a.routePath.localeCompare(b.routePath);
     });
   }
-  const nav = [];
-  const rootFiles = groups.get(rootDir) ?? [];
-  for (const doc of rootFiles) {
-    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;
+  function buildGroupChildren(parentDir) {
+    const items = [];
+    const directFiles = groups.get(parentDir) ?? [];
+    for (const doc of directFiles) {
+      const item = { label: doc.frontmatter.title, path: doc.routePath };
+      if (doc.frontmatter.icon) item.icon = doc.frontmatter.icon;
+      items.push(item);
+    }
+    const childDirs = /* @__PURE__ */ new Set();
+    for (const dir of groups.keys()) {
+      if (dir !== parentDir && dirname(dir) === parentDir) {
+        childDirs.add(dir);
+      }
+    }
+    for (const indexPath of indexPages.keys()) {
+      const dir = indexPath;
+      if (dirname(dir) === parentDir && !childDirs.has(dir)) {
+        childDirs.add(dir);
+      }
+    }
+    const sortedChildDirs = [...childDirs].sort((a, b) => {
+      const indexA = indexPages.get(a);
+      const indexB = indexPages.get(b);
+      const orderA = indexA?.frontmatter.order ?? 999;
+      const orderB = indexB?.frontmatter.order ?? 999;
+      if (orderA !== orderB) return orderA - orderB;
+      return a.localeCompare(b);
     });
-    nav.push({ label, children });
+    for (const childDir of sortedChildDirs) {
+      const indexPage = indexPages.get(childDir);
+      const label = indexPage?.frontmatter.title ?? toTitleCase(basename(childDir));
+      const children = buildGroupChildren(childDir);
+      if (children.length > 0) {
+        const group = { label, children };
+        if (indexPage?.frontmatter.icon) group.icon = indexPage.frontmatter.icon;
+        items.push(group);
+      } else if (indexPage) {
+        const item = { label, path: indexPage.routePath };
+        if (indexPage.frontmatter.icon) item.icon = indexPage.frontmatter.icon;
+        items.push(item);
+      }
+    }
+    return items;
   }
-  return nav;
+  return buildGroupChildren(rootDir);
 }
 function buildRoutes(docs, sectionId) {
   return docs.map((doc) => ({

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

@@ -8,15 +8,15 @@ import {
 } from "./chunk-SCZZB7OE.js";
 import {
   clearifyPlugin
-} from "./chunk-3WWPYCGQ.js";
+} from "./chunk-2RAA6477.js";
 import {
   loadUserConfig,
   resolveConfig,
   resolveSections
-} from "./chunk-YMRRZEYA.js";
+} from "./chunk-PVTUVUBK.js";
 import {
   buildSectionData
-} from "./chunk-6PUBRHS7.js";
+} from "./chunk-QNC5QRIO.js";
 
 // src/node/build.ts
 import { build as viteBuild } from "vite";
@@ -140,7 +140,7 @@ 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 sectionDataList = productionSections.map(

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

@@ -4,7 +4,7 @@ export { defineConfig } from '../types/index.js';
 declare const defaultConfig: ClearifyConfig;
 declare function loadUserConfig(root: string): Promise<Partial<ClearifyConfig>>;
 declare function resolveConfig(userConfig?: Partial<ClearifyConfig>, root?: string): ClearifyConfig;
-declare function resolveSections(config: ClearifyConfig, root: string): ResolvedSection[];
+declare function resolveSections(config: ClearifyConfig, root: string): Promise<ResolvedSection[]>;
 declare function scanHubProjects(config: ClearifyConfig, root: string): Promise<ClearifyConfig>;
 
 export { defaultConfig, loadUserConfig, resolveConfig, resolveSections, scanHubProjects };

package/dist/node/core/config.js

@@ -4,7 +4,8 @@ import {
   resolveConfig,
   resolveSections,
   scanHubProjects
-} from "../chunk-YMRRZEYA.js";
+} from "../chunk-PVTUVUBK.js";
+import "../chunk-AJBCHKBP.js";
 import {
   defineConfig
 } from "../chunk-V7LLYIRO.js";

package/dist/node/core/navigation.js

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

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

@@ -0,0 +1,18 @@
+import { SectionConfig, RemoteGitSource } from '../types/index.js';
+
+interface ResolvedRemote {
+    localPath: string;
+    resolvedCommit: string;
+    cached: boolean;
+}
+/**
+ * Clone or update a git repo into the cache directory.
+ */
+declare function resolveRemoteSource(source: RemoteGitSource, cacheDir: string): Promise<ResolvedRemote>;
+/**
+ * For each section with a `git` source, clone/update the repo and rewrite
+ * `docsDir` to the absolute path inside the cached clone.
+ */
+declare function resolveRemoteSections(sections: SectionConfig[], cacheDir: string): Promise<SectionConfig[]>;
+
+export { resolveRemoteSections, resolveRemoteSource };

package/dist/node/core/remote.js

@@ -0,0 +1,8 @@
+import {
+  resolveRemoteSections,
+  resolveRemoteSource
+} from "../chunk-AJBCHKBP.js";
+export {
+  resolveRemoteSections,
+  resolveRemoteSource
+};

package/dist/node/node/build.js

@@ -1,13 +1,14 @@
 import {
   buildSite
-} from "../chunk-W3MZOFJQ.js";
+} from "../chunk-ZNURJXMI.js";
 import "../chunk-PRTER35L.js";
 import "../chunk-SCZZB7OE.js";
-import "../chunk-3WWPYCGQ.js";
+import "../chunk-2RAA6477.js";
 import "../chunk-B2Q23JW3.js";
-import "../chunk-YMRRZEYA.js";
+import "../chunk-PVTUVUBK.js";
+import "../chunk-AJBCHKBP.js";
 import "../chunk-V7LLYIRO.js";
-import "../chunk-6PUBRHS7.js";
+import "../chunk-QNC5QRIO.js";
 import "../chunk-5TD7NQIW.js";
 export {
   buildSite

package/dist/node/node/check.js

@@ -1,9 +1,10 @@
 import {
   checkLinks
-} from "../chunk-4BOXMNVR.js";
-import "../chunk-YMRRZEYA.js";
+} from "../chunk-ELRDUSZS.js";
+import "../chunk-PVTUVUBK.js";
+import "../chunk-AJBCHKBP.js";
 import "../chunk-V7LLYIRO.js";
-import "../chunk-6PUBRHS7.js";
+import "../chunk-QNC5QRIO.js";
 import "../chunk-5TD7NQIW.js";
 export {
   checkLinks

package/dist/node/node/index.js

@@ -1,26 +1,27 @@
 import {
   buildSite
-} from "../chunk-W3MZOFJQ.js";
+} from "../chunk-ZNURJXMI.js";
 import {
   remarkMermaidToComponent
 } from "../chunk-PRTER35L.js";
 import "../chunk-SCZZB7OE.js";
 import {
   clearifyPlugin
-} from "../chunk-3WWPYCGQ.js";
+} from "../chunk-2RAA6477.js";
 import "../chunk-B2Q23JW3.js";
 import {
   init
 } from "../chunk-QIAMD2Q6.js";
 import {
   checkLinks
-} from "../chunk-4BOXMNVR.js";
+} from "../chunk-ELRDUSZS.js";
 import {
   loadUserConfig,
   resolveConfig
-} from "../chunk-YMRRZEYA.js";
+} from "../chunk-PVTUVUBK.js";
+import "../chunk-AJBCHKBP.js";
 import "../chunk-V7LLYIRO.js";
-import "../chunk-6PUBRHS7.js";
+import "../chunk-QNC5QRIO.js";
 import "../chunk-5TD7NQIW.js";
 
 // src/node/index.ts

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

@@ -1,3 +1,9 @@
+interface RemoteGitSource {
+    repo: string;
+    ref?: string;
+    path?: string;
+    sparse?: boolean;
+}
 interface SectionConfig {
     label: string;
     docsDir: string;
@@ -5,6 +11,7 @@ interface SectionConfig {
     draft?: boolean;
     sitemap?: boolean;
     exclude?: string[];
+    git?: RemoteGitSource;
 }
 interface ResolvedSection {
     id: string;
@@ -85,11 +92,18 @@ interface HubProject {
     status?: 'active' | 'beta' | 'planned' | 'deprecated';
     icon?: string;
     tags?: string[];
+    group?: string;
+    hubUrl?: string;
+    hubName?: string;
+    mode?: 'link' | 'embed';
+    git?: RemoteGitSource;
+    embedSections?: 'all' | 'public' | string[];
 }
 interface HubConfig {
     projects: HubProject[];
     scan?: string;
+    cacheDir?: string;
 }
 declare function defineConfig(config: Partial<ClearifyConfig>): Partial<ClearifyConfig>;
 
-export { type ClearifyConfig, type HubConfig, type HubProject, type NavigationItem, type PageFrontmatter, type ResolvedSection, type RouteEntry, type SectionConfig, type SectionNavigation, defineConfig };
+export { type ClearifyConfig, 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,10 +1,11 @@
 import {
   clearifyPlugin
-} from "../chunk-3WWPYCGQ.js";
+} from "../chunk-2RAA6477.js";
 import "../chunk-B2Q23JW3.js";
-import "../chunk-YMRRZEYA.js";
+import "../chunk-PVTUVUBK.js";
+import "../chunk-AJBCHKBP.js";
 import "../chunk-V7LLYIRO.js";
-import "../chunk-6PUBRHS7.js";
+import "../chunk-QNC5QRIO.js";
 import "../chunk-5TD7NQIW.js";
 export {
   clearifyPlugin

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@marlinjai/clearify",
-  "version": "1.8.0",
+  "version": "1.10.0",
   "description": "An open-source documentation site generator. Turn markdown into beautiful docs.",
   "type": "module",
   "bin": {
@@ -22,6 +22,10 @@
     "src/client",
     "src/theme"
   ],
+  "scripts": {
+    "build": "tsup",
+    "dev:self": "node bin/clearify.js dev"
+  },
   "dependencies": {
     "@mdx-js/react": "^3.1.1",
     "@mdx-js/rollup": "^3.1.1",
@@ -68,6 +72,7 @@
     "tsup": "^8.3.6",
     "typescript": "^5.7.3"
   },
+  "packageManager": "pnpm@9.15.0",
   "license": "MIT",
   "author": "MarlinJai",
   "repository": {
@@ -88,9 +93,5 @@
     "react",
     "mermaid",
     "openapi"
-  ],
-  "scripts": {
-    "build": "tsup",
-    "dev:self": "node bin/clearify.js dev"
-  }
-}
+  ]
+}

package/src/theme/Layout.tsx

@@ -33,6 +33,7 @@ export function Layout({ config, sections, children }: LayoutProps) {
             sections={sections}
             open={sidebarOpen}
             onClose={() => setSidebarOpen(false)}
+            hubProject={config.hubProject}
           />
           <Content>{children}</Content>
           <TableOfContents />

package/src/theme/Sidebar.tsx

@@ -1,12 +1,13 @@
 import React, { useState, useEffect, useRef } from 'react';
 import { Link, useLocation, useNavigate } from 'react-router-dom';
 import clsx from 'clsx';
-import type { NavigationItem, SectionNavigation } from '../types/index.js';
+import type { NavigationItem, SectionNavigation, HubProject } from '../types/index.js';
 
 interface SidebarProps {
   sections: SectionNavigation[];
   open: boolean;
   onClose: () => void;
+  hubProject?: Omit<HubProject, 'name'>;
 }
 
 function findActiveSection(pathname: string, sections: SectionNavigation[]): string {
@@ -103,7 +104,7 @@ function SectionSwitcher({
   );
 }
 
-export function Sidebar({ sections, open, onClose }: SidebarProps) {
+export function Sidebar({ sections, open, onClose, hubProject }: SidebarProps) {
   const location = useLocation();
   const navigate = useNavigate();
 
@@ -246,6 +247,37 @@ export function Sidebar({ sections, open, onClose }: SidebarProps) {
         }}
         className={clsx('clearify-sidebar', open && 'clearify-sidebar-open')}
       >
+        {hubProject?.hubUrl && (
+          <a
+            href={hubProject.hubUrl}
+            style={{
+              display: 'flex',
+              alignItems: 'center',
+              gap: '0.375rem',
+              padding: '0.375rem 0.75rem',
+              margin: '0 0.5rem 0.5rem',
+              fontSize: '0.75rem',
+              fontWeight: 500,
+              color: 'var(--clearify-text-tertiary)',
+              textDecoration: 'none',
+              borderRadius: 'var(--clearify-radius-sm)',
+              transition: 'color 0.15s, background-color 0.15s',
+            }}
+            onMouseEnter={(e) => {
+              e.currentTarget.style.color = 'var(--clearify-primary)';
+              e.currentTarget.style.backgroundColor = 'var(--clearify-primary-soft)';
+            }}
+            onMouseLeave={(e) => {
+              e.currentTarget.style.color = 'var(--clearify-text-tertiary)';
+              e.currentTarget.style.backgroundColor = 'transparent';
+            }}
+          >
+            <svg width="12" height="12" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round">
+              <polyline points="15 18 9 12 15 6" />
+            </svg>
+            {hubProject.hubName ?? 'Hub'}
+          </a>
+        )}
         {showSwitcher && (
           <SectionSwitcher
             sections={sections}

package/src/theme/components/ProjectGrid.tsx

@@ -1,52 +1,142 @@
 import React from 'react';
 import hub from 'virtual:clearify/hub';
 import { ProjectCard } from './ProjectCard.js';
+import type { HubProject } from '../../types/index.js';
 
 interface ProjectGridProps {
   cols?: number;
   children?: React.ReactNode;
 }
 
-export function ProjectGrid({ cols = 3, children }: ProjectGridProps) {
-  const hasChildren = React.Children.count(children) > 0;
-
+function ProjectGridInner({ cols, projects }: { cols: number; projects: HubProject[] }) {
   return (
     <div
       style={{
         display: 'grid',
         gridTemplateColumns: `repeat(${cols}, 1fr)`,
         gap: '0.875rem',
-        marginBottom: '1.5rem',
       }}
       className="clearify-project-grid"
     >
-      {hasChildren
-        ? children
-        : hub?.projects.map((project) => (
-            <ProjectCard
-              key={project.name}
-              name={project.name}
-              description={project.description}
-              href={project.href}
-              repo={project.repo}
-              status={project.status}
-              icon={project.icon}
-              tags={project.tags}
-            />
-          ))}
-
-      <style>{`
-        @media (max-width: 900px) {
-          .clearify-project-grid {
-            grid-template-columns: repeat(2, 1fr) !important;
-          }
-        }
-        @media (max-width: 640px) {
-          .clearify-project-grid {
-            grid-template-columns: 1fr !important;
-          }
-        }
-      `}</style>
+      {projects.map((project) => (
+        <ProjectCard
+          key={project.name}
+          name={project.name}
+          description={project.description}
+          href={project.href}
+          repo={project.repo}
+          status={project.status}
+          icon={project.icon}
+          tags={project.tags}
+        />
+      ))}
     </div>
   );
 }
+
+export function ProjectGrid({ cols = 3, children }: ProjectGridProps) {
+  const hasChildren = React.Children.count(children) > 0;
+
+  if (hasChildren) {
+    return (
+      <div
+        style={{
+          display: 'grid',
+          gridTemplateColumns: `repeat(${cols}, 1fr)`,
+          gap: '0.875rem',
+          marginBottom: '1.5rem',
+        }}
+        className="clearify-project-grid"
+      >
+        {children}
+        <style>{gridResponsiveStyles}</style>
+      </div>
+    );
+  }
+
+  const projects: HubProject[] = hub?.projects ?? [];
+  const hasGroups = projects.some((p) => p.group);
+
+  if (!hasGroups) {
+    return (
+      <div style={{ marginBottom: '1.5rem' }}>
+        <ProjectGridInner cols={cols} projects={projects} />
+        <style>{gridResponsiveStyles}</style>
+      </div>
+    );
+  }
+
+  // Group projects by their group field, preserving insertion order
+  const groupOrder: string[] = [];
+  const grouped: Record<string, HubProject[]> = {};
+  const ungrouped: HubProject[] = [];
+
+  for (const project of projects) {
+    if (project.group) {
+      if (!grouped[project.group]) {
+        grouped[project.group] = [];
+        groupOrder.push(project.group);
+      }
+      grouped[project.group].push(project);
+    } else {
+      ungrouped.push(project);
+    }
+  }
+
+  return (
+    <div style={{ marginBottom: '1.5rem' }}>
+      {groupOrder.map((groupName) => (
+        <div key={groupName} style={{ marginBottom: '1.5rem' }}>
+          <h2
+            style={{
+              fontSize: '1.25rem',
+              fontWeight: 600,
+              marginBottom: '0.75rem',
+              marginTop: 0,
+              color: 'var(--clearify-text)',
+              letterSpacing: '-0.01em',
+            }}
+          >
+            {groupName}
+          </h2>
+          <ProjectGridInner cols={cols} projects={grouped[groupName]} />
+        </div>
+      ))}
+
+      {ungrouped.length > 0 && (
+        <div style={{ marginBottom: '1.5rem' }}>
+          {groupOrder.length > 0 && (
+            <h2
+              style={{
+                fontSize: '1.25rem',
+                fontWeight: 600,
+                marginBottom: '0.75rem',
+                marginTop: 0,
+                color: 'var(--clearify-text)',
+                letterSpacing: '-0.01em',
+              }}
+            >
+              Other Projects
+            </h2>
+          )}
+          <ProjectGridInner cols={cols} projects={ungrouped} />
+        </div>
+      )}
+
+      <style>{gridResponsiveStyles}</style>
+    </div>
+  );
+}
+
+const gridResponsiveStyles = `
+  @media (max-width: 900px) {
+    .clearify-project-grid {
+      grid-template-columns: repeat(2, 1fr) !important;
+    }
+  }
+  @media (max-width: 640px) {
+    .clearify-project-grid {
+      grid-template-columns: 1fr !important;
+    }
+  }
+`;