@clarify-labs/templates 0.5.0

package/output/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","names":[],"sources":["../index.ts"],"sourcesContent":["import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from 'node:fs'\nimport { dirname, relative, resolve } from 'node:path'\n\nexport const supportedTemplates = ['minimal', 'standard', 'complete'] as const\n\nexport type ClarifyTemplate = typeof supportedTemplates[number]\n\nexport type TemplateVariables = {\n  contentDir: string\n}\n\nexport type TemplateCopyOptions = {\n  contentDir: string\n  force?: boolean\n  variables?: Partial<TemplateVariables>\n}\n\nexport type TemplateCopyResult = {\n  created: string[]\n}\n\nexport class TemplateConflictError extends Error {\n  constructor(public readonly conflicts: string[]) {\n    super(`[clarify] Init target has conflicting files:\\n${conflicts.map(file => `  - ${file}`).join('\\n')}\\nUse --force to overwrite them.`)\n    this.name = 'TemplateConflictError'\n  }\n}\n\nexport function resolveTemplate(template?: string): ClarifyTemplate {\n  const selectedTemplate = template ?? 'standard'\n  if (supportedTemplates.includes(selectedTemplate as ClarifyTemplate)) return selectedTemplate as ClarifyTemplate\n  throw new Error(`[clarify] Unknown template \"${selectedTemplate}\". Available templates: ${supportedTemplates.join(', ')}.`)\n}\n\nexport function getTemplateDirectory(templatesDirectory: string, template: ClarifyTemplate): string {\n  return resolve(templatesDirectory, template)\n}\n\nexport function renderTemplate(content: string, variables: TemplateVariables): string {\n  return content.replaceAll('{{contentDir}}', variables.contentDir)\n}\n\nexport function toTemplateTargetPath(relativePath: string, contentDir: string): string {\n  return relativePath.replace(/^source(?=\\/|$)/, contentDir)\n}\n\nexport function copyTemplateDirectory(templateDirectory: string, targetDirectory: string, options: TemplateCopyOptions): TemplateCopyResult {\n  const created: string[] = []\n  const variables = {\n    contentDir: options.contentDir,\n    ...options.variables,\n  }\n\n  if (options.force !== true) {\n    const conflicts = findTemplateConflicts(templateDirectory, targetDirectory, options.contentDir)\n    if (conflicts.length > 0) throw new TemplateConflictError(conflicts)\n  }\n\n  copyDirectory(templateDirectory, templateDirectory, targetDirectory, options.contentDir, variables, created)\n\n  return { created }\n}\n\nfunction findTemplateConflicts(templateDirectory: string, targetDirectory: string, contentDir: string): string[] {\n  const conflicts: string[] = []\n  collectTemplateConflicts(templateDirectory, templateDirectory, targetDirectory, contentDir, conflicts)\n  return conflicts\n}\n\nfunction collectTemplateConflicts(templateDirectory: string, sourceDirectory: string, targetDirectory: string, contentDir: string, conflicts: string[]): void {\n  for (const entry of readdirSync(sourceDirectory, { withFileTypes: true })) {\n    const sourcePath = resolve(sourceDirectory, entry.name)\n    const sourceRelativePath = relative(templateDirectory, sourcePath)\n    const targetRelativePath = toTemplateTargetPath(sourceRelativePath, contentDir)\n    const targetPath = resolve(targetDirectory, targetRelativePath)\n\n    if (entry.isDirectory()) {\n      collectTemplateConflicts(templateDirectory, sourcePath, targetDirectory, contentDir, conflicts)\n      continue\n    }\n\n    if (entry.isFile() && existsSync(targetPath)) conflicts.push(targetRelativePath)\n  }\n}\n\nfunction copyDirectory(templateDirectory: string, sourceDirectory: string, targetDirectory: string, contentDir: string, variables: TemplateVariables, created: string[]): void {\n  for (const entry of readdirSync(sourceDirectory, { withFileTypes: true })) {\n    const sourcePath = resolve(sourceDirectory, entry.name)\n    const sourceRelativePath = relative(templateDirectory, sourcePath)\n    const targetRelativePath = toTemplateTargetPath(sourceRelativePath, contentDir)\n    const targetPath = resolve(targetDirectory, targetRelativePath)\n\n    if (entry.isDirectory()) {\n      copyDirectory(templateDirectory, sourcePath, targetDirectory, contentDir, variables, created)\n      continue\n    }\n\n    if (!entry.isFile()) continue\n\n    const content = renderTemplate(readFileSync(sourcePath, 'utf-8'), variables)\n    mkdirSync(dirname(targetPath), { recursive: true })\n    writeFileSync(targetPath, content, 'utf-8')\n    created.push(targetRelativePath)\n  }\n}\n"],"mappings":";;;AAGA,IAAa,qBAAqB;CAAC;CAAW;CAAY;AAAU;AAkBpE,IAAa,wBAAb,cAA2C,MAAM;CACnB;CAA5B,YAAY,WAAqC;EAC/C,MAAM,iDAAiD,UAAU,KAAI,SAAQ,OAAO,MAAM,EAAE,KAAK,IAAI,EAAE,iCAAiC;EAD9G,KAAA,YAAA;EAE1B,KAAK,OAAO;CACd;AACF;AAEA,SAAgB,gBAAgB,UAAoC;CAClE,MAAM,mBAAmB,YAAY;CACrC,IAAI,mBAAmB,SAAS,gBAAmC,GAAG,OAAO;CAC7E,MAAM,IAAI,MAAM,+BAA+B,iBAAiB,0BAA0B,mBAAmB,KAAK,IAAI,EAAE,EAAE;AAC5H;AAEA,SAAgB,qBAAqB,oBAA4B,UAAmC;CAClG,OAAO,QAAQ,oBAAoB,QAAQ;AAC7C;AAEA,SAAgB,eAAe,SAAiB,WAAsC;CACpF,OAAO,QAAQ,WAAW,kBAAkB,UAAU,UAAU;AAClE;AAEA,SAAgB,qBAAqB,cAAsB,YAA4B;CACrF,OAAO,aAAa,QAAQ,mBAAmB,UAAU;AAC3D;AAEA,SAAgB,sBAAsB,mBAA2B,iBAAyB,SAAkD;CAC1I,MAAM,UAAoB,CAAC;CAC3B,MAAM,YAAY;EAChB,YAAY,QAAQ;EACpB,GAAG,QAAQ;CACb;CAEA,IAAI,QAAQ,UAAU,MAAM;EAC1B,MAAM,YAAY,sBAAsB,mBAAmB,iBAAiB,QAAQ,UAAU;EAC9F,IAAI,UAAU,SAAS,GAAG,MAAM,IAAI,sBAAsB,SAAS;CACrE;CAEA,cAAc,mBAAmB,mBAAmB,iBAAiB,QAAQ,YAAY,WAAW,OAAO;CAE3G,OAAO,EAAE,QAAQ;AACnB;AAEA,SAAS,sBAAsB,mBAA2B,iBAAyB,YAA8B;CAC/G,MAAM,YAAsB,CAAC;CAC7B,yBAAyB,mBAAmB,mBAAmB,iBAAiB,YAAY,SAAS;CACrG,OAAO;AACT;AAEA,SAAS,yBAAyB,mBAA2B,iBAAyB,iBAAyB,YAAoB,WAA2B;CAC5J,KAAK,MAAM,SAAS,YAAY,iBAAiB,EAAE,eAAe,KAAK,CAAC,GAAG;EACzE,MAAM,aAAa,QAAQ,iBAAiB,MAAM,IAAI;EAEtD,MAAM,qBAAqB,qBADA,SAAS,mBAAmB,UACP,GAAoB,UAAU;EAC9E,MAAM,aAAa,QAAQ,iBAAiB,kBAAkB;EAE9D,IAAI,MAAM,YAAY,GAAG;GACvB,yBAAyB,mBAAmB,YAAY,iBAAiB,YAAY,SAAS;GAC9F;EACF;EAEA,IAAI,MAAM,OAAO,KAAK,WAAW,UAAU,GAAG,UAAU,KAAK,kBAAkB;CACjF;AACF;AAEA,SAAS,cAAc,mBAA2B,iBAAyB,iBAAyB,YAAoB,WAA8B,SAAyB;CAC7K,KAAK,MAAM,SAAS,YAAY,iBAAiB,EAAE,eAAe,KAAK,CAAC,GAAG;EACzE,MAAM,aAAa,QAAQ,iBAAiB,MAAM,IAAI;EAEtD,MAAM,qBAAqB,qBADA,SAAS,mBAAmB,UACP,GAAoB,UAAU;EAC9E,MAAM,aAAa,QAAQ,iBAAiB,kBAAkB;EAE9D,IAAI,MAAM,YAAY,GAAG;GACvB,cAAc,mBAAmB,YAAY,iBAAiB,YAAY,WAAW,OAAO;GAC5F;EACF;EAEA,IAAI,CAAC,MAAM,OAAO,GAAG;EAErB,MAAM,UAAU,eAAe,aAAa,YAAY,OAAO,GAAG,SAAS;EAC3E,UAAU,QAAQ,UAAU,GAAG,EAAE,WAAW,KAAK,CAAC;EAClD,cAAc,YAAY,SAAS,OAAO;EAC1C,QAAQ,KAAK,kBAAkB;CACjC;AACF"}

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@clarify-labs/templates",
+  "version": "0.5.0",
+  "license": "AGPL-3.0-only",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/taicode-labs/clarify",
+    "directory": "packages/templates"
+  },
+  "main": "output/index.cjs",
+  "module": "output/index.js",
+  "types": "output/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./output/index.d.ts",
+      "import": "./output/index.js",
+      "require": "./output/index.cjs",
+      "default": "./output/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "LICENSE",
+    "minimal",
+    "standard",
+    "complete",
+    "output"
+  ],
+  "scripts": {
+    "build": "vite build",
+    "lint": "eslint index.ts",
+    "lint:fix": "eslint index.ts --fix",
+    "typecheck": "tsc -p tsconfig.json --noEmit"
+  },
+  "devDependencies": {
+    "@types/node": "^24.0.0",
+    "typescript": "^5.8.3",
+    "vite": "^8.0.15",
+    "vite-plugin-dts": "^4.5.4"
+  }
+}

