mirror of
https://github.com/hanzoai/skills.git
synced 2026-11-19 00:47:36 +00:00
hanzoskills.com/llms.txt now opens with the install line, the API reference index and the company index, so an agent that lands on any one of the three can find the rest. robots.txt claimed 537 documents while llms.txt counts 920. The number is gone from robots.txt; llms.txt derives it. public/ is regenerated from scripts/site.py, which it had fallen behind: the copy-prompt menu and agent bar were in the generator and not in the committed pages. tests/site.mjs passes against the result. Co-authored-by: Hanzo Dev <[email protected]>
783 lines
49 KiB
HTML
783 lines
49 KiB
HTML
<!doctype html>
|
|
<html lang="en"><head>
|
|
<meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1">
|
|
<title>hip-0045</title>
|
|
<meta name="color-scheme" content="dark">
|
|
<style>
|
|
/* Committed to one visual world: a dark instrument panel. No light variant —
|
|
the dot field and the hairline rules only read on black, and a naive
|
|
inversion would wash both out. Every colour is painted explicitly so the page
|
|
never borrows a host background. */
|
|
@font-face{font-family:'Zen';src:url('/fonts/Zen-Variable.woff2') format('woff2');font-weight:100 900;font-style:normal;font-display:swap}
|
|
@font-face{font-family:'Zen';src:url('/fonts/Zen-Italic-Variable.woff2') format('woff2');font-weight:100 900;font-style:italic;font-display:swap}
|
|
@font-face{font-family:'Zen Mono';src:url('/fonts/ZenMono-Variable.woff2') format('woff2');font-weight:100 900;font-style:normal;font-display:swap}
|
|
@font-face{font-family:'Zen Mono';src:url('/fonts/ZenMono-Italic-Variable.woff2') format('woff2');font-weight:100 900;font-style:italic;font-display:swap}
|
|
@font-face{font-family:'Zen Pixel Square';src:url('/fonts/ZenPixel-Square.woff2') format('woff2');font-style:normal;font-display:swap}
|
|
|
|
:root{
|
|
--ink:#f4f4f2; --soft:#9c9c98; --faint:#6a6a66; --ground:#000; --panel:#0a0a0a;
|
|
--line:#232323; --line-hi:#3a3a3a; --accent:#f4f4f2;
|
|
--font-zen-sans:'Zen',-apple-system,BlinkMacSystemFont,"Segoe UI",Helvetica,Arial,sans-serif;
|
|
--font-zen-mono:'Zen Mono',ui-monospace,"SF Mono",SFMono-Regular,Menlo,Consolas,monospace;
|
|
--font-zen-pixel-square:'Zen Pixel Square',monospace;
|
|
--mono:var(--font-zen-mono);
|
|
--sans:var(--font-zen-sans);
|
|
/* Controls are pills and surfaces are soft, as on hanzo.ai. */
|
|
--r:999px; --r-soft:14px;
|
|
}
|
|
*{box-sizing:border-box}
|
|
html{-webkit-text-size-adjust:100%}
|
|
body{margin:0;background:var(--ground);color:var(--ink);font-family:var(--sans);
|
|
font-size:16px;line-height:1.65;-webkit-font-smoothing:antialiased}
|
|
.wrap{max-width:60rem;margin:0 auto;padding:0 1.75rem}
|
|
|
|
/* The dot field. A halftone made of one repeating radial-gradient, faded out
|
|
along the diagonal by a mask so it reads as a wave rather than wallpaper. */
|
|
/* No overflow clip here: the dot field is inset to the box already, and a clip
|
|
would cut off the copy-prompt menu. */
|
|
.hero{position:relative;border-bottom:1px solid var(--line)}
|
|
.hero::before{content:"";position:absolute;inset:0;
|
|
background-image:radial-gradient(var(--line-hi) 1px, transparent 1px);
|
|
background-size:7px 7px;
|
|
-webkit-mask-image:linear-gradient(115deg,#000 0%,rgba(0,0,0,.55) 38%,transparent 72%);
|
|
mask-image:linear-gradient(115deg,#000 0%,rgba(0,0,0,.55) 38%,transparent 72%);
|
|
pointer-events:none}
|
|
.hero .wrap{position:relative;padding-top:5.5rem;padding-bottom:4rem}
|
|
|
|
nav{border-bottom:1px solid var(--line)}
|
|
nav .in{max-width:60rem;margin:0 auto;padding:1.1rem 1.75rem;display:flex;
|
|
justify-content:space-between;align-items:center;gap:1rem}
|
|
.brand{font-family:var(--mono);font-size:.85rem;letter-spacing:.14em;
|
|
text-transform:uppercase;color:var(--ink);text-decoration:none;
|
|
display:inline-flex;align-items:center;gap:.6rem}
|
|
.brand i{font-style:normal;color:var(--faint)}
|
|
.mark{width:1.15em;height:1.15em;display:block;flex:0 0 auto}
|
|
nav a.up{font-family:var(--mono);font-size:.72rem;letter-spacing:.14em;
|
|
text-transform:uppercase;color:var(--soft);text-decoration:none}
|
|
nav a.up:hover{color:var(--ink)}
|
|
|
|
h1{font-family:var(--mono);font-size:clamp(2rem,5.4vw,3.4rem);line-height:1.12;
|
|
letter-spacing:-.02em;margin:0 0 1.1rem;font-weight:500;text-wrap:balance}
|
|
h1 em{font-style:normal;color:var(--faint)}
|
|
.lede{color:var(--soft);font-size:1.05rem;max-width:52ch;margin:0 0 2.25rem}
|
|
|
|
.btns{display:flex;flex-wrap:wrap;gap:.7rem;margin:0 0 .5rem;align-items:center}
|
|
.btn{display:inline-flex;align-items:center;gap:.5rem;font-family:var(--mono);
|
|
font-size:.72rem;letter-spacing:.14em;text-transform:uppercase;
|
|
padding:.8rem 1.4rem;border:1px solid var(--line-hi);border-radius:var(--r);
|
|
color:var(--ink);text-decoration:none;background:transparent;cursor:pointer;
|
|
line-height:1.2;font-weight:400}
|
|
.btn:hover{background:#141414;text-decoration:none;border-color:var(--soft)}
|
|
.btn.solid{background:var(--ink);color:#000;border-color:var(--ink)}
|
|
.btn.solid:hover{background:#d8d8d4}
|
|
.btn .chev{width:.7em;height:.7em;flex:0 0 auto;transition:transform .15s ease}
|
|
.btn[aria-expanded="true"] .chev{transform:rotate(180deg)}
|
|
|
|
/* Copy-prompt selector. Each row copies the prompt for its own target. */
|
|
.copy{position:relative;display:inline-flex}
|
|
.menu{position:absolute;top:calc(100% + .5rem);left:0;z-index:20;min-width:21rem;
|
|
background:var(--panel);border:1px solid var(--line-hi);border-radius:var(--r-soft);
|
|
padding:.4rem;display:flex;flex-direction:column;
|
|
box-shadow:0 12px 32px rgba(0,0,0,.75)}
|
|
.menu[hidden]{display:none}
|
|
.mi{display:flex;align-items:center;gap:.7rem;width:100%;text-align:left;
|
|
padding:.62rem .8rem;border:0;border-radius:calc(var(--r-soft) - .35rem);
|
|
background:transparent;color:var(--ink);font-family:var(--mono);font-size:.76rem;
|
|
letter-spacing:.04em;text-decoration:none;cursor:pointer;line-height:1.3;
|
|
white-space:nowrap}
|
|
.mi:hover,.mi:focus-visible{background:#181818;outline:none}
|
|
.mi .mark{width:1.05rem;height:1.05rem;color:var(--soft)}
|
|
.mi:hover .mark{color:var(--ink)}
|
|
.mi u{margin-left:auto;color:var(--faint);text-decoration:none;font-size:.68rem;
|
|
letter-spacing:.1em;text-transform:uppercase}
|
|
|
|
/* Works-with bar: one scrolling row, name and mark per agent. */
|
|
.strip{border-bottom:1px solid var(--line);background:var(--panel)}
|
|
.strip .in{max-width:60rem;margin:0 auto;padding:.9rem 1.75rem;display:flex;
|
|
align-items:center;gap:1.25rem;font-family:var(--mono);font-size:.72rem;
|
|
letter-spacing:.1em;text-transform:uppercase;color:var(--faint)}
|
|
.strip b{color:var(--soft);font-weight:400;flex:0 0 auto;
|
|
border-right:1px solid var(--line);padding-right:1.25rem;align-self:stretch;
|
|
display:flex;align-items:center}
|
|
.bar{display:flex;align-items:center;gap:.5rem;flex:1 1 auto;min-width:0;
|
|
overflow-x:auto;scrollbar-width:none;scroll-snap-type:x proximity;
|
|
-webkit-overflow-scrolling:touch;
|
|
-webkit-mask-image:linear-gradient(90deg,#000 calc(100% - 3rem),transparent);
|
|
mask-image:linear-gradient(90deg,#000 calc(100% - 3rem),transparent)}
|
|
.bar::-webkit-scrollbar{display:none}
|
|
.agent{display:inline-flex;align-items:center;gap:.45rem;flex:0 0 auto;
|
|
padding:.4rem .85rem;border:1px solid var(--line);border-radius:var(--r);
|
|
color:var(--soft);white-space:nowrap;scroll-snap-align:start;
|
|
text-decoration:none;background:var(--ground)}
|
|
.agent:hover{color:var(--ink);border-color:var(--line-hi);text-decoration:none}
|
|
.agent .mark{width:.95rem;height:.95rem}
|
|
|
|
h2{font-family:var(--mono);font-size:1.1rem;letter-spacing:-.01em;margin:2.75rem 0 .75rem;font-weight:500}
|
|
h3{font-size:1rem;margin:2rem 0 .5rem;font-weight:600}
|
|
h4,h5,h6{font-size:.94rem;margin:1.5rem 0 .5rem;font-weight:600}
|
|
p{margin:0 0 1rem;max-width:70ch}
|
|
ul,ol{margin:0 0 1rem;padding-left:1.35rem;max-width:70ch}
|
|
li{margin:.22rem 0}
|
|
a{color:var(--ink);text-decoration:underline;text-underline-offset:3px;
|
|
text-decoration-color:var(--line-hi)}
|
|
a:hover{text-decoration-color:var(--ink)}
|
|
a:focus-visible{outline:1px solid var(--ink);outline-offset:3px}
|
|
code{font-family:var(--mono);font-size:.85em;background:var(--panel);
|
|
border:1px solid var(--line);border-radius:5px;padding:.1em .36em}
|
|
pre{background:var(--panel);border:1px solid var(--line);padding:1rem 1.1rem;
|
|
border-radius:var(--r-soft);overflow-x:auto;margin:0 0 1.25rem}
|
|
pre code{background:none;border:0;padding:0;font-size:.82rem;line-height:1.7}
|
|
blockquote{margin:0 0 1rem;padding-left:1rem;border-left:1px solid var(--line-hi);color:var(--soft)}
|
|
hr{border:0;border-top:1px solid var(--line);margin:2.5rem 0}
|
|
table{border-collapse:collapse;width:100%;margin:0 0 1.25rem;font-size:.92rem;
|
|
display:block;overflow-x:auto}
|
|
th,td{border:1px solid var(--line);padding:.5rem .7rem;text-align:left}
|
|
|
|
.curl{display:block;background:var(--panel);border:1px solid var(--line);
|
|
border-radius:var(--r-soft);padding:.95rem 1.1rem;font-family:var(--mono);
|
|
font-size:.8rem;color:var(--soft);overflow-x:auto;margin:0 0 2.5rem;
|
|
white-space:pre;line-height:1.9}
|
|
.curl b{color:var(--ink);font-weight:400}
|
|
.curl i{font-style:normal;color:var(--faint)}
|
|
|
|
/* index */
|
|
#q{width:100%;padding:.85rem 1.2rem;font-family:var(--mono);font-size:.85rem;color:var(--ink);
|
|
background:var(--panel);border:1px solid var(--line);border-radius:var(--r);margin:0 0 .6rem}
|
|
#q::placeholder{color:var(--faint);text-transform:uppercase;letter-spacing:.1em;font-size:.72rem}
|
|
#q:focus{outline:none;border-color:var(--soft)}
|
|
#count{color:var(--faint);font-family:var(--mono);font-size:.72rem;letter-spacing:.1em;
|
|
text-transform:uppercase;margin:0 0 2rem}
|
|
.cat{margin:2.5rem 0 .5rem;font-family:var(--mono);font-size:.7rem;letter-spacing:.16em;
|
|
text-transform:uppercase;color:var(--faint);border-bottom:1px solid var(--line);
|
|
padding-bottom:.45rem}
|
|
.row{display:block;padding:.6rem .9rem;margin:0 -.9rem;border-bottom:1px solid var(--line);
|
|
border-radius:var(--r-soft);text-decoration:none}
|
|
.row:hover{background:#0a0a0a}
|
|
.nm{font-family:var(--mono);font-size:.84rem;color:var(--ink);display:block}
|
|
.ds{color:var(--soft);font-size:.9rem;display:block;margin-top:.12rem}
|
|
footer{margin-top:4rem;padding:2rem 0 4rem;border-top:1px solid var(--line);
|
|
color:var(--faint);font-size:.85rem}
|
|
footer a{color:var(--soft)}
|
|
.fmap{display:grid;gap:1.75rem;grid-template-columns:repeat(auto-fit,minmax(11rem,1fr));
|
|
margin:0 0 2rem;font-size:.85rem}
|
|
.fmap b{display:block;font-family:var(--mono);font-size:.68rem;letter-spacing:.16em;
|
|
text-transform:uppercase;color:var(--faint);font-weight:400;margin:0 0 .6rem;
|
|
border-bottom:1px solid var(--line);padding-bottom:.4rem}
|
|
.fmap a{display:inline-block;color:var(--ink);text-decoration:none;margin:.3rem .35rem 0 0}
|
|
.fmap a:hover{text-decoration:underline}
|
|
.fmap div{color:var(--faint);line-height:1.5}
|
|
.fend{border-top:1px solid var(--line);padding-top:1.25rem;font-size:.82rem}
|
|
|
|
@media (max-width:640px){
|
|
.hero .wrap{padding-top:3.25rem;padding-bottom:2.75rem}
|
|
.btns{gap:.5rem}
|
|
.btn{padding:.75rem 1.15rem;font-size:.68rem}
|
|
.copy,.copy .btn{width:100%;justify-content:center}
|
|
.menu{left:0;right:0;min-width:0}
|
|
.strip .in{flex-direction:column;align-items:flex-start;gap:.6rem;padding:.9rem 1.75rem}
|
|
.strip b{border-right:0;padding-right:0}
|
|
.bar{width:100%}
|
|
}
|
|
</style>
|
|
<link rel="alternate" type="text/markdown" href="/hip-0045.md">
|
|
|
|
<link rel="icon" href="/favicon.svg">
|
|
<link rel="canonical" href="https://hanzoskills.com/hip-0045">
|
|
</head>
|
|
<!-- Reading this with a machine? Every page here is also plain markdown.
|
|
This one: https://hanzoskills.com/hip-0045.md
|
|
Index: https://hanzoskills.com/llms.txt
|
|
Corpus: https://hanzoskills.com/all.md
|
|
Append .md to any path for the markdown twin. -->
|
|
<body>
|
|
<nav><div class="in">
|
|
<a class="brand" href="/"><svg class="mark" viewBox="0 0 67 67" fill="currentColor" aria-hidden="true"><path d="M22.21 67V44.6369H0V67H22.21Z"/><path d="M66.7038 22.3184H22.2534L0.0878906 44.6367H44.4634L66.7038 22.3184Z"/><path d="M22.21 0H0V22.3184H22.21V0Z"/><path d="M66.7198 0H44.5098V22.3184H66.7198V0Z"/><path d="M66.7198 67V44.6369H44.5098V67H66.7198Z"/></svg> HANZO<i>SKILLS</i></a>
|
|
<a class="up" href="/">All skills</a>
|
|
</div></nav>
|
|
|
|
<div class="wrap">
|
|
<h1>hip-0045</h1><p class="lede">HIP-45: Documentation Framework Standard. Status Final. Hanzo architectural specification.</p><h1>HIP-0045: Documentation Framework Standard</h1>
|
|
<h2>Abstract</h2>
|
|
<p>This proposal defines the documentation framework standard for the Hanzo ecosystem. All developer-facing documentation sites -- from API references to protocol specifications -- MUST be built using the <code>@hanzo/docs-*</code> package family, a purpose-built fork of the Fumadocs framework extended with multi-brand theming, OpenAPI generation, and cross-ecosystem search.</p>
|
|
<p>The framework ships as 24 independently versioned packages in a pnpm monorepo. Applications compose only the packages they need. A single unified wrapper (<code>@hanzo/docs</code>) re-exports everything for convenience.</p>
|
|
<p><strong>Repository</strong>: <a href="https://github.com/hanzoai/docs">github.com/hanzoai/docs</a> <strong>Primary Package</strong>: <code>@hanzo/docs</code> (unified wrapper) <strong>Build Toolchain</strong>: tsdown for packages, Turbo for monorepo orchestration <strong>Runtime</strong>: Next.js 15+ with App Router, React 19+, Tailwind CSS 4+</p>
|
|
<h2>Design Philosophy</h2>
|
|
<p>This section explains the <strong>why</strong> behind each architectural decision. Documentation infrastructure is high-leverage -- the wrong choice here affects every product team and every developer who reads Hanzo docs.</p>
|
|
<h3>Why Fork Fumadocs (Not Use It Directly)</h3>
|
|
<p>Fumadocs is the best Next.js documentation framework available. It supports the App Router, React Server Components, and ships with a clean Radix UI component library. It is 40% lighter than Docusaurus and has first-class MDX support.</p>
|
|
<p>We forked it because we need capabilities that do not fit upstream's scope:</p>
|
|
<ul><li><strong>Multi-brand theming</strong>: Fumadocs assumes one site = one brand. We need a single deployment pipeline that produces five visually distinct sites from shared content structure. This requires deep changes to the theming layer (CSS variable namespacing, brand-aware component variants, per-site layout configuration).</li></ul>
|
|
<ul><li><strong>Custom search</strong>: Fumadocs provides Orama-based search per site. We need cross-site federated search and integration with our own search API (HIP-1147). This requires changes to the search indexing pipeline and client.</li></ul>
|
|
<ul><li><strong>OpenAPI generation</strong>: While Fumadocs has an OpenAPI plugin, we need tighter integration -- generating pages that match our API playground format, supporting our authentication flows, and rendering response schemas with our type table components.</li></ul>
|
|
<ul><li><strong>Package renaming</strong>: Our fork publishes under the <code>@hanzo/docs-*</code> namespace so that consumers clearly depend on the Hanzo-maintained version, which receives security patches, multi-brand features, and ecosystem integrations that upstream does not.</li></ul>
|
|
<p>The fork maintains an <code>upstream</code> remote pointing to <code>fuma-nama/fumadocs</code>. We periodically merge upstream changes and resolve conflicts in our extension points. This gives us upstream improvements (bug fixes, performance, new Radix UI components) while maintaining our custom features.</p>
|
|
<p><strong>Trade-off acknowledged</strong>: Maintaining a fork requires ongoing merge effort. We accept this because the alternative -- building a docs framework from scratch -- is orders of magnitude more work, and using upstream directly does not meet our multi-brand and OpenAPI requirements.</p>
|
|
<h3>Why a Monorepo with 24 Packages</h3>
|
|
<p>Each package is independently versioned and publishable. This matters because:</p>
|
|
<ul><li><strong>Selective dependency</strong>: A site that only needs core source loading and a basic UI does not need to install the OpenAPI generator, Python docgen, or Twoslash TypeScript hints. It installs <code>@hanzo/docs-core</code> + <code>@hanzo/docs-ui</code> and nothing else.</li></ul>
|
|
<ul><li><strong>Independent release cadence</strong>: A bug fix in <code>@hanzo/docs-openapi</code> does not force a release of <code>@hanzo/docs-core</code>. Sites that do not use OpenAPI docs are unaffected.</li></ul>
|
|
<ul><li><strong>Tree-shaking</strong>: Because packages declare explicit exports, bundlers can eliminate unused code. The unified <code>@hanzo/docs</code> wrapper re-exports everything but consumers who import from it still benefit from tree-shaking at the module level.</li></ul>
|
|
<ul><li><strong>Clear ownership boundaries</strong>: Each package has a defined scope. <code>@hanzo/docs-core</code> handles source loading and search. <code>@hanzo/docs-ui</code> handles Radix UI components. <code>@hanzo/docs-openapi</code> handles spec parsing and page generation. Contributors know where to make changes.</li></ul>
|
|
<h2>Specification</h2>
|
|
<h3>Package Architecture</h3>
|
|
<p>The framework consists of 24 packages organized by responsibility:</p>
|
|
<h4>Core Packages</h4>
|
|
<p>| Package | NPM Name | Purpose | |---------|----------|---------| | <code>packages/core</code> | <code>@hanzo/docs-core</code> | Source loading, search indexing, i18n, page tree construction, breadcrumb generation, TOC extraction, syntax highlighting | | <code>packages/mdx</code> | <code>@hanzo/docs-mdx</code> | MDX processing, frontmatter parsing, content collections, file watching, Next.js/Vite integration | | <code>packages/hanzo-docs</code> | <code>@hanzo/docs</code> | Unified wrapper that re-exports all packages under a single import namespace |</p>
|
|
<h4>UI Packages</h4>
|
|
<p>| Package | NPM Name | Purpose | |---------|----------|---------| | <code>packages/radix-ui</code> | <code>@hanzo/docs-ui</code> | Full UI component library built on Radix primitives (sidebar, TOC, breadcrumb, search dialog, code blocks, tabs, cards, callouts) | | <code>packages/base-ui</code> | <code>@hanzo/docs-base-ui</code> | Headless UI components built on <code>@base-ui/react</code> for maximum styling flexibility | | <code>packages/tailwind</code> | <code>@hanzo/docs-tailwind</code> | Tailwind CSS utilities, preset configuration, and CSS custom property definitions | | <code>packages/story</code> | <code>@hanzo/docs-story</code> | Component story/preview system for documentation UI components |</p>
|
|
<h4>Content Generation Packages</h4>
|
|
<p>| Package | NPM Name | Purpose | |---------|----------|---------| | <code>packages/openapi</code> | <code>@hanzo/docs-openapi</code> | Auto-generate endpoint documentation from OpenAPI 3.x specs, with interactive playground | | <code>packages/typescript</code> | <code>@hanzo/docs-typescript</code> | Auto-generate type tables from TypeScript declarations and <code>.d.ts</code> files | | <code>packages/python</code> | <code>@hanzo/docs-python</code> | Python API documentation generation (includes <code>fumapy</code> Python package for docstring extraction) | | <code>packages/twoslash</code> | <code>@hanzo/docs-twoslash</code> | TypeScript code hints and inline type annotations in code blocks | | <code>packages/doc-gen</code> | <code>@hanzo/docs-docgen</code> | Generic documentation generation utilities |</p>
|
|
<h4>Integration Packages</h4>
|
|
<p>| Package | NPM Name | Purpose | |---------|----------|---------| | <code>packages/mdx-remote</code> | <code>@hanzo/docs-mdx-remote</code> | Remote MDX content loading (fetch MDX from URLs or CMS) | | <code>packages/mdx-runtime</code> | <code>@hanzo/mdx-runtime</code> | Runtime MDX compilation for dynamic content | | <code>packages/obsidian</code> | <code>@hanzo/docs-obsidian</code> | Obsidian vault adapter (use Obsidian markdown as docs source) | | <code>packages/content-collections</code> | <code>@hanzo/docs-content-collections</code> | Content Collections integration for type-safe content | | <code>packages/press</code> | <code>@hanzo/docs-press</code> | Minimal setup package for quick documentation sites |</p>
|
|
<h4>Tooling Packages</h4>
|
|
<p>| Package | NPM Name | Purpose | |---------|----------|---------| | <code>packages/cli</code> | <code>@hanzo/docs-cli</code> | CLI for scaffolding new doc sites, customizing components, and running dev tasks | | <code>packages/create-app</code> | <code>@hanzo/docs-create-app</code> | Project scaffolding (<code>pnpm create @hanzo/docs-app</code>) | | <code>packages/create-app-versions</code> | <code>@hanzo/docs-create-app-versions</code> | Version tracking for create-app templates | | <code>packages/stf</code> | <code>@fumari/stf</code> | Upstream schema/transform dependency (kept under original namespace) | | <code>packages/org</code> | <code>@hanzo/docs-org</code> | Organization-level shared utilities |</p>
|
|
<h4>Configuration Packages</h4>
|
|
<p>| Package | NPM Name | Purpose | |---------|----------|---------| | <code>packages/tsconfig</code> | <code>tsconfig</code> | Shared TypeScript configuration (base, Next.js, React library) | | <code>packages/eslint-config-custom</code> | <code>eslint-config-custom</code> | Shared ESLint configuration | | <code>packages/shared</code> | <code>shared</code> | Shared internal utilities and registry |</p>
|
|
<h3>Package Dependency Graph</h3>
|
|
<pre><code>@hanzo/docs (unified wrapper)
|
|
|
|
|
+-- @hanzo/docs-core .............. source, search, i18n, page tree
|
|
| |
|
|
| +-- shiki .................. syntax highlighting
|
|
| +-- @orama/orama .......... full-text search engine
|
|
| +-- unified/remark ........ markdown processing pipeline
|
|
|
|
|
+-- @hanzo/docs-mdx .............. MDX processing, collections
|
|
| |
|
|
| +-- @mdx-js/mdx ........... MDX compiler
|
|
| +-- chokidar .............. file watching
|
|
| +-- esbuild ............... fast JS/TS bundling
|
|
|
|
|
+-- @hanzo/docs-ui ............... Radix UI components
|
|
| |
|
|
| +-- @radix-ui/* ........... UI primitives
|
|
| +-- motion ................ animations
|
|
| +-- next-themes ........... dark/light mode
|
|
| +-- tailwind-merge ........ class merging
|
|
|
|
|
+-- @hanzo/docs-openapi .......... OpenAPI doc generation
|
|
| |
|
|
| +-- @scalar/openapi-parser . spec parsing
|
|
| +-- openapi-sampler ....... example generation
|
|
| +-- react-hook-form ....... playground forms
|
|
|
|
|
+-- @hanzo/docs-typescript ....... TS type tables
|
|
+-- @hanzo/docs-python ........... Python docgen
|
|
+-- @hanzo/docs-twoslash ......... TS code hints
|
|
+-- @hanzo/docs-obsidian ......... Obsidian adapter
|
|
+-- @hanzo/docs-press ............ minimal setup
|
|
+-- @hanzo/docs-cli .............. scaffolding
|
|
+-- @hanzo/docs-mdx-remote ....... remote MDX
|
|
+-- @hanzo/mdx-runtime ........... runtime MDX
|
|
+-- @hanzo/docs-content-collections
|
|
+-- @hanzo/docs-docgen</code></pre>
|
|
<h3>Sites Powered by This Framework</h3>
|
|
<p>| Site | URL | App Directory | Purpose | |------|-----|---------------|---------| | Main Docs | docs.hanzo.ai | <code>apps/docs</code> | Primary Hanzo documentation, API reference | | HIPs | hips.hanzo.ai | <code>../hips/docs</code> | Hanzo Improvement Proposals | | Zen LM | zenlm.org | <code>apps/zen-docs</code> | Zen model family documentation | | ZAP Protocol | zap.hanzo.ai | <code>apps/zap-docs</code> | ZAP protocol specification | | Dev Docs | dev.hanzo.ai | <code>apps/dev-docs</code> | Developer guides and tutorials | | Bot Docs | bot.hanzo.ai | <code>apps/bot-docs</code> | Bot framework documentation |</p>
|
|
<h3>Source Configuration</h3>
|
|
<p>Every documentation site MUST define a <code>source.config.ts</code> at its root:</p>
|
|
<pre><code class="lang-typescript">import { defineConfig, defineDocs } from '@hanzo/docs-mdx/config';
|
|
|
|
export default defineConfig({
|
|
docs: defineDocs({
|
|
dir: 'content/docs',
|
|
}),
|
|
});</code></pre>
|
|
<p>This file declares the content sources. The MDX package uses it to:</p>
|
|
<ol><li>Discover markdown/MDX files in the specified directories</li><li>Extract frontmatter metadata</li><li>Build the page tree (navigation structure)</li><li>Generate TypeScript types for content collections</li></ol>
|
|
<h3>Source Loader</h3>
|
|
<p>Each site MUST create a source loader in <code>lib/source.ts</code>:</p>
|
|
<pre><code class="lang-typescript">import { docs } from '@/.source';
|
|
import { loader } from '@hanzo/docs-core/source';
|
|
|
|
export const source = loader({
|
|
baseUrl: '/docs',
|
|
source: docs.toFumadocsSource(),
|
|
});</code></pre>
|
|
<p>The loader transforms raw content into a structured page tree with:</p>
|
|
<ul><li>URL slugs derived from file paths</li><li>Navigation ordering from frontmatter or file naming (<code>01-getting-started.mdx</code>)</li><li>Folder-based grouping with <code>meta.json</code> for custom ordering</li><li>Breadcrumb data for each page</li></ul>
|
|
<h3>Page Component Pattern</h3>
|
|
<p>Documentation pages follow this pattern:</p>
|
|
<pre><code class="lang-tsx">import { source } from '@/lib/source';
|
|
import { DocsPage, DocsBody } from '@hanzo/docs-ui/layouts/docs/page';
|
|
import defaultMdxComponents from '@hanzo/docs-ui/mdx';
|
|
import { notFound } from 'next/navigation';
|
|
|
|
export default async function Page(props: { params: Promise<{ slug?: string[] }> }) {
|
|
const params = await props.params;
|
|
const page = source.getPage(params.slug);
|
|
if (!page) notFound();
|
|
|
|
const MDX = page.data.body;
|
|
|
|
return (
|
|
<DocsPage toc={page.data.toc}>
|
|
<DocsBody>
|
|
<MDX components={{ ...defaultMdxComponents }} />
|
|
</DocsBody>
|
|
</DocsPage>
|
|
);
|
|
}</code></pre>
|
|
<h3>Layout System</h3>
|
|
<p>The framework provides four layout variants:</p>
|
|
<p>| Layout | Import Path | Use Case | |--------|------------|----------| | <strong>Docs</strong> | <code>@hanzo/docs-ui/layouts/docs</code> | Standard documentation with sidebar navigation | | <strong>Home</strong> | <code>@hanzo/docs-ui/layouts/home</code> | Landing pages with hero sections and feature grids | | <strong>Notebook</strong> | <code>@hanzo/docs-ui/layouts/notebook</code> | Notebook-style layout for tutorials | | <strong>Flux</strong> | <code>@hanzo/docs-ui/layouts/flux</code> | Alternative layout with fluid navigation |</p>
|
|
<p>Each layout provides a root layout component and a page component:</p>
|
|
<pre><code class="lang-tsx">// app/docs/layout.tsx
|
|
import { DocsLayout } from '@hanzo/docs-ui/layouts/docs';
|
|
import { source } from '@/lib/source';
|
|
|
|
export default function Layout({ children }: { children: React.ReactNode }) {
|
|
return (
|
|
<DocsLayout tree={source.pageTree}>
|
|
{children}
|
|
</DocsLayout>
|
|
);
|
|
}</code></pre>
|
|
<h3>Multi-Brand Theming</h3>
|
|
<p>Each site configures its brand identity through CSS custom properties and layout configuration. The theming system uses three layers:</p>
|
|
<h4>Layer 1: CSS Custom Properties</h4>
|
|
<pre><code class="lang-css">/* Brand: Hanzo */
|
|
:root {
|
|
--fd-primary: 0 84% 61%; /* #fd4444 in HSL */
|
|
--fd-background: 0 0% 4%;
|
|
--fd-foreground: 0 0% 98%;
|
|
--fd-muted: 0 0% 15%;
|
|
--fd-accent: 0 84% 61%;
|
|
--fd-border: 0 0% 15%;
|
|
--fd-ring: 0 84% 61%;
|
|
}
|
|
|
|
/* Brand: Zen */
|
|
:root {
|
|
--fd-primary: 210 100% 50%;
|
|
--fd-accent: 210 100% 50%;
|
|
}</code></pre>
|
|
<h4>Layer 2: Layout Configuration</h4>
|
|
<pre><code class="lang-tsx"><DocsLayout
|
|
tree={source.pageTree}
|
|
nav={{
|
|
title: 'Hanzo Docs',
|
|
url: 'https://docs.hanzo.ai',
|
|
}}
|
|
sidebar={{
|
|
banner: <Logo brand="hanzo" />,
|
|
}}
|
|
links={[
|
|
{ text: 'GitHub', url: 'https://github.com/hanzoai' },
|
|
{ text: 'Discord', url: 'https://discord.gg/CJCyAsm9Vr' },
|
|
]}
|
|
></code></pre>
|
|
<h4>Layer 3: Content Isolation</h4>
|
|
<p>Each brand's content lives in its own <code>content/</code> directory. The source loader is configured per-app, so cross-brand content leakage is impossible at the build level.</p>
|
|
<h3>Search</h3>
|
|
<p>The framework supports three search backends:</p>
|
|
<h4>Built-in Search (Orama)</h4>
|
|
<p>Full-text search using Orama, indexed at build time:</p>
|
|
<pre><code class="lang-typescript">import { source } from '@/lib/source';
|
|
import { createSearchAPI } from '@hanzo/docs-core/search/server';
|
|
|
|
export const { GET } = createSearchAPI('advanced', {
|
|
indexes: source.getPages().map((page) => ({
|
|
title: page.data.title,
|
|
description: page.data.description,
|
|
url: page.url,
|
|
structuredData: page.data.structuredData,
|
|
})),
|
|
});</code></pre>
|
|
<h4>Algolia Adapter</h4>
|
|
<p>For sites that need hosted search with analytics:</p>
|
|
<pre><code class="lang-typescript">import { createSearchAPI } from '@hanzo/docs-core/search/algolia-server';
|
|
|
|
export const { GET } = createSearchAPI({
|
|
appId: process.env.ALGOLIA_APP_ID!,
|
|
apiKey: process.env.ALGOLIA_API_KEY!,
|
|
indexName: 'hanzo-docs',
|
|
});</code></pre>
|
|
<h4>Custom Search API</h4>
|
|
<p>For integration with Hanzo Search (HIP-1147):</p>
|
|
<pre><code class="lang-typescript">import { createSearchAPI } from '@hanzo/docs-core/search/server';
|
|
|
|
export const { GET } = createSearchAPI('custom', {
|
|
search: async (query) => {
|
|
const results = await fetch(`https://search.hanzo.ai/v1/search?q=${query}`);
|
|
return results.json();
|
|
},
|
|
});</code></pre>
|
|
<h3>Internationalization (i18n)</h3>
|
|
<p>Built-in i18n support with file-based routing:</p>
|
|
<pre><code>content/
|
|
docs/
|
|
index.mdx # Default language (en)
|
|
index.zh.mdx # Chinese
|
|
index.ja.mdx # Japanese</code></pre>
|
|
<p>Configuration:</p>
|
|
<pre><code class="lang-typescript">// lib/source.ts
|
|
import { loader } from '@hanzo/docs-core/source';
|
|
import { i18n } from '@hanzo/docs-core/i18n';
|
|
|
|
export const { source, openapi } = loader({
|
|
baseUrl: '/docs',
|
|
source: docs.toFumadocsSource(),
|
|
i18n: {
|
|
languages: ['en', 'zh', 'ja'],
|
|
defaultLanguage: 'en',
|
|
},
|
|
});</code></pre>
|
|
<p>Middleware for locale negotiation:</p>
|
|
<pre><code class="lang-typescript">// middleware.ts
|
|
import { createI18nMiddleware } from '@hanzo/docs-core/i18n/middleware';
|
|
|
|
export default createI18nMiddleware({
|
|
languages: ['en', 'zh', 'ja'],
|
|
defaultLanguage: 'en',
|
|
});</code></pre>
|
|
<h3>MDX Components</h3>
|
|
<p>The framework provides a standard set of MDX components available in all documentation pages:</p>
|
|
<p>| Component | Description | Usage | |-----------|-------------|-------| | <code>Callout</code> | Info/warning/error callouts | <code><Callout type="warn">Text</Callout></code> | | <code>Card</code> | Linked card with title and description | <code><Card title="Guide" href="/docs/guide"></code> | | <code>Cards</code> | Card grid container | <code><Cards><Card .../><Card .../></Cards></code> | | <code>Tab</code> / <code>Tabs</code> | Tabbed content panels | <code><Tabs items={['npm', 'pnpm']}><Tab>...</Tab></Tabs></code> | | <code>Step</code> / <code>Steps</code> | Numbered step-by-step guides | <code><Steps><Step>...</Step></Steps></code> | | <code>TypeTable</code> | Auto-generated type property tables | <code><TypeTable type={MyInterface} /></code> | | <code>Accordion</code> | Collapsible content sections | <code><Accordion title="Details">...</Accordion></code> | | <code>Files</code> | File tree visualization | <code><Files><File name="app.ts" /><Folder name="lib" /></Files></code> | | <code>ImageZoom</code> | Zoomable images | <code><ImageZoom src="/img/arch.png" /></code> | | <code>CodeBlock</code> | Syntax-highlighted code with copy button | Automatic from fenced code blocks | | <code>InlineTOC</code> | Inline table of contents | <code><InlineTOC /></code> | | <code>Banner</code> | Announcement banner | <code><Banner>New release!</Banner></code> |</p>
|
|
<p>These are registered as default MDX components and available in all <code>.mdx</code> files without explicit imports.</p>
|
|
<h3>OpenAPI Integration</h3>
|
|
<p>The <code>@hanzo/docs-openapi</code> package generates documentation pages from OpenAPI 3.x specification files.</p>
|
|
<h4>Spec Loading</h4>
|
|
<pre><code class="lang-typescript">// source.config.ts
|
|
import { defineConfig, defineDocs } from '@hanzo/docs-mdx/config';
|
|
import { defineOpenAPI } from '@hanzo/docs-openapi';
|
|
|
|
export default defineConfig({
|
|
docs: defineDocs({ dir: 'content/docs' }),
|
|
openapi: defineOpenAPI({
|
|
input: './openapi-specs/*.yaml',
|
|
output: './content/docs/api',
|
|
}),
|
|
});</code></pre>
|
|
<h4>Generated Output</h4>
|
|
<p>For each endpoint in the spec, the package generates:</p>
|
|
<ul><li><strong>Endpoint page</strong>: Method, path, description, parameters, request body, response schemas</li><li><strong>Interactive playground</strong>: Try-it-out form with authentication, parameter inputs, and live response</li><li><strong>Type schemas</strong>: Rendered as collapsible property tables with nested object support</li><li><strong>Code samples</strong>: Auto-generated cURL, JavaScript, Python, and Go examples</li></ul>
|
|
<h4>Scalar Integration</h4>
|
|
<p>For interactive API exploration, the OpenAPI package integrates with Scalar:</p>
|
|
<pre><code class="lang-typescript">import { createScalarPage } from '@hanzo/docs-openapi/scalar';
|
|
|
|
export default createScalarPage({
|
|
spec: './openapi-specs/hanzo-api.yaml',
|
|
theme: 'kepler',
|
|
});</code></pre>
|
|
<h3>TypeScript Type Documentation</h3>
|
|
<p>The <code>@hanzo/docs-typescript</code> package generates type tables from TypeScript declarations:</p>
|
|
<pre><code class="lang-tsx">import { AutoTypeTable } from '@hanzo/docs-typescript/ui';
|
|
|
|
// Automatically generates a property table from the TypeScript interface
|
|
<AutoTypeTable path="./src/types.ts" name="UserConfig" /></code></pre>
|
|
<p>This resolves the full type, including inherited properties, generics, and JSDoc comments. The output is a structured table showing property name, type, default value, and description.</p>
|
|
<h3>Python API Documentation</h3>
|
|
<p>The <code>@hanzo/docs-python</code> package includes a Python component (<code>fumapy</code>) that extracts docstrings and type annotations:</p>
|
|
<pre><code class="lang-bash"># Generate Python API docs
|
|
uv run fumapy generate --module hanzo.sdk --output content/docs/python-sdk</code></pre>
|
|
<p>The generated MDX files include function signatures, parameter tables, return types, and docstring content.</p>
|
|
<h3>Build Toolchain</h3>
|
|
<h4>Package Building</h4>
|
|
<p>All packages (except the <code>@hanzo/docs</code> wrapper) use <code>tsdown</code> for compilation:</p>
|
|
<pre><code class="lang-typescript">// packages/core/tsdown.config.ts
|
|
import { defineConfig } from 'tsdown';
|
|
|
|
export default defineConfig({
|
|
entry: ['src/**/*.ts', 'src/**/*.tsx'],
|
|
format: 'esm',
|
|
dts: true,
|
|
clean: true,
|
|
});</code></pre>
|
|
<p>The <code>@hanzo/docs</code> wrapper uses <code>tsup</code> because it needs special re-export handling.</p>
|
|
<h4>Monorepo Orchestration</h4>
|
|
<p>Turbo manages the build graph:</p>
|
|
<pre><code class="lang-json">{
|
|
"tasks": {
|
|
"build": {
|
|
"dependsOn": ["^build"],
|
|
"outputs": ["dist/**", ".next/**", "out"]
|
|
},
|
|
"dev": {
|
|
"cache": false,
|
|
"persistent": true
|
|
}
|
|
}
|
|
}</code></pre>
|
|
<p>The <code>^build</code> dependency ensures packages build before the apps that consume them.</p>
|
|
<h4>Application Building</h4>
|
|
<p>Documentation apps use Next.js with static export:</p>
|
|
<pre><code class="lang-typescript">// next.config.ts
|
|
import { createMDX } from '@hanzo/docs-mdx/next';
|
|
|
|
const withMDX = createMDX();
|
|
|
|
export default withMDX({
|
|
output: 'export', // Static HTML for CDN deployment
|
|
images: { unoptimized: true },
|
|
});</code></pre>
|
|
<h3>Deployment</h3>
|
|
<p>Documentation sites support three deployment targets:</p>
|
|
<h4>Vercel (Recommended for Dynamic Sites)</h4>
|
|
<p>Sites with server-side features (search API routes, ISR) deploy to Vercel:</p>
|
|
<pre><code class="lang-bash"># Automatic via GitHub integration
|
|
# Or manual:
|
|
vercel deploy --prod</code></pre>
|
|
<h4>Cloudflare Workers (Edge)</h4>
|
|
<p>For globally distributed static sites with edge functions:</p>
|
|
<pre><code class="lang-typescript">// open-next.config.ts (for Cloudflare adapter)
|
|
export default {
|
|
default: {
|
|
override: {
|
|
wrapper: 'cloudflare-node',
|
|
converter: 'edge',
|
|
},
|
|
},
|
|
};</code></pre>
|
|
<p>Deploy via Wrangler:</p>
|
|
<pre><code class="lang-bash">pnpm build && wrangler pages deploy out</code></pre>
|
|
<h4>Static Export (CDN / K8s)</h4>
|
|
<p>For maximum simplicity, export static HTML and serve from any HTTP server:</p>
|
|
<pre><code class="lang-bash">pnpm build # Produces ./out/ directory
|
|
# Serve via nginx, Caddy, or S3+CloudFront</code></pre>
|
|
<p>The <code>apps/bot-docs</code> and <code>apps/zt-docs</code> sites use this pattern with nginx in a Docker container:</p>
|
|
<pre><code class="lang-dockerfile">FROM node:20-alpine AS builder
|
|
WORKDIR /app
|
|
COPY . .
|
|
RUN pnpm install && pnpm build
|
|
|
|
FROM nginx:alpine
|
|
COPY --from=builder /app/out /usr/share/nginx/html
|
|
COPY nginx.conf /etc/nginx/conf.d/default.conf</code></pre>
|
|
<h3>App Structure for New Documentation Sites</h3>
|
|
<p>New documentation sites MUST follow this structure:</p>
|
|
<pre><code>apps/my-docs/
|
|
app/
|
|
layout.tsx # Root layout with DocsLayout
|
|
page.tsx # Landing page
|
|
docs/
|
|
[[...slug]]/
|
|
page.tsx # Dynamic docs page
|
|
api/
|
|
search/
|
|
route.ts # Search API endpoint
|
|
content/
|
|
docs/
|
|
index.mdx # Docs root page
|
|
getting-started.mdx
|
|
guides/
|
|
meta.json # Navigation ordering
|
|
installation.mdx
|
|
configuration.mdx
|
|
lib/
|
|
source.ts # Source loader configuration
|
|
source.config.ts # Content source definition
|
|
mdx-components.tsx # MDX component registration
|
|
next.config.ts # Next.js configuration with MDX
|
|
package.json
|
|
postcss.config.mjs
|
|
tsconfig.json</code></pre>
|
|
<p>The <code>@hanzo/docs-cli</code> can scaffold this structure:</p>
|
|
<pre><code class="lang-bash">npx @hanzo/docs-create-app my-docs</code></pre>
|
|
<h3>Upstream Sync Process</h3>
|
|
<p>The fork maintains compatibility with upstream Fumadocs. The sync process:</p>
|
|
<pre><code class="lang-bash"># 1. Fetch upstream changes
|
|
git remote add upstream https://github.com/fuma-nama/fumadocs.git # one-time
|
|
git fetch upstream
|
|
|
|
# 2. Create merge branch
|
|
git checkout -b merge-upstream-YYYY-MM-DD
|
|
|
|
# 3. Merge upstream dev branch
|
|
git merge upstream/dev
|
|
|
|
# 4. Resolve conflicts (usually in package.json names and brand-specific files)
|
|
|
|
# 5. Run bulk rename script
|
|
bash scripts/mirror-ui-change.sh
|
|
|
|
# 6. Verify build
|
|
pnpm install && pnpm build && pnpm test
|
|
|
|
# 7. Open PR for review</code></pre>
|
|
<p>The <code>scripts/setup-fork.sh</code> script automates creating brand-specific documentation forks for ecosystem partners.</p>
|
|
<h4>Rename Mapping</h4>
|
|
<p>During upstream sync, all references are renamed:</p>
|
|
<p>| Upstream Name | Hanzo Name | |--------------|------------| | <code>fumadocs-core</code> | <code>@hanzo/docs-core</code> | | <code>fumadocs-ui</code> | <code>@hanzo/docs-ui</code> | | <code>fumadocs-mdx</code> | <code>@hanzo/docs-mdx</code> | | <code>fumadocs-openapi</code> | <code>@hanzo/docs-openapi</code> | | <code>fumadocs-typescript</code> | <code>@hanzo/docs-typescript</code> | | <code>fumadocs-twoslash</code> | <code>@hanzo/docs-twoslash</code> | | <code>@fumadocs/cli</code> | <code>@hanzo/docs-cli</code> | | <code>@fumadocs/base-ui</code> | <code>@hanzo/docs-base-ui</code> | | <code>@fumadocs/story</code> | <code>@hanzo/docs-story</code> | | <code>@fumadocs/tailwind</code> | <code>@hanzo/docs-tailwind</code> | | <code>fumadocs-docgen</code> | <code>@hanzo/docs-docgen</code> |</p>
|
|
<p>Note: <code>packages/radix-ui</code> publishes as <code>@hanzo/docs-ui</code> (the primary UI package). The original <code>fumadocs-ui</code> name maps to this package.</p>
|
|
<h2>Implementation</h2>
|
|
<h3>Repository Structure</h3>
|
|
<pre><code>github.com/hanzoai/docs/
|
|
.changeset/ # Changeset configuration for versioning
|
|
.github/
|
|
workflows/
|
|
deploy-docs.yml # Deploy docs.hanzo.ai
|
|
deploy-zen-docs.yml # Deploy zenlm.org
|
|
deploy-zap-docs.yml # Deploy zap.hanzo.ai
|
|
deploy-bot-docs.yml # Deploy bot.hanzo.ai
|
|
lint.yml # Lint all packages
|
|
test.yml # Test all packages
|
|
release.yml # Publish to npm via changesets
|
|
apps/
|
|
docs/ # docs.hanzo.ai
|
|
zen-docs/ # zenlm.org
|
|
zap-docs/ # zap.hanzo.ai
|
|
bot-docs/ # bot.hanzo.ai
|
|
dev-docs/ # dev.hanzo.ai
|
|
cloud/ # cloud docs
|
|
flow/ # flow docs
|
|
zt-docs/ # zt docs
|
|
packages/ # 24 packages (see Package Architecture)
|
|
examples/ # 24 example applications
|
|
scripts/
|
|
build-all-docs.sh # Build all doc sites
|
|
dev-all-docs.sh # Run all doc sites in dev mode
|
|
mirror-ui-change.sh # Sync UI changes across radix-ui and base-ui
|
|
setup-fork.sh # Create branded doc forks
|
|
cf-pages-deploy.mjs # Cloudflare Pages deployment script
|
|
package.json # Root workspace configuration
|
|
pnpm-workspace.yaml # Workspace package declarations
|
|
turbo.json # Turbo build pipeline configuration
|
|
vitest.config.ts # Test configuration</code></pre>
|
|
<h3>Version Management</h3>
|
|
<p>Packages use <a href="https://github.com/changesets/changesets">Changesets</a> for version management:</p>
|
|
<pre><code class="lang-bash"># Add a changeset
|
|
pnpm changeset
|
|
|
|
# Version all changed packages
|
|
pnpm version
|
|
|
|
# Publish to npm
|
|
pnpm release</code></pre>
|
|
<p>The release process:</p>
|
|
<ol><li>Developer runs <code>pnpm changeset</code> and selects affected packages</li><li>CI runs <code>changeset version</code> to bump versions</li><li>CI runs <code>turbo run build --filter=./packages/*</code> to build all packages</li><li>CI runs <code>changeset publish</code> to push to npm</li><li>Packages with <code>postpublish</code> scripts run any post-publish tasks</li></ol>
|
|
<h3>Workspace Configuration</h3>
|
|
<pre><code class="lang-yaml"># pnpm-workspace.yaml
|
|
packages:
|
|
- packages/*
|
|
- apps/*
|
|
- examples/*</code></pre>
|
|
<p>All packages, apps, and examples are part of the workspace. Internal dependencies use <code>workspace:*</code> protocol for always-latest linking during development.</p>
|
|
<h3>CI/CD Workflows</h3>
|
|
<h4>Package Publishing (<code>release.yml</code>)</h4>
|
|
<p>Triggered on push to main. Uses changesets to determine which packages need publishing:</p>
|
|
<pre><code class="lang-yaml">name: Release
|
|
on:
|
|
push:
|
|
branches: [main]
|
|
jobs:
|
|
release:
|
|
runs-on: ubuntu-latest
|
|
steps:
|
|
- uses: actions/checkout@v4
|
|
- uses: pnpm/action-setup@v4
|
|
- uses: actions/setup-node@v4
|
|
with:
|
|
node-version: 20
|
|
cache: pnpm
|
|
- run: pnpm install
|
|
- uses: changesets/action@v1
|
|
with:
|
|
publish: pnpm release
|
|
env:
|
|
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
|
|
NPM_TOKEN: ${{ secrets.NPM_TOKEN }}</code></pre>
|
|
<h4>Site Deployment (<code>deploy-*.yml</code>)</h4>
|
|
<p>Each documentation site has its own deployment workflow. Example for <code>docs.hanzo.ai</code>:</p>
|
|
<pre><code class="lang-yaml">name: Deploy Docs
|
|
on:
|
|
push:
|
|
branches: [main]
|
|
paths:
|
|
- 'apps/docs/**'
|
|
- 'packages/**'
|
|
jobs:
|
|
deploy:
|
|
runs-on: ubuntu-latest
|
|
steps:
|
|
- uses: actions/checkout@v4
|
|
- uses: pnpm/action-setup@v4
|
|
- run: pnpm install
|
|
- run: pnpm build --filter docs
|
|
- uses: cloudflare/pages-deploy-action@v1
|
|
with:
|
|
directory: apps/docs/out
|
|
project-name: hanzo-docs</code></pre>
|
|
<h3>Compatibility Matrix</h3>
|
|
<p>| Dependency | Minimum Version | Tested Version | |-----------|----------------|----------------| | Node.js | 18.17.0 | 20.x, 22.x | | Next.js | 15.3.0 | 16.1.x | | React | 19.2.0 | 19.2.x | | Tailwind CSS | 4.0.0 | 4.1.x | | pnpm | 10.0.0 | 10.18.x | | TypeScript | 5.5.0 | 5.9.x |</p>
|
|
<h3>Configuration Files</h3>
|
|
<p>Every documentation app requires these configuration files:</p>
|
|
<h4><code>next.config.ts</code></h4>
|
|
<pre><code class="lang-typescript">import { createMDX } from '@hanzo/docs-mdx/next';
|
|
|
|
const withMDX = createMDX();
|
|
|
|
export default withMDX({
|
|
output: 'export',
|
|
});</code></pre>
|
|
<h4><code>postcss.config.mjs</code></h4>
|
|
<pre><code class="lang-javascript">export default {
|
|
plugins: {
|
|
'@tailwindcss/postcss': {},
|
|
},
|
|
};</code></pre>
|
|
<h4><code>mdx-components.tsx</code></h4>
|
|
<pre><code class="lang-tsx">import type { MDXComponents } from 'mdx/types';
|
|
import defaultComponents from '@hanzo/docs-ui/mdx';
|
|
|
|
export function useMDXComponents(components: MDXComponents): MDXComponents {
|
|
return {
|
|
...defaultComponents,
|
|
...components,
|
|
};
|
|
}</code></pre>
|
|
<h2>Security</h2>
|
|
<h3>Content Security</h3>
|
|
<ul><li><strong>No arbitrary code execution</strong>: MDX files are compiled at build time, not runtime. User-submitted content cannot execute arbitrary JavaScript.</li><li><strong>Sanitized HTML</strong>: The <code>rehype-raw</code> plugin processes inline HTML through a sanitizer before rendering.</li><li><strong>No secrets in content</strong>: Documentation content MUST NOT contain API keys, tokens, or credentials. Example code MUST use placeholder values (<code>sk-...</code>, <code>your-api-key</code>).</li></ul>
|
|
<h3>Dependency Security</h3>
|
|
<ul><li><strong>Dependabot enabled</strong>: The repository uses Renovate for automated dependency updates.</li><li><strong>npm provenance</strong>: Published packages include npm provenance attestations.</li><li><strong>Lockfile integrity</strong>: The <code>pnpm-lock.yaml</code> is committed and verified in CI.</li></ul>
|
|
<h3>Deployment Security</h3>
|
|
<ul><li><strong>Static export preferred</strong>: Static HTML has no server-side attack surface.</li><li><strong>CSP headers</strong>: All deployed sites MUST include Content Security Policy headers restricting script sources.</li><li><strong>HTTPS only</strong>: All documentation sites are served over HTTPS with HSTS enabled.</li></ul>
|
|
<h2>Monitoring and Observability</h2>
|
|
<h3>Build Metrics</h3>
|
|
<p>| Metric | Description | Target | |--------|-------------|--------| | <code>docs.build.duration_seconds</code> | Full build time for a documentation site | < 120s | | <code>docs.package.build_seconds</code> | Individual package build time | < 30s | | <code>docs.bundle.size_kb</code> | Client-side JavaScript bundle size | < 250KB | | <code>docs.pages.count</code> | Total pages across all sites | Informational | | <code>docs.search.index_size_kb</code> | Search index size | < 5MB per site |</p>
|
|
<h3>Lighthouse Targets</h3>
|
|
<p>All documentation sites MUST meet these Lighthouse scores:</p>
|
|
<p>| Category | Minimum Score | |----------|--------------| | Performance | 90 | | Accessibility | 95 | | Best Practices | 95 | | SEO | 95 |</p>
|
|
<h3>Uptime</h3>
|
|
<p>Documentation sites are monitored via the Hanzo status page. Target uptime: 99.9%.</p>
|
|
<pre><code class="lang-bash"># 1. Scaffold a new docs site
|
|
npx @hanzo/docs-create-app my-docs
|
|
|
|
# 2. Install dependencies
|
|
cd my-docs && pnpm install
|
|
|
|
# 3. Add content
|
|
# Create .mdx files in content/docs/
|
|
|
|
# 4. Run development server
|
|
pnpm dev
|
|
|
|
# 5. Build for production
|
|
pnpm build</code></pre>
|
|
<h2>Future Work</h2>
|
|
<h3>Phase 4: Automation (Q4 2026)</h3>
|
|
<ul><li>Auto-generate SDK documentation from source code (Go, Python, TypeScript, Rust)</li><li>Auto-sync API docs when OpenAPI specs change in CI</li><li>AI-assisted content generation for boilerplate documentation</li><li>Automated broken link detection and content freshness scoring</li></ul>
|
|
<h2>References</h2>
|
|
<ol><li><a href="https://fumadocs.dev">Fumadocs Documentation</a> -- Upstream framework</li><li><a href="https://github.com/hanzoai/docs">Hanzo Docs Repository</a> -- Source code</li><li><a href="https://nextjs.org/docs/app">Next.js App Router Documentation</a></li><li><a href="https://mdxjs.com/">MDX Documentation</a></li><li><a href="https://www.radix-ui.com/">Radix UI Primitives</a></li><li><a href="https://docs.orama.com/">Orama Search Engine</a></li><li><a href="https://github.com/changesets/changesets">Changesets Version Management</a></li><li><a href="https://turbo.build/">Turbo Build System</a></li><li><a href="./hip-0010-model-context-protocol-mcp-integration-standards.md">HIP-0010: Model Context Protocol Integration Standards</a></li><li><a href="./hip-1147-search-hybrid-retrieval.md">HIP-1147: Search — Hybrid Retrieval</a></li><li><a href="./hip-0036-ci-cd-build-system-standard.md">HIP-0036: CI/CD Build System Standard</a></li></ol>
|
|
<h2>Copyright</h2>
|
|
<p>Copyright and related rights waived via <a href="https://creativecommons.org/publicdomain/zero/1.0/">CC0</a>.</p>
|
|
<footer>
|
|
<div class="fmap">
|
|
<div><b>Build</b>
|
|
<a href="https://hanzo.app">hanzo.app</a> app builder
|
|
<a href="https://hanzo.codes">hanzo.codes</a> code with an agent
|
|
<a href="https://hanzoskills.com">hanzoskills.com</a> what an agent reads</div>
|
|
<div><b>Run</b>
|
|
<a href="https://console.hanzo.ai">console.hanzo.ai</a> cloud console
|
|
<a href="https://api.hanzo.ai">api.hanzo.ai</a> the API</div>
|
|
<div><b>Account</b>
|
|
<a href="https://hanzo.id">hanzo.id</a> sign in
|
|
<a href="https://pay.hanzo.ai">pay.hanzo.ai</a> top up
|
|
<a href="https://billing.hanzo.ai">billing.hanzo.ai</a> invoices and usage</div>
|
|
<div><b>Company</b>
|
|
<a href="https://hanzo.ai">hanzo.ai</a> canonical
|
|
<a href="https://hanzo.ventures">hanzo.ventures</a> ventures</div>
|
|
</div>
|
|
<div class="fend"><a href="/hip-0045.md">This page as plain text</a> · <a href="/llms.txt">Index for agents</a></div>
|
|
</footer>
|
|
</div></body></html> |