@marlinjai/clearify 1.11.1 → 1.12.0

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

@@ -1,10 +1,86 @@
-import { ClearifyConfig, ResolvedSection } from '../types/index.js';
+import { z } from 'zod';
+import { ClearifyConfig, ClearifyDataConfig, ResolvedSection } from '../types/index.js';
 export { defineConfig } from '../types/index.js';
 
+/** Zod schema for clearify.data.json — Tier 1+2 visual-config fields, all optional. */
+declare const ClearifyDataSchema: z.ZodObject<{
+    name: z.ZodOptional<z.ZodString>;
+    siteUrl: z.ZodOptional<z.ZodString>;
+    theme: z.ZodOptional<z.ZodObject<{
+        primaryColor: z.ZodOptional<z.ZodString>;
+        mode: z.ZodOptional<z.ZodEnum<{
+            light: "light";
+            dark: "dark";
+            auto: "auto";
+        }>>;
+    }, z.core.$strip>>;
+    logo: z.ZodOptional<z.ZodObject<{
+        light: z.ZodOptional<z.ZodString>;
+        dark: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    links: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    sections: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        label: z.ZodString;
+        docsDir: z.ZodString;
+        basePath: z.ZodOptional<z.ZodString>;
+        draft: z.ZodOptional<z.ZodBoolean>;
+        sitemap: z.ZodOptional<z.ZodBoolean>;
+        exclude: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        git: z.ZodOptional<z.ZodObject<{
+            repo: z.ZodString;
+            ref: z.ZodOptional<z.ZodString>;
+            path: z.ZodOptional<z.ZodString>;
+            sparse: z.ZodOptional<z.ZodBoolean>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>>;
+    hub: z.ZodOptional<z.ZodObject<{
+        projects: z.ZodDefault<z.ZodArray<z.ZodObject<{
+            name: z.ZodString;
+            description: z.ZodString;
+            href: z.ZodOptional<z.ZodString>;
+            repo: z.ZodOptional<z.ZodString>;
+            status: z.ZodDefault<z.ZodEnum<{
+                active: "active";
+                beta: "beta";
+                planned: "planned";
+                deprecated: "deprecated";
+            }>>;
+            icon: z.ZodOptional<z.ZodString>;
+            tags: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            group: z.ZodOptional<z.ZodString>;
+            mode: z.ZodOptional<z.ZodEnum<{
+                link: "link";
+                embed: "embed";
+                inject: "inject";
+            }>>;
+            git: z.ZodOptional<z.ZodObject<{
+                repo: z.ZodString;
+                ref: z.ZodOptional<z.ZodString>;
+                path: z.ZodOptional<z.ZodString>;
+                sparse: z.ZodOptional<z.ZodBoolean>;
+            }, z.core.$strip>>;
+            embedSections: z.ZodOptional<z.ZodUnion<readonly [z.ZodLiteral<"all">, z.ZodLiteral<"public">, z.ZodArray<z.ZodString>]>>;
+            injectInto: z.ZodOptional<z.ZodString>;
+            docsPath: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>>;
+        scan: z.ZodOptional<z.ZodString>;
+        cacheDir: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+/**
+ * Deep-merge utility where JSON (overlay) values win over base values.
+ * Plain objects merge recursively. Arrays are replaced entirely.
+ * Undefined values in the overlay are skipped.
+ */
+declare function deepMergeJsonWins<T extends Record<string, any>>(base: T, json: Partial<T>): T;
+/** Load and validate clearify.data.json from a project root. Returns `{}` on missing/invalid file. */
+declare function loadDataConfig(root: string): ClearifyDataConfig;
+/** Validate and atomically write clearify.data.json. */
+declare function writeDataConfig(root: string, data: unknown): void;
 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): Promise<ResolvedSection[]>;
 declare function scanHubProjects(config: ClearifyConfig, root: string): Promise<ClearifyConfig>;
 
-export { defaultConfig, loadUserConfig, resolveConfig, resolveSections, scanHubProjects };
+export { ClearifyDataSchema, deepMergeJsonWins, defaultConfig, loadDataConfig, loadUserConfig, resolveConfig, resolveSections, scanHubProjects, writeDataConfig };

package/dist/node/core/config.js

@@ -1,19 +1,27 @@
 import {
+  ClearifyDataSchema,
+  deepMergeJsonWins,
   defaultConfig,
+  loadDataConfig,
   loadUserConfig,
   resolveConfig,
   resolveSections,
-  scanHubProjects
-} from "../chunk-PVTUVUBK.js";
+  scanHubProjects,
+  writeDataConfig
+} from "../chunk-2WLFSQS7.js";
 import "../chunk-AJBCHKBP.js";
 import {
   defineConfig
 } from "../chunk-V7LLYIRO.js";
 export {
+  ClearifyDataSchema,
+  deepMergeJsonWins,
   defaultConfig,
   defineConfig,
+  loadDataConfig,
   loadUserConfig,
   resolveConfig,
   resolveSections,
-  scanHubProjects
+  scanHubProjects,
+  writeDataConfig
 };

package/dist/node/node/build.js

@@ -1,11 +1,11 @@
 import {
   buildSite
-} from "../chunk-JU53JE4P.js";
+} from "../chunk-6YAEHWC7.js";
 import "../chunk-PRTER35L.js";
 import "../chunk-SCZZB7OE.js";
-import "../chunk-PFX7LHRZ.js";
+import "../chunk-XYS5SV4M.js";
 import "../chunk-B2Q23JW3.js";
-import "../chunk-PVTUVUBK.js";
+import "../chunk-2WLFSQS7.js";
 import "../chunk-AJBCHKBP.js";
 import "../chunk-V7LLYIRO.js";
 import "../chunk-QTGT76RY.js";

package/dist/node/node/check.js

@@ -1,8 +1,8 @@
 import {
   checkFrontmatter,
   checkLinks
-} from "../chunk-NGWAMBXS.js";
-import "../chunk-PVTUVUBK.js";
+} from "../chunk-6XHVO5AO.js";
+import "../chunk-2WLFSQS7.js";
 import "../chunk-AJBCHKBP.js";
 import "../chunk-V7LLYIRO.js";
 import "../chunk-QTGT76RY.js";

package/dist/node/node/index.js

@@ -1,13 +1,13 @@
 import {
   buildSite
-} from "../chunk-JU53JE4P.js";
+} from "../chunk-6YAEHWC7.js";
 import {
   remarkMermaidToComponent
 } from "../chunk-PRTER35L.js";
 import "../chunk-SCZZB7OE.js";
 import {
   clearifyPlugin
-} from "../chunk-PFX7LHRZ.js";
+} from "../chunk-XYS5SV4M.js";
 import "../chunk-B2Q23JW3.js";
 import {
   init
@@ -15,11 +15,11 @@ import {
 import {
   checkFrontmatter,
   checkLinks
-} from "../chunk-NGWAMBXS.js";
+} from "../chunk-6XHVO5AO.js";
 import {
   loadUserConfig,
   resolveConfig
-} from "../chunk-PVTUVUBK.js";
+} from "../chunk-2WLFSQS7.js";
 import "../chunk-AJBCHKBP.js";
 import "../chunk-V7LLYIRO.js";
 import "../chunk-QTGT76RY.js";

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