package/standard/clarify.ts

@@ -0,0 +1,57 @@
+import { defineConfig } from '@clarify-labs/cli'
+
+export default defineConfig({
+  title: 'Clarify Docs',
+  description: 'A documentation starter powered by Clarify.',
+  logo: '/logo.svg',
+  favicon: '/favicon.svg',
+  banner: {
+    content: 'Edit this starter in {{contentDir}} and ship your docs with Clarify.',
+    dismissible: true,
+  },
+  theme: {
+    preset: 'default',
+    tokens: {
+      colors: {
+        primary: '#00D492',
+        accent: '#00F6C9',
+      },
+    },
+  },
+  navbar: {
+    links: [
+      { label: 'Guides', href: '/guides/writing-content' },
+      { label: 'Changelog', href: '/changelog' },
+      { label: 'GitHub', href: 'https://github.com/taicode-labs/clarify', external: true },
+    ],
+  },
+  footer: {
+    copyright: '© 2026 Your Company. Built with Clarify.',
+    links: [
+      { label: 'Get started', href: '/' },
+      { label: 'Writing content', href: '/guides/writing-content' },
+      { label: 'Changelog', href: '/changelog' },
+    ],
+    socials: {
+      GitHub: 'https://github.com/taicode-labs/clarify',
+    },
+  },
+  tabs: [
+    {
+      tab: 'Docs',
+      icon: 'BookOpen',
+      pages: [
+        {
+          group: 'Start here',
+          icon: 'Rocket',
+          pages: [
+            { page: 'index', title: 'Overview', icon: 'Sparkles' },
+            { page: 'guides/writing-content', title: 'Writing content', icon: 'PenLine' },
+            { page: 'guides/navigation', title: 'Navigation', icon: 'PanelLeft' },
+            { page: 'changelog', title: 'Changelog', icon: 'History' },
+          ],
+        },
+      ],
+    },
+  ],
+})

