@marlinjai/clearify 1.5.0

package/package.json

@@ -0,0 +1,94 @@
+{
+  "name": "@marlinjai/clearify",
+  "version": "1.5.0",
+  "description": "An open-source documentation site generator. Turn markdown into beautiful docs.",
+  "type": "module",
+  "bin": {
+    "clearify": "./bin/clearify.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/node/types/index.d.ts",
+      "import": "./dist/node/types/index.js"
+    },
+    "./config": {
+      "types": "./dist/node/core/config.d.ts",
+      "import": "./dist/node/core/config.js"
+    }
+  },
+  "files": [
+    "bin",
+    "dist",
+    "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",
+    "@scalar/api-reference-react": "^0.8.52",
+    "@shikijs/rehype": "^3.22.0",
+    "@tailwindcss/typography": "^0.5.19",
+    "@tailwindcss/vite": "^4.1.18",
+    "@vitejs/plugin-react": "^4.3.4",
+    "autoprefixer": "^10.4.24",
+    "cac": "^6.7.14",
+    "clsx": "^2.1.1",
+    "flexsearch": "^0.8.212",
+    "globby": "^16.1.0",
+    "gray-matter": "^4.0.3",
+    "mermaid": "^11.0.0",
+    "postcss": "^8.5.6",
+    "react-router-dom": "^7.13.0",
+    "remark-frontmatter": "^5.0.0",
+    "remark-gfm": "^4.0.1",
+    "remark-mdx-frontmatter": "^5.2.0",
+    "shiki": "^3.22.0",
+    "tailwindcss": "^4.1.18",
+    "unist-util-visit": "^5.0.0",
+    "vite": "^6.1.0",
+    "zod": "^4.3.6"
+  },
+  "peerDependencies": {
+    "puppeteer": ">=22.0.0",
+    "react": "^18.0.0 || ^19.0.0",
+    "react-dom": "^18.0.0 || ^19.0.0"
+  },
+  "peerDependenciesMeta": {
+    "puppeteer": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@types/node": "^25.2.2",
+    "@types/react": "^18.3.18",
+    "@types/react-dom": "^18.3.5",
+    "puppeteer": "^24.37.2",
+    "tsup": "^8.3.6",
+    "typescript": "^5.7.3"
+  },
+  "license": "MIT",
+  "author": "MarlinJai",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/marlinjai/clearify.git"
+  },
+  "homepage": "https://github.com/marlinjai/clearify",
+  "bugs": {
+    "url": "https://github.com/marlinjai/clearify/issues"
+  },
+  "keywords": [
+    "documentation",
+    "docs",
+    "markdown",
+    "mdx",
+    "static-site-generator",
+    "vite",
+    "react",
+    "mermaid",
+    "openapi"
+  ]
+}

package/src/client/App.tsx

