@clarify-labs/templates 0.5.0

package/LICENSE

@@ -0,0 +1 @@
+Clarify template assets are distributed under the same license as this repository.

package/complete/clarify.ts

@@ -0,0 +1,94 @@
+import { defineConfig } from '@clarify-labs/cli'
+
+export default defineConfig({
+  title: 'Clarify Docs',
+  description: 'A full-featured documentation starter powered by Clarify.',
+  logo: '/logo.svg',
+  favicon: '/favicon.svg',
+  banner: {
+    content: {
+      'en-US': 'Edit this starter in {{contentDir}} and ship your docs with Clarify.',
+      'zh-CN': '在 {{contentDir}} 中编辑这个多语言模板，并使用 Clarify 发布文档。',
+    },
+    dismissible: true,
+  },
+  i18n: {
+    defaultLocale: 'en-US',
+    missing: 'fallback',
+    locales: [
+      { code: 'en-US', label: 'English' },
+      { code: 'zh-CN', label: '简体中文' },
+    ],
+  },
+  theme: {
+    preset: 'default',
+    tokens: {
+      colors: {
+        primary: '#2563eb',
+        accent: '#7c3aed',
+      },
+      radius: {
+        lg: '0.75rem',
+        xl: '1rem',
+      },
+    },
+  },
+  navbar: {
+    links: [
+      { label: { 'en-US': 'Guides', 'zh-CN': '指南' }, href: '/guides/writing-content' },
+      { label: { 'en-US': 'API', 'zh-CN': '接口' }, href: '/api' },
+      { label: 'GitHub', href: 'https://github.com/taicode-labs/clarify', external: true },
+    ],
+  },
+  footer: {
+    copyright: '© 2026 Your Company. Built with Clarify.',
+    links: [
+      { label: { 'en-US': 'Get started', 'zh-CN': '开始使用' }, href: '/' },
+      { label: { 'en-US': 'Configuration', 'zh-CN': '配置' }, href: '/reference/configuration' },
+      { label: { 'en-US': 'API reference', 'zh-CN': 'API 参考' }, href: '/api' },
+    ],
+    socials: {
+      GitHub: 'https://github.com/taicode-labs/clarify',
+    },
+  },
+  tabs: [
+    {
+      tab: { 'en-US': 'Docs', 'zh-CN': '文档' },
+      icon: 'BookOpen',
+      pages: [
+        {
+          group: { 'en-US': 'Start here', 'zh-CN': '从这里开始' },
+          icon: 'Rocket',
+          pages: [
+            { page: 'index', title: { 'en-US': 'Overview', 'zh-CN': '概览' }, icon: 'Sparkles' },
+            { page: 'guides/writing-content', title: { 'en-US': 'Writing content', 'zh-CN': '编写内容' }, icon: 'PenLine' },
+            { page: 'guides/navigation', title: { 'en-US': 'Navigation', 'zh-CN': '导航' }, icon: 'PanelLeft' },
+          ],
+        },
+        {
+          group: { 'en-US': 'Reference', 'zh-CN': '参考' },
+          icon: 'Library',
+          pages: [
+            { page: 'reference/configuration', title: { 'en-US': 'Configuration', 'zh-CN': '配置' }, icon: 'Settings2' },
+            { page: 'reference/components', title: { 'en-US': 'MDX components', 'zh-CN': 'MDX 组件' }, icon: 'Component' },
+            { page: 'changelog', title: { 'en-US': 'Changelog', 'zh-CN': '更新日志' }, icon: 'History' },
+          ],
+        },
+      ],
+    },
+    {
+      tab: { 'en-US': 'API', 'zh-CN': '接口' },
+      icon: 'Webhook',
+      pages: [
+        {
+          group: { 'en-US': 'API reference', 'zh-CN': 'API 参考' },
+          icon: 'FileJson2',
+          pages: [
+            { openapi: 'api.openapi.json', title: { 'en-US': 'OpenAPI reference', 'zh-CN': 'OpenAPI 参考' }, icon: 'FileJson2' },
+            { page: 'api/embedding', title: { 'en-US': 'Embed API endpoints', 'zh-CN': '嵌入 API 端点' }, icon: 'CodeXml' },
+          ],
+        },
+      ],
+    },
+  ],
+})

package/complete/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/complete/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/complete/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/complete/source/en-US/api/embedding.mdx