package/standard/index.html

@@ -0,0 +1,11 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Clarify Docs</title>
+  </head>
+  <body>
+    <div id="root"></div>
+  </body>
+</html>

package/standard/public/favicon.svg

@@ -0,0 +1,11 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<svg width="279px" height="200px" viewBox="0 0 279 200" version="1.1" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink">
+    <title>clarify</title>
+    <g id="页面-1" stroke="none" stroke-width="1" fill="none" fill-rule="evenodd">
+        <g id="clarify" transform="translate(-0, 0.0054)">
+            <path d="M44.867217,0.0054376148 C130.715579,1.00591567 200,70.9091172 200,156.994562 L199.986321,155.127494 C199.384888,180.009127 179.026368,199.994562 154,199.994562 L46,199.994562 C20.5949015,199.994562 0,179.399661 0,153.994562 L0,45.9945624 C0,21.0975659 19.7793434,0.820282524 44.4815926,0.0191499894 Z" fill="#00D492"></path>
+            <path d="M123.867217,0.0054376148 C209.715579,1.00591567 279,70.9091172 279,156.994562 L278.986321,155.127494 C278.384888,180.009127 258.026368,199.994562 233,199.994562 L125,199.994562 C99.5949015,199.994562 79,179.399661 79,153.994562 L79,45.9945624 C79,21.0975659 98.7793434,0.820282524 123.481593,0.0191499894 Z" id="clarify-right" fill-opacity="0.6" fill="#00F6C9" transform="translate(179, 100) rotate(-90) translate(-179, -100)"></path>
+            <path d="M199.979267,154.416906 L199.984438,155.157125 L199.962366,155.872459 C198.977251,180.406837 178.776104,199.994562 154,199.994562 L124.372438,199.994125 L124.249053,199.994081 C99.6939678,199.603921 79.8122712,179.973634 79.01915,155.518407 L79.0054376,155.132783 C79.5830823,105.566626 103.129768,61.5221348 139.498462,33.1463428 C175.69419,61.3871018 199.186123,105.143863 199.979267,154.416906 Z" id="形状结合" fill="#00F692"></path>
+        </g>
+    </g>
+</svg>