@@ -0,0 +1,101 @@
+import React, { useEffect, useState, useRef } from 'react';
+import { BrowserRouter, Routes, Route, useLocation } from 'react-router-dom';
+import { MDXProvider } from '@mdx-js/react';
+// @ts-expect-error virtual module
+import routes from 'virtual:clearify/routes';
+// @ts-expect-error virtual module
+import config from 'virtual:clearify/config';
+// @ts-expect-error virtual module
+import sections from 'virtual:clearify/navigation';
+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';
+
+interface RouteEntry {
+  path: string;
+  component: () => Promise<any>;
+  frontmatter: { title?: string; description?: string };
+}
+
+function PageWrapper({ loader, fallbackFrontmatter }: { loader: () => Promise<any>; fallbackFrontmatter: any }) {
+  const location = useLocation();
+  const [page, setPage] = useState<{ Component: React.ComponentType; fm: any } | null>(null);
+  const isInitialRender = useRef(true);
+
+  useEffect(() => {
+    let cancelled = false;
+
+    // On SSR-hydrated pages, the initial route's content is already visible.
+    // Still load the module so subsequent SPA navigations work, but don't
+    // flash "Loading..." by clearing state only on navigation changes.
+    if (isInitialRender.current) {
+      isInitialRender.current = false;
+      // Load eagerly but don't clear existing DOM content
+      loader().then((mod) => {
+        if (cancelled) return;
+        setPage({
+          Component: mod.default,
+          fm: mod.frontmatter ?? fallbackFrontmatter,
+        });
+      });
+      return () => { cancelled = true; };
+    }
+
+    setPage(null);
+    loader().then((mod) => {
+      if (cancelled) return;
+      setPage({
+        Component: mod.default,
+        fm: mod.frontmatter ?? fallbackFrontmatter,
+      });
+    });
+    return () => { cancelled = true; };
+  }, [location.pathname]);
+
+  if (!page) {
+    // If we're hydrating an SSR page, don't show loading — the HTML is already there.
+    // The browser will display the server-rendered content until React hydrates.
+    const isSSR = typeof document !== 'undefined' && document.getElementById('root')?.dataset.clearifySsr;
+    if (isSSR && isInitialRender.current) {
+      return null;
+    }
+    return <div style={{ padding: '2rem', color: 'var(--clearify-text-secondary)' }}>Loading...</div>;
+  }
+
+  const { Component, fm } = page;
+  return (
+    <article>
+      <Head title={fm?.title} description={fm?.description} url={location.pathname} />
+      <Component />
+    </article>
+  );
+}
+
+function AppRoutes() {
+  return (
+    <Layout config={config} sections={sections}>
+      <Routes>
+        {(routes as RouteEntry[]).map((route) => (
+          <Route
+            key={route.path}
+            path={route.path}
+            element={<PageWrapper loader={route.component} fallbackFrontmatter={route.frontmatter} />}
+          />
+        ))}
+        <Route path="*" element={<NotFound />} />
+      </Routes>
+    </Layout>
+  );
+}
+
+export function App() {
+  return (
+    <BrowserRouter>
+      <MDXProvider components={mdxComponents}>
+        <AppRoutes />
+      </MDXProvider>
+    </BrowserRouter>
+  );
+}

package/src/client/Page.tsx

@@ -0,0 +1,15 @@
+import React from 'react';
+
+interface PageProps {
+  content: React.ComponentType;
+  frontmatter: { title?: string; description?: string };
+}
+
+export function Page({ content: Content, frontmatter }: PageProps) {
+  return (
+    <article>
+      {frontmatter.title && <h1>{frontmatter.title}</h1>}
+      <Content />
+    </article>
+  );
+}

package/src/client/entry-server.tsx

@@ -0,0 +1,79 @@
+import React from 'react';
+import { renderToString } from 'react-dom/server';
+import { MemoryRouter, Routes, Route } from 'react-router';
+import { MDXProvider } from '@mdx-js/react';
+// @ts-expect-error virtual module
+import routes from 'virtual:clearify/routes';
+// @ts-expect-error virtual module
+import config from 'virtual:clearify/config';
+// @ts-expect-error virtual module
+import sections from 'virtual:clearify/navigation';
+import { Layout } from '../theme/Layout.js';
+import { Head } from '../theme/Head.js';
+import { mdxComponents } from '../theme/MDXComponents.js';
+import { HeadProvider, type HeadData } from '../theme/HeadContext.js';
+import '../theme/styles/globals.css';
+
+interface RouteEntry {
+  path: string;
+  component: () => Promise<any>;
+  frontmatter: { title?: string; description?: string };
+}
+
+export async function render(url: string): Promise<{ html: string; head: HeadData }> {
+  // Find the matching route and pre-load its module
+  const allRoutes = routes as RouteEntry[];
+  // Prefer exact match over catch-all
+  const matchedRoute =
+    allRoutes.find((r) => r.path === url) ??
+    allRoutes.find((r) => {
+      if (!r.path.endsWith('/*')) return false;
+      const base = r.path.slice(0, -2);
+      return url === base || url.startsWith(base + '/');
+    });
+
+  let Component: React.ComponentType = () => null;
+  let fm: { title?: string; description?: string } = {};
+
+  if (matchedRoute) {
+    const mod = await matchedRoute.component();
+    Component = mod.default;
+    fm = mod.frontmatter ?? matchedRoute.frontmatter;
+  }
+
+  // Collect head data during render
+  let headData: HeadData = {
+    title: config.name,
+    description: `${config.name} documentation`,
+    url,
+    siteName: config.name,
+  };
+
+  const onCollect = (data: HeadData) => {
+    headData = data;
+  };
+
+  const html = renderToString(
+    <HeadProvider onCollect={onCollect}>
+      <MemoryRouter initialEntries={[url]}>
+        <MDXProvider components={mdxComponents}>
+          <Layout config={config} sections={sections}>
+            <Routes>
+              <Route
+                path={matchedRoute?.path ?? url}
+                element={
+                  <article>
+                    <Head title={fm.title} description={fm.description} url={url} />
+                    <Component />
+                  </article>
+                }
+              />
+            </Routes>
+          </Layout>
+        </MDXProvider>
+      </MemoryRouter>
+    </HeadProvider>
+  );
+
+  return { html, head: headData };
+}