@@ -0,0 +1,46 @@
+---
+title: Embed API endpoints
+description: Render OpenAPI operations inside workflow-focused MDX pages.
+---
+
+# Embed API endpoints
+
+Use embedded OpenAPI components when an endpoint belongs next to a tutorial, setup guide, or integration workflow.
+
+## Markdown descriptions
+
+OpenAPI `description` strings render Markdown in both full references and embedded operations. This keeps interface notes close to the spec while preserving links, lists, emphasis, and `inline code`.
+
+```json
+{
+  "description": "Returns **active** projects.\n\n- Use `limit` for page size.\n- Use `nextCursor` for pagination."
+}
+```
+
+## Embed one operation
+
+```mdx
+<OpenApiOperation specPath="/api" path="/v1/projects" method="get" />
+```
+
+<OpenApiOperation specPath="/api" path="/v1/projects" method="get" />
+
+## Embed a request body operation
+
+```mdx
+<OpenApiOperation specPath="/api" path="/v1/projects" method="post" />
+```
+
+<OpenApiOperation specPath="/api" path="/v1/projects" method="post" />
+
+## Embed the full API page
+
+Use `OpenApiDocument` if you want prose before a complete reference.
+
+```mdx
+<OpenApiDocument specPath="/api" />
+```
+
+<Callout title="Spec path convention">
+  `specPath` is the route generated from the OpenAPI filename. `api.openapi.json` becomes `/api`.
+</Callout>

package/complete/source/en-US/api.openapi.json