package/standard/public/logo.svg

@@ -0,0 +1,11 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<svg width="279px" height="200px" viewBox="0 0 279 200" version="1.1" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink">
+    <title>clarify</title>
+    <g id="页面-1" stroke="none" stroke-width="1" fill="none" fill-rule="evenodd">
+        <g id="clarify" transform="translate(-0, 0.0054)">
+            <path d="M44.867217,0.0054376148 C130.715579,1.00591567 200,70.9091172 200,156.994562 L199.986321,155.127494 C199.384888,180.009127 179.026368,199.994562 154,199.994562 L46,199.994562 C20.5949015,199.994562 0,179.399661 0,153.994562 L0,45.9945624 C0,21.0975659 19.7793434,0.820282524 44.4815926,0.0191499894 Z" fill="#00D492"></path>
+            <path d="M123.867217,0.0054376148 C209.715579,1.00591567 279,70.9091172 279,156.994562 L278.986321,155.127494 C278.384888,180.009127 258.026368,199.994562 233,199.994562 L125,199.994562 C99.5949015,199.994562 79,179.399661 79,153.994562 L79,45.9945624 C79,21.0975659 98.7793434,0.820282524 123.481593,0.0191499894 Z" id="clarify-right" fill-opacity="0.6" fill="#00F6C9" transform="translate(179, 100) rotate(-90) translate(-179, -100)"></path>
+            <path d="M199.979267,154.416906 L199.984438,155.157125 L199.962366,155.872459 C198.977251,180.406837 178.776104,199.994562 154,199.994562 L124.372438,199.994125 L124.249053,199.994081 C99.6939678,199.603921 79.8122712,179.973634 79.01915,155.518407 L79.0054376,155.132783 C79.5830823,105.566626 103.129768,61.5221348 139.498462,33.1463428 C175.69419,61.3871018 199.186123,105.143863 199.979267,154.416906 Z" id="形状结合" fill="#00F692"></path>
+        </g>
+    </g>
+</svg>