package/src/client/index.html

@@ -0,0 +1,18 @@
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <meta name="generator" content="Clearify" />
+    <!--clearify-head-->
+    <link rel="preconnect" href="https://fonts.googleapis.com" />
+    <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
+    <link href="https://fonts.googleapis.com/css2?family=Plus+Jakarta+Sans:ital,wght@0,300;0,400;0,500;0,600;0,700;0,800;1,400;1,500&family=JetBrains+Mono:wght@400;500;600&display=swap" rel="stylesheet" />
+    <link rel="icon" type="image/svg+xml" href="data:image/svg+xml,<svg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 100 100'><text y='.9em' font-size='90'>📖</text></svg>" />
+    <title>Documentation</title>
+  </head>
+  <body>
+    <div id="root"><!--clearify-outlet--></div>
+    <script type="module" src="./main.tsx"></script>
+  </body>
+</html>

package/src/client/main.tsx

@@ -0,0 +1,11 @@
+import React from 'react';
+import { hydrateRoot, createRoot } from 'react-dom/client';
+import { App } from './App.js';
+
+const container = document.getElementById('root')!;
+
+if (container.dataset.clearifySsr) {
+  hydrateRoot(container, <App />);
+} else {
+  createRoot(container).render(<App />);
+}

package/src/theme/CodeBlock.tsx