@@ -0,0 +1,319 @@
+{
+  "openapi": "3.1.0",
+  "info": {
+    "title": "Starter API",
+    "summary": "A compact OpenAPI example for Clarify.",
+    "description": "Replace this file with your real OpenAPI description.\n\n**Markdown descriptions are supported** in API reference pages and embedded endpoints. Use `inline code`, links, lists, and tables for interface notes while keeping reusable components in MDX.\n\n| Field | Use |\n| --- | --- |\n| `limit` | Page size |\n| `cursor` | Pagination token |",
+    "version": "1.0.0"
+  },
+  "servers": [
+    {
+      "url": "https://api.example.com",
+      "description": "Production"
+    },
+    {
+      "url": "https://sandbox.example.com",
+      "description": "Sandbox"
+    }
+  ],
+  "tags": [
+    {
+      "name": "Projects",
+      "description": "Project management endpoints."
+    },
+    {
+      "name": "System",
+      "description": "Operational endpoints."
+    }
+  ],
+  "security": [
+    {
+      "BearerAuth": []
+    }
+  ],
+  "paths": {
+    "/v1/projects": {
+      "get": {
+        "tags": ["Projects"],
+        "operationId": "listProjects",
+        "summary": "List projects",
+        "description": "Returns projects visible to the current API token.\n\n- Use `limit` to control page size.\n- Pass the returned `nextCursor` to continue pagination.",
+        "parameters": [
+          {
+            "name": "limit",
+            "in": "query",
+            "description": "Maximum number of projects to return.\n\n| Value | Behavior |\n| --- | --- |\n| `20` | Default page size |\n| `100` | Largest allowed page |",
+            "schema": {
+              "type": "integer",
+              "minimum": 1,
+              "maximum": 100,
+              "default": 20
+            }
+          },
+          {
+            "name": "cursor",
+            "in": "query",
+            "description": "Pagination cursor from a previous response.",
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Project list.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ProjectList"
+                },
+                "examples": {
+                  "default": {
+                    "summary": "Two projects",
+                    "value": {
+                      "data": [
+                        {
+                          "id": "proj_123",
+                          "name": "Documentation",
+                          "status": "active"
+                        },
+                        {
+                          "id": "proj_456",
+                          "name": "API Reference",
+                          "status": "archived"
+                        }
+                      ],
+                      "nextCursor": null
+                    }
+                  }
+                }
+              }
+            }
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          }
+        }
+      },
+      "post": {
+        "tags": ["Projects"],
+        "operationId": "createProject",
+        "summary": "Create a project",
+        "description": "Creates a new project from a JSON request body.",
+        "requestBody": {
+          "required": true,
+          "description": "Send **JSON** with a `name` and optional `description`.",
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/ProjectCreate"
+              },
+              "examples": {
+                "default": {
+                  "value": {
+                    "name": "Documentation",
+                    "description": "Public product documentation."
+                  }
+                }
+              }
+            }
+          }
+        },
+        "responses": {
+          "201": {
+            "description": "Project created.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Project"
+                }
+              }
+            }
+          },
+          "400": {
+            "$ref": "#/components/responses/BadRequest"
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          }
+        }
+      }
+    },
+    "/v1/projects/{projectId}": {
+      "parameters": [
+        {
+          "name": "projectId",
+          "in": "path",
+          "required": true,
+          "description": "Project identifier.",
+          "schema": {
+            "type": "string",
+            "pattern": "^proj_[a-zA-Z0-9]+$"
+          }
+        }
+      ],
+      "get": {
+        "tags": ["Projects"],
+        "operationId": "getProject",
+        "summary": "Get a project",
+        "responses": {
+          "200": {
+            "description": "Project details.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Project"
+                }
+              }
+            }
+          },
+          "404": {
+            "$ref": "#/components/responses/NotFound"
+          }
+        }
+      }
+    },
+    "/v1/health": {
+      "get": {
+        "tags": ["System"],
+        "operationId": "getHealth",
+        "summary": "Check service health",
+        "security": [],
+        "responses": {
+          "200": {
+            "description": "Service status.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "required": ["status"],
+                  "properties": {
+                    "status": {
+                      "type": "string",
+                      "enum": ["ok"]
+                    }
+                  }
+                }
+              }
+            }
+          }
+        }
+      }
+    }
+  },
+  "components": {
+    "securitySchemes": {
+      "BearerAuth": {
+        "type": "http",
+        "scheme": "bearer",
+        "bearerFormat": "JWT"
+      }
+    },
+    "schemas": {
+      "ProjectStatus": {
+        "type": "string",
+        "enum": ["active", "archived"],
+        "description": "Project lifecycle state: `active` projects appear in default lists; `archived` projects are retained for history."
+      },
+      "Project": {
+        "type": "object",
+        "required": ["id", "name", "status"],
+        "properties": {
+          "id": {
+            "type": "string",
+            "examples": ["proj_123"]
+          },
+          "name": {
+            "type": "string",
+            "minLength": 1
+          },
+          "description": {
+            "type": ["string", "null"],
+            "description": "Optional public summary. Markdown such as **bold text** and `inline code` is allowed in OpenAPI descriptions."
+          },
+          "status": {
+            "$ref": "#/components/schemas/ProjectStatus"
+          },
+          "createdAt": {
+            "type": "string",
+            "format": "date-time"
+          }
+        }
+      },
+      "ProjectCreate": {
+        "type": "object",
+        "required": ["name"],
+        "properties": {
+          "name": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 120
+          },
+          "description": {
+            "type": "string",
+            "maxLength": 500
+          }
+        }
+      },
+      "ProjectList": {
+        "type": "object",
+        "required": ["data"],
+        "properties": {
+          "data": {
+            "type": "array",
+            "items": {
+              "$ref": "#/components/schemas/Project"
+            }
+          },
+          "nextCursor": {
+            "type": ["string", "null"]
+          }
+        }
+      },
+      "Error": {
+        "type": "object",
+        "required": ["code", "message"],
+        "properties": {
+          "code": {
+            "type": "string"
+          },
+          "message": {
+            "type": "string"
+          }
+        }
+      }
+    },
+    "responses": {
+      "BadRequest": {
+        "description": "Invalid request.\n\nCheck the response `code` and `message` before retrying.",
+        "content": {
+          "application/json": {
+            "schema": {
+              "$ref": "#/components/schemas/Error"
+            }
+          }
+        }
+      },
+      "Unauthorized": {
+        "description": "Missing or invalid API token.",
+        "content": {
+          "application/json": {
+            "schema": {
+              "$ref": "#/components/schemas/Error"
+            }
+          }
+        }
+      },
+      "NotFound": {
+        "description": "Resource was not found.",
+        "content": {
+          "application/json": {
+            "schema": {
+              "$ref": "#/components/schemas/Error"
+            }
+          }
+        }
+      }
+    }
+  }
+}

package/complete/source/en-US/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/complete/source/en-US/guides/navigation.mdx

@@ -0,0 +1,78 @@
+---
+title: Navigation
+description: Configure tabs, sidebar groups, page links, OpenAPI entries, 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' },
+          ],
+        },
+      ],
+    },
+  ],
+})
+```
+
+## 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: 'GitHub', href: 'https://github.com/taicode-labs/clarify', external: true },
+    ],
+  },
+  footer: {
+    copyright: '© 2026 Your Company.',
+    links: [{ label: 'Configuration', href: '/reference/configuration' }],
+    socials: { GitHub: 'https://github.com/taicode-labs/clarify' },
+  },
+})
+```
+
+## OpenAPI entries
+
+Add an OpenAPI file to navigation with `openapi` instead of `page`.
+
+```ts title="clarify.ts"
+{
+  openapi: 'api.openapi.json',
+  title: 'OpenAPI reference',
+  icon: 'FileJson2',
+}
+```
+
+This renders the full reference for `{{contentDir}}/api.openapi.json` at `/api`.