package/standard/source/changelog.mdx

@@ -0,0 +1,20 @@
+---
+title: Changelog
+description: Track notable product and documentation changes.
+---
+
+# Changelog
+
+Use this page to publish notable product, API, and documentation updates.
+
+## 2026-06-20
+
+### Added
+
+- Initial Clarify documentation starter.
+- Basic MDX authoring examples.
+- OpenAPI reference example.
+
+### Changed
+
+- Replace these entries with your real release notes.

package/standard/source/guides/navigation.mdx

@@ -0,0 +1,70 @@
+---
+title: Navigation
+description: Configure tabs, sidebar groups, page links, navbar links, and footer links.
+---
+
+# Navigation
+
+Clarify navigation is configured in `clarify.ts`. The starter uses explicit tabs so users can see how every part fits together.
+
+## Tabs and sidebar groups
+
+```ts title="clarify.ts"
+export default defineConfig({
+  tabs: [
+    {
+      tab: 'Docs',
+      icon: 'BookOpen',
+      pages: [
+        {
+          group: 'Start here',
+          icon: 'Rocket',
+          pages: [
+            { page: 'index', title: 'Overview', icon: 'Sparkles' },
+            { page: 'guides/writing-content', title: 'Writing content', icon: 'PenLine' },
+            { page: 'changelog', title: 'Changelog', icon: 'History' },
+          ],
+        },
+      ],
+    },
+  ],
+})
+```
+
+## File tree mode
+
+For smaller docs, use `FileTree` and let Clarify derive navigation from files.
+
+```ts title="clarify.ts"
+export default defineConfig({
+  tabs: [
+    {
+      tab: 'Docs',
+      pages: 'FileTree',
+    },
+  ],
+})
+```
+
+## Navbar and footer
+
+```ts title="clarify.ts"
+export default defineConfig({
+  navbar: {
+    links: [
+      { label: 'Guides', href: '/guides/writing-content' },
+      { label: 'Changelog', href: '/changelog' },
+      { label: 'GitHub', href: 'https://github.com/taicode-labs/clarify', external: true },
+    ],
+  },
+  footer: {
+    copyright: '© 2026 Your Company.',
+    links: [{ label: 'Changelog', href: '/changelog' }],
+    socials: { GitHub: 'https://github.com/taicode-labs/clarify' },
+  },
+})
+```
+
+## Next step
+
+If your docs need an API reference, initialize the `complete` template or add an OpenAPI file and navigation entry later.

package/standard/source/guides/writing-content.mdx