@@ -0,0 +1,103 @@
+import React, { useState, useRef } from 'react';
+
+export function CodeBlock({ children, className, ...props }: React.HTMLAttributes<HTMLPreElement>) {
+  const [copied, setCopied] = useState(false);
+  const preRef = useRef<HTMLPreElement>(null);
+
+  const lang = className
+    ?.split(' ')
+    .find((c) => c.startsWith('language-'))
+    ?.replace('language-', '') ?? '';
+
+  const handleCopy = async () => {
+    const text = preRef.current?.textContent ?? '';
+    await navigator.clipboard.writeText(text);
+    setCopied(true);
+    setTimeout(() => setCopied(false), 2000);
+  };
+
+  return (
+    <div style={{ position: 'relative', marginBottom: '1.25rem' }} className="clearify-codeblock">
+      {lang && (
+        <div
+          style={{
+            position: 'absolute',
+            top: '0.625rem',
+            right: '3.5rem',
+            fontSize: '0.6875rem',
+            color: 'var(--clearify-text-tertiary)',
+            textTransform: 'uppercase',
+            letterSpacing: '0.05em',
+            userSelect: 'none',
+            fontFamily: 'var(--font-mono)',
+            fontWeight: 500,
+          }}
+        >
+          {lang}
+        </div>
+      )}
+      <button
+        onClick={handleCopy}
+        style={{
+          position: 'absolute',
+          top: '0.5rem',
+          right: '0.5rem',
+          background: 'var(--clearify-bg)',
+          border: '1px solid var(--clearify-border)',
+          borderRadius: 'var(--clearify-radius-sm)',
+          padding: '0.25rem 0.625rem',
+          cursor: 'pointer',
+          fontSize: '0.6875rem',
+          fontWeight: 500,
+          color: copied ? 'var(--clearify-primary)' : 'var(--clearify-text-tertiary)',
+          transition: 'all 0.15s ease',
+          fontFamily: 'var(--font-sans)',
+        }}
+        className="clearify-copy-btn"
+        aria-label="Copy code"
+      >
+        {copied ? (
+          <span style={{ display: 'flex', alignItems: 'center', gap: '0.25rem' }}>
+            <svg width="12" height="12" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2.5" strokeLinecap="round" strokeLinejoin="round">
+              <polyline points="20 6 9 17 4 12" />
+            </svg>
+            Copied
+          </span>
+        ) : (
+          <span style={{ display: 'flex', alignItems: 'center', gap: '0.25rem' }}>
+            <svg width="12" height="12" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round">
+              <rect x="9" y="9" width="13" height="13" rx="2" ry="2" />
+              <path d="M5 15H4a2 2 0 0 1-2-2V4a2 2 0 0 1 2-2h9a2 2 0 0 1 2 2v1" />
+            </svg>
+            Copy
+          </span>
+        )}
+      </button>
+      <pre
+        ref={preRef}
+        className={className}
+        style={{
+          backgroundColor: 'var(--clearify-bg-secondary)',
+          border: '1px solid var(--clearify-border)',
+          borderRadius: 'var(--clearify-radius)',
+          padding: '1rem 1.25rem',
+          overflow: 'auto',
+          fontSize: '0.8125rem',
+          lineHeight: 1.75,
+          fontFamily: 'var(--font-mono)',
+        }}
+        {...props}
+      >
+        {children}
+      </pre>
+
+      <style>{`
+        .clearify-copy-btn:hover {
+          border-color: var(--clearify-border-strong) !important;
+          color: var(--clearify-text) !important;
+          background: var(--clearify-bg-secondary) !important;
+        }
+      `}</style>
+    </div>
+  );
+}

package/src/theme/Content.tsx

@@ -0,0 +1,32 @@
+import React from 'react';
+import { Breadcrumbs } from './components/Breadcrumbs.js';
+
+interface ContentProps {
+  children: React.ReactNode;
+}
+
+export function Content({ children }: ContentProps) {
+  return (
+    <div
+      className="clearify-prose"
+      style={{
+        flex: 1,
+        minWidth: 0,
+        padding: '2.5rem 3rem',
+        maxWidth: 'var(--clearify-content-max)',
+        animation: 'clearify-fade-in 0.3s ease-out',
+      }}
+    >
+      <Breadcrumbs />
+      {children}
+
+      <style>{`
+        @media (max-width: 768px) {
+          .clearify-prose {
+            padding: 1.5rem 1.25rem !important;
+          }
+        }
+      `}</style>
+    </div>
+  );
+}

package/src/theme/Footer.tsx

@@ -0,0 +1,53 @@
+import React from 'react';
+
+interface FooterProps {
+  name: string;
+  links?: { github?: string; [key: string]: string | undefined };
+}
+
+export function Footer({ name, links }: FooterProps) {
+  return (
+    <footer
+      style={{
+        borderTop: '1px solid var(--clearify-border)',
+        padding: '2rem 2.5rem',
+        fontSize: '0.8125rem',
+        color: 'var(--clearify-text-tertiary)',
+        display: 'flex',
+        justifyContent: 'space-between',
+        alignItems: 'center',
+        flexWrap: 'wrap',
+        gap: '1rem',
+      }}
+    >
+      <div style={{ letterSpacing: '-0.01em' }}>
+        &copy; {new Date().getFullYear()} {name}.{' '}
+        <span style={{ opacity: 0.6 }}>Built with Clearify.</span>
+      </div>
+      {links && (
+        <div style={{ display: 'flex', gap: '1.25rem' }}>
+          {Object.entries(links).map(([key, url]) =>
+            url ? (
+              <a
+                key={key}
+                href={url}
+                target="_blank"
+                rel="noopener noreferrer"
+                style={{
+                  color: 'var(--clearify-text-tertiary)',
+                  textDecoration: 'none',
+                  transition: 'color 0.15s',
+                  fontSize: '0.8125rem',
+                }}
+                onMouseEnter={(e) => (e.currentTarget.style.color = 'var(--clearify-text-secondary)')}
+                onMouseLeave={(e) => (e.currentTarget.style.color = 'var(--clearify-text-tertiary)')}
+              >
+                {key.charAt(0).toUpperCase() + key.slice(1)}
+              </a>
+            ) : null
+          )}
+        </div>
+      )}
+    </footer>
+  );
+}