@@ -102,15 +102,36 @@ interface HubProject {
     group?: string;
     hubUrl?: string;
     hubName?: string;
-    mode?: 'link' | 'embed';
+    mode?: 'link' | 'embed' | 'inject';
     git?: RemoteGitSource;
     embedSections?: 'all' | 'public' | string[];
+    injectInto?: string;
+    docsPath?: string;
 }
 interface HubConfig {
     projects: HubProject[];
     scan?: string;
     cacheDir?: string;
 }
+/** Tier 1+2 fields that can live in clearify.data.json for visual editing. */
+interface ClearifyDataConfig {
+    name?: string;
+    siteUrl?: string;
+    theme?: {
+        primaryColor?: string;
+        mode?: 'light' | 'dark' | 'auto';
+    };
+    logo?: {
+        light?: string;
+        dark?: string;
+    };
+    links?: {
+        github?: string;
+        [key: string]: string | undefined;
+    };
+    sections?: SectionConfig[];
+    hub?: HubConfig;
+}
 declare function defineConfig(config: Partial<ClearifyConfig>): Partial<ClearifyConfig>;
 
-export { type ClearifyConfig, type DocCategory, type HubConfig, type HubProject, type NavigationItem, type PageFrontmatter, type RemoteGitSource, type ResolvedSection, type RouteEntry, type SectionConfig, type SectionNavigation, defineConfig };
+export { type ClearifyConfig, type ClearifyDataConfig, 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,8 +1,8 @@
 import {
   clearifyPlugin
-} from "../chunk-PFX7LHRZ.js";
+} from "../chunk-XYS5SV4M.js";
 import "../chunk-B2Q23JW3.js";
-import "../chunk-PVTUVUBK.js";
+import "../chunk-2WLFSQS7.js";
 import "../chunk-AJBCHKBP.js";
 import "../chunk-V7LLYIRO.js";
 import "../chunk-QTGT76RY.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@marlinjai/clearify",