@@ -0,0 +1,102 @@
+---
+title: Writing content
+description: Learn the Clarify MDX patterns included in the starter template.
+---
+
+# Writing content
+
+Clarify pages are MDX files. You can start with plain Markdown and add components when a page needs richer structure.
+
+## Frontmatter
+
+Use frontmatter to control page metadata.
+
+```mdx title="page.mdx"
+---
+title: Writing content
+description: Explain how authors write documentation.
+keywords:
+  - mdx
+  - docs
+---
+
+# Writing content
+```
+
+## Callouts
+
+<Callout title="Use callouts for important notes">
+  Callouts are useful for setup requirements, warnings, migration notes, and product constraints.
+</Callout>
+
+<Note>
+  `Note` is a lightweight MDX primitive for contextual information inside a section.
+</Note>
+
+## Cards
+
+<CardGroup cols={3}>
+  <Card title="Concept" icon="Lightbulb">
+    Explain the idea behind a feature.
+  </Card>
+  <Card title="Guide" icon="Route">
+    Walk users through a workflow step by step.
+  </Card>
+  <Card title="Reference" icon="Library">
+    Document exact options, props, commands, or API shapes.
+  </Card>
+</CardGroup>
+
+## Code groups
+
+Use code groups when users need package-manager or framework variants.
+
+<CodeGroup title="Install dependencies">
+
+```bash title="pnpm"
+pnpm add @clarify-labs/cli
+```
+
+```bash title="npm"
+npm install @clarify-labs/cli
+```
+
+```bash title="bun"
+bun add @clarify-labs/cli
+```
+
+</CodeGroup>
+
+## Properties
+
+Use properties for configuration, component props, environment variables, or response fields.
+
+<Properties>
+  <Property name="title" type="string">
+    Site title used in the header and SEO metadata.
+  </Property>
+  <Property name="description" type="string">
+    Default description used for pages without a custom description.
+  </Property>
+  <Property name="tabs" type="ClarifyTabsConfig">
+    Top-level navigation areas. Each tab owns its sidebar groups and pages.
+  </Property>
+</Properties>
+
+## Two-column layout
+
+<Row>
+  <Col>
+    ### Explain the workflow
+
+    Put prose, diagrams, and decisions in the left column. This keeps the guide readable.
+  </Col>
+  <Col sticky>
+    ```ts title="example.ts"
+    export const docs = {
+      format: 'MDX',
+      api: 'OpenAPI',
+    }
+    ```
+  </Col>
+</Row>

package/standard/source/index.mdx

@@ -0,0 +1,77 @@
+---
+title: Overview
+description: A standard starter showing the common Clarify docs workflow.
+keywords:
+  - documentation
+  - mdx
+  - guides
+---
+
+# Build documentation with Clarify
+
+This standard starter includes a practical site configuration, navigation, MDX pages, built-in components, and a changelog. Use it as a clean starting point for product docs, internal docs, or project guides.
+
+<Callout title="Starter tip">
+  All editable content lives in `{{contentDir}}`. Start with `clarify.ts` for site structure, then edit the MDX pages.
+</Callout>
+
+## What is included
+
+<CardGroup cols={2}>
+  <Card title="Site configuration" icon="Settings2" href="/guides/navigation">
+    Navbar links, footer links, banner, theme tokens, tabs, sidebar groups, and Clarify branding.
+  </Card>
+  <Card title="MDX authoring" icon="PenLine" href="/guides/writing-content">
+    Frontmatter, headings, cards, callouts, code groups, properties, and layout primitives.
+  </Card>
+  <Card title="Navigation guide" icon="PanelLeft" href="/guides/navigation">
+    Learn how to edit tabs, sidebar groups, navbar links, and footer links.
+  </Card>
+  <Card title="Changelog" icon="History" href="/changelog">
+    A simple page for documenting notable product and documentation changes.
+  </Card>
+</CardGroup>
+
+## Quick edits
+
+1. Update `clarify.ts` with your product name, theme, navbar, footer, tabs, and sidebar pages.
+2. Replace pages under `{{contentDir}}/guides` with your real documentation.
+3. Update `{{contentDir}}/changelog.mdx` with your release notes.
+4. Run `pnpm dev` to preview and `pnpm build` to create the static site.
+
+## Example workflow
+
+<Row>
+  <Col>
+    ### Write docs in MDX
+
+    Use Markdown for normal documentation and MDX components for richer product explanations.
+
+    <Properties>
+      <Property name="Frontmatter" type="YAML">
+        Page metadata such as `title`, `description`, and `keywords`.
+      </Property>
+      <Property name="Navigation" type="clarify.ts">
+        Tabs, groups, page links, icons, and top-level links.
+      </Property>
+      <Property name="Content" type="MDX">
+        Pages under `{{contentDir}}` become routes in the generated documentation site.
+      </Property>
+    </Properties>
+  </Col>
+  <Col sticky>
+    ```ts title="clarify.ts"
+    import { defineConfig } from '@clarify-labs/cli'
+
+    export default defineConfig({
+      title: 'Your Docs',
+      tabs: [
+        {
+          tab: 'Docs',
+          pages: 'FileTree',
+        },
+      ],
+    })
+    ```
+  </Col>
+</Row>