package/src/theme/Head.tsx

@@ -0,0 +1,80 @@
+import { useEffect } from 'react';
+// @ts-expect-error virtual module
+import config from 'virtual:clearify/config';
+import { useHeadContext } from './HeadContext.js';
+
+interface HeadProps {
+  title?: string;
+  description?: string;
+  url?: string;
+}
+
+export function Head({ title, description, url }: HeadProps) {
+  const headCtx = useHeadContext();
+
+  // SSR mode: push data to collector, no DOM access
+  if (headCtx) {
+    const pageTitle = title ? `${title} | ${config.name}` : config.name;
+    const desc = description ?? `${config.name} documentation`;
+    headCtx.collect({
+      title: pageTitle,
+      description: desc,
+      url: url ?? '',
+      siteName: config.name,
+    });
+    return null;
+  }
+
+  // Client mode: useEffect DOM mutations (existing behavior)
+  useEffect(() => {
+    const pageTitle = title ? `${title} | ${config.name}` : config.name;
+    document.title = pageTitle;
+
+    const desc = description ?? `${config.name} documentation`;
+
+    // Update meta description
+    let metaDesc = document.querySelector('meta[name="description"]');
+    if (!metaDesc) {
+      metaDesc = document.createElement('meta');
+      metaDesc.setAttribute('name', 'description');
+      document.head.appendChild(metaDesc);
+    }
+    metaDesc.setAttribute('content', desc);
+
+    // Update OG tags
+    setMeta('og:title', pageTitle);
+    setMeta('og:description', desc);
+    setMeta('og:type', 'article');
+    setMeta('og:site_name', config.name);
+
+    // Update Twitter tags
+    setMeta('twitter:card', 'summary', 'name');
+    setMeta('twitter:title', pageTitle, 'name');
+    setMeta('twitter:description', desc, 'name');
+
+    // Update canonical link
+    if (url) {
+      const siteUrl = config.siteUrl?.replace(/\/$/, '') ?? '';
+      const canonical = siteUrl ? `${siteUrl}${url}` : url;
+      let link = document.querySelector('link[rel="canonical"]') as HTMLLinkElement | null;
+      if (!link) {
+        link = document.createElement('link');
+        link.setAttribute('rel', 'canonical');
+        document.head.appendChild(link);
+      }
+      link.setAttribute('href', canonical);
+    }
+  }, [title, description, url]);
+
+  return null;
+}
+
+function setMeta(key: string, content: string, attr: 'property' | 'name' = 'property') {
+  let el = document.querySelector(`meta[${attr}="${key}"]`);
+  if (!el) {
+    el = document.createElement('meta');
+    el.setAttribute(attr, key);
+    document.head.appendChild(el);
+  }
+  el.setAttribute('content', content);
+}

package/src/theme/HeadContext.tsx

@@ -0,0 +1,32 @@
+import React, { createContext, useContext } from 'react';
+
+export interface HeadData {
+  title: string;
+  description: string;
+  url: string;
+  siteName: string;
+}
+
+interface HeadContextValue {
+  collect: (data: HeadData) => void;
+}
+
+const HeadContext = createContext<HeadContextValue | null>(null);
+
+export function useHeadContext() {
+  return useContext(HeadContext);
+}
+
+export function HeadProvider({
+  children,
+  onCollect,
+}: {
+  children: React.ReactNode;
+  onCollect: (data: HeadData) => void;
+}) {
+  return (
+    <HeadContext.Provider value={{ collect: onCollect }}>
+      {children}
+    </HeadContext.Provider>
+  );
+}