-  "version": "1.11.1",
+  "version": "1.12.0",
   "description": "An open-source documentation site generator. Turn markdown into beautiful docs.",
   "type": "module",
   "bin": {
@@ -14,7 +14,8 @@
     "./config": {
       "types": "./dist/node/core/config.d.ts",
       "import": "./dist/node/core/config.js"
-    }
+    },
+    "./config-schema.json": "./dist/config-schema.json"
   },
   "files": [
     "bin",
@@ -24,6 +25,7 @@
   ],
   "scripts": {
     "build": "tsup",
+    "postbuild": "node scripts/generate-schema.mjs",
     "dev:self": "node bin/clearify.js dev",
     "prepare": "husky",
     "release": "semantic-release"

package/src/client/App.tsx

@@ -7,12 +7,20 @@ import routes from 'virtual:clearify/routes';
 import config from 'virtual:clearify/config';
 // @ts-expect-error virtual module
 import sections from 'virtual:clearify/navigation';
+// @ts-expect-error virtual module
+import adminEnabled from 'virtual:clearify/admin-enabled';
 import { Layout } from '../theme/Layout.js';
 import { Head } from '../theme/Head.js';
 import { NotFound } from '../theme/NotFound.js';
 import { mdxComponents } from '../theme/MDXComponents.js';
 import '../theme/styles/globals.css';
 
+const AdminLayout = React.lazy(() => import('../theme/admin/AdminLayout.js'));
+const AdminDashboard = React.lazy(() => import('../theme/admin/AdminDashboard.js'));
+const ProjectsManager = React.lazy(() => import('../theme/admin/ProjectsManager.js'));
+const SectionsManager = React.lazy(() => import('../theme/admin/SectionsManager.js'));
+const SiteSettings = React.lazy(() => import('../theme/admin/SiteSettings.js'));
+
 interface RouteEntry {
   path: string;
   component?: () => Promise<any>;
@@ -74,24 +82,59 @@ function PageWrapper({ loader, fallbackFrontmatter }: { loader: () => Promise<an
   );
 }
 
+function AdminDisabled() {
+  return (
+    <div style={{ display: 'flex', alignItems: 'center', justifyContent: 'center', minHeight: '100vh', color: 'var(--clearify-text-secondary)', fontFamily: 'var(--font-sans)' }}>
+      Admin panel is only available in dev mode.
+    </div>
+  );
+}
+
 function AppRoutes() {
   return (
-    <Layout config={config} sections={sections}>
-      <Routes>
-        {(routes as RouteEntry[]).map((route) =>
-          route.redirectTo ? (
-            <Route key={route.path} path={route.path} element={<Navigate to={route.redirectTo} replace />} />
-          ) : (
-            <Route
-              key={route.path}
-              path={route.path}
-              element={<PageWrapper loader={route.component!} fallbackFrontmatter={route.frontmatter} />}
-            />
-          )
-        )}
-        <Route path="*" element={<NotFound />} />
-      </Routes>
-    </Layout>
+    <Routes>
+      {/* Admin routes — outside Layout, lazy-loaded */}
+      {adminEnabled ? (
+        <Route
+          path="/admin"
+          element={
+            <React.Suspense fallback={<div style={{ padding: '2rem', color: 'var(--clearify-text-secondary)' }}>Loading...</div>}>
+              <AdminLayout />
+            </React.Suspense>
+          }
+        >
+          <Route index element={<AdminDashboard />} />
+          <Route path="projects" element={<ProjectsManager />} />
+          <Route path="sections" element={<SectionsManager />} />
+          <Route path="settings" element={<SiteSettings />} />
+        </Route>
+      ) : (
+        <Route path="/admin/*" element={<AdminDisabled />} />
+      )}
+
+      {/* Docs routes — wrapped in Layout */}
+      <Route
+        path="*"
+        element={
+          <Layout config={config} sections={sections}>
+            <Routes>
+              {(routes as RouteEntry[]).map((route) =>
+                route.redirectTo ? (
+                  <Route key={route.path} path={route.path} element={<Navigate to={route.redirectTo} replace />} />
+                ) : (
+                  <Route
+                    key={route.path}
+                    path={route.path}
+                    element={<PageWrapper loader={route.component!} fallbackFrontmatter={route.frontmatter} />}
+                  />
+                )
+              )}
+              <Route path="*" element={<NotFound />} />
+            </Routes>
+          </Layout>
+        }
+      />
+    </Routes>
   );
 }
 

package/src/theme/Header.tsx

@@ -2,6 +2,8 @@ import React from 'react';
 import { Link } from 'react-router-dom';
 import { useTheme } from './ThemeProvider.js';
 import { Search } from './Search.js';
+// @ts-expect-error virtual module
+import adminEnabled from 'virtual:clearify/admin-enabled';
 
 interface HeaderProps {
   name: string;
@@ -158,6 +160,36 @@ export function Header({ name, links, logo, onMenuToggle }: HeaderProps) {
           </a>
         )}
 
+        {adminEnabled && (
+          <Link
+            to="/admin"
+            aria-label="Admin panel"
+            style={{
+              display: 'inline-flex',
+              alignItems: 'center',
+              justifyContent: 'center',
+              width: 36,
+              height: 36,
+              borderRadius: 'var(--clearify-radius-sm)',
+              color: 'var(--clearify-text-secondary)',
+              transition: 'color 0.15s, background-color 0.15s',
+            }}
+            onMouseEnter={(e) => {
+              e.currentTarget.style.color = 'var(--clearify-text)';
+              e.currentTarget.style.backgroundColor = 'var(--clearify-bg-secondary)';
+            }}
+            onMouseLeave={(e) => {
+              e.currentTarget.style.color = 'var(--clearify-text-secondary)';
+              e.currentTarget.style.backgroundColor = 'transparent';
+            }}
+          >
+            <svg width="18" height="18" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round">
+              <circle cx="12" cy="12" r="3" />
+              <path d="M19.4 15a1.65 1.65 0 0 0 .33 1.82l.06.06a2 2 0 0 1 0 2.83 2 2 0 0 1-2.83 0l-.06-.06a1.65 1.65 0 0 0-1.82-.33 1.65 1.65 0 0 0-1 1.51V21a2 2 0 0 1-2 2 2 2 0 0 1-2-2v-.09A1.65 1.65 0 0 0 9 19.4a1.65 1.65 0 0 0-1.82.33l-.06.06a2 2 0 0 1-2.83 0 2 2 0 0 1 0-2.83l.06-.06A1.65 1.65 0 0 0 4.68 15a1.65 1.65 0 0 0-1.51-1H3a2 2 0 0 1-2-2 2 2 0 0 1 2-2h.09A1.65 1.65 0 0 0 4.6 9a1.65 1.65 0 0 0-.33-1.82l-.06-.06a2 2 0 0 1 0-2.83 2 2 0 0 1 2.83 0l.06.06A1.65 1.65 0 0 0 9 4.68a1.65 1.65 0 0 0 1-1.51V3a2 2 0 0 1 2-2 2 2 0 0 1 2 2v.09a1.65 1.65 0 0 0 1 1.51 1.65 1.65 0 0 0 1.82-.33l.06-.06a2 2 0 0 1 2.83 0 2 2 0 0 1 0 2.83l-.06.06A1.65 1.65 0 0 0 19.4 9a1.65 1.65 0 0 0 1.51 1H21a2 2 0 0 1 2 2 2 2 0 0 1-2 2h-.09a1.65 1.65 0 0 0-1.51 1z" />
+            </svg>
+          </Link>
+        )}
+
         <button
           onClick={toggleTheme}
           style={{

package/src/theme/admin/AdminDashboard.tsx

@@ -0,0 +1,129 @@
+import React from 'react';
+import { Link } from 'react-router-dom';
+
+const cardStyle: React.CSSProperties = {
+  backgroundColor: 'var(--clearify-surface-elevated)',
+  border: '1px solid var(--clearify-border)',
+  borderRadius: 'var(--clearify-radius)',
+  padding: '1.5rem',
+  boxShadow: 'var(--clearify-shadow)',
+  textDecoration: 'none',
+  color: 'inherit',
+  transition: 'box-shadow 0.15s, border-color 0.15s',
+};
+
+interface DashboardCardProps {
+  title: string;
+  description: string;
+  to: string;
+  icon: React.ReactNode;
+}
+
+function DashboardCard({ title, description, to, icon }: DashboardCardProps) {
+  return (
+    <Link
+      to={to}
+      style={cardStyle}
+      onMouseEnter={(e) => {
+        e.currentTarget.style.boxShadow = 'var(--clearify-shadow-glow)';
+        e.currentTarget.style.borderColor = 'var(--clearify-primary)';
+      }}
+      onMouseLeave={(e) => {
+        e.currentTarget.style.boxShadow = 'var(--clearify-shadow)';
+        e.currentTarget.style.borderColor = 'var(--clearify-border)';
+      }}
+    >
+      <div style={{ display: 'flex', alignItems: 'center', gap: '0.75rem', marginBottom: '0.75rem' }}>
+        <div
+          style={{
+            width: 40,
+            height: 40,
+            borderRadius: 'var(--clearify-radius-sm)',
+            background: 'var(--clearify-primary-soft)',
+            display: 'flex',
+            alignItems: 'center',
+            justifyContent: 'center',
+            color: 'var(--clearify-primary)',
+          }}
+        >
+          {icon}
+        </div>
+        <h3 style={{ fontSize: '1.125rem', fontWeight: 650, color: 'var(--clearify-text)' }}>
+          {title}
+        </h3>
+      </div>
+      <p style={{ fontSize: '0.875rem', color: 'var(--clearify-text-secondary)', lineHeight: 1.5 }}>
+        {description}
+      </p>
+    </Link>
+  );
+}
+
+export function AdminDashboard() {
+  return (
+    <div style={{ padding: '2rem', maxWidth: '64rem', margin: '0 auto' }}>
+      <h1
+        style={{
+          fontSize: '2rem',
+          fontWeight: 800,
+          letterSpacing: '-0.035em',
+          color: 'var(--clearify-text)',
+          marginBottom: '0.5rem',
+        }}
+      >
+        Admin Dashboard
+      </h1>
+      <p style={{ color: 'var(--clearify-text-secondary)', marginBottom: '2rem' }}>
+        Manage your Clearify documentation site.
+      </p>
+
+      <div
+        style={{
+          display: 'grid',
+          gridTemplateColumns: 'repeat(auto-fill, minmax(280px, 1fr))',
+          gap: '1.25rem',
+        }}
+      >
+        <DashboardCard
+          title="Projects"
+          description="Manage hub projects, add or remove project entries."
+          to="/admin/projects"
+          icon={
+            <svg width="20" height="20" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round">
+              <path d="M2 3h6a4 4 0 0 1 4 4v14a3 3 0 0 0-3-3H2z" />
+              <path d="M22 3h-6a4 4 0 0 0-4 4v14a3 3 0 0 1 3-3h7z" />
+            </svg>
+          }
+        />
+        <DashboardCard
+          title="Sections"
+          description="Organize documentation sections and navigation structure."
+          to="/admin/sections"
+          icon={
+            <svg width="20" height="20" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round">
+              <line x1="8" y1="6" x2="21" y2="6" />
+              <line x1="8" y1="12" x2="21" y2="12" />
+              <line x1="8" y1="18" x2="21" y2="18" />
+              <line x1="3" y1="6" x2="3.01" y2="6" />
+              <line x1="3" y1="12" x2="3.01" y2="12" />
+              <line x1="3" y1="18" x2="3.01" y2="18" />
+            </svg>
+          }
+        />
+        <DashboardCard
+          title="Site Settings"
+          description="Configure site name, colors, links, and other settings."
+          to="/admin/settings"
+          icon={
+            <svg width="20" height="20" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round">
+              <circle cx="12" cy="12" r="3" />
+              <path d="M19.4 15a1.65 1.65 0 0 0 .33 1.82l.06.06a2 2 0 0 1 0 2.83 2 2 0 0 1-2.83 0l-.06-.06a1.65 1.65 0 0 0-1.82-.33 1.65 1.65 0 0 0-1 1.51V21a2 2 0 0 1-2 2 2 2 0 0 1-2-2v-.09A1.65 1.65 0 0 0 9 19.4a1.65 1.65 0 0 0-1.82.33l-.06.06a2 2 0 0 1-2.83 0 2 2 0 0 1 0-2.83l.06-.06A1.65 1.65 0 0 0 4.68 15a1.65 1.65 0 0 0-1.51-1H3a2 2 0 0 1-2-2 2 2 0 0 1 2-2h.09A1.65 1.65 0 0 0 4.6 9a1.65 1.65 0 0 0-.33-1.82l-.06-.06a2 2 0 0 1 0-2.83 2 2 0 0 1 2.83 0l.06.06A1.65 1.65 0 0 0 9 4.68a1.65 1.65 0 0 0 1-1.51V3a2 2 0 0 1 2-2 2 2 0 0 1 2 2v.09a1.65 1.65 0 0 0 1 1.51 1.65 1.65 0 0 0 1.82-.33l.06-.06a2 2 0 0 1 2.83 0 2 2 0 0 1 0 2.83l-.06.06A1.65 1.65 0 0 0 19.4 9a1.65 1.65 0 0 0 1.51 1H21a2 2 0 0 1 2 2 2 2 0 0 1-2 2h-.09a1.65 1.65 0 0 0-1.51 1z" />
+            </svg>
+          }
+        />
+      </div>
+    </div>
+  );
+}
+
+export default AdminDashboard;