clarity-theme 0.1.2 → 0.1.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (7) hide show
  1. package/README.md +48 -274
  2. package/README.zh-CN.md +49 -293
  3. package/package.json +5 -1
  4. package/src/components/widget/BlogTech.vue +2 -0
  5. package/src/config/define.mjs +1 -1
  6. package/src/config/define.ts +1 -1
  7. package/src/config/public.ts +1 -1
package/README.md CHANGED
@@ -1,51 +1,45 @@
1
1
  # Clarity Theme
2
2
 
3
+ [![CI](https://github.com/iicemeta/clarity-theme/actions/workflows/ci.yml/badge.svg)](https://github.com/iicemeta/clarity-theme/actions/workflows/ci.yml)
4
+ [![npm version](https://img.shields.io/npm/v/clarity-theme)](https://www.npmjs.com/package/clarity-theme)
5
+ [![License: MIT](https://img.shields.io/npm/l/clarity-theme)](./LICENSE)
6
+
3
7
  **English** | [简体中文](./README.zh-CN.md)
4
8
 
5
9
  Clarity Theme is a reusable **Nuxt 4 Layer blog theme** extracted from [L33Z22L11/blog-v3](https://github.com/L33Z22L11/blog-v3). It provides the generic blog UI, page structure, Markdown/MDC rendering, SEO integration, and feed/server outputs; your project provides all site data and content.
6
10
 
7
- ## Features
11
+ ## Why Clarity?
8
12
 
9
- - Nuxt 4 Layer installation through one `extends` entry
10
- - Validated site configuration with defaults and strict unknown-field rejection
11
- - Nuxt Content collection factory for article metadata and sitemap data
12
- - Markdown, MDC components, Shiki code highlighting, KaTeX, Mermaid, ABC music scores, and rich images
13
- - Article list, archive, pagination, TOC, search, theme toggle, widgets, preview, and 404 routing
14
- - Atom, OPML, statistics, robots, sitemap, and LLMs outputs
15
- - Twikoo, head scripts, and anti-mirror integrations driven by consumer configuration
16
- - UI defaults, app config overrides, custom Shiki themes, and same-path component overrides
17
- - Automated workspace, tarball-consumer, SSR, browser, hydration, purity, contract, peer, and upstream-sync checks
13
+ Clarity replaces the traditional sync-fork workflow. Instead of merging thousands of upstream lines into your blog repository, you consume the Theme as a Layer and keep only your own files:
18
14
 
19
- ## Requirements
15
+ - **One `extends` entry** installs the whole blog application skeleton.
16
+ - **Theme and consumer are separated**: articles, friend links, redirects, deployment settings, secrets, and dependency patches never enter the Theme package.
17
+ - **Validated configuration**: `clarity.config.ts` is schema-checked with defaults and strict unknown-field rejection.
18
+ - **Content factory**: the Nuxt Content collection and article schema are derived from your configuration.
19
+ - **Rich rendering**: Markdown, MDC components, Shiki code highlighting, KaTeX, Mermaid, ABC music scores, and rich images.
20
+ - **Complete outputs**: article list, archive, pagination, TOC, search, theme toggle, widgets, Atom, OPML, statistics, robots, sitemap, and LLMs.
21
+ - **Integrations stay yours**: Twikoo, head scripts, and anti-mirror are driven by consumer configuration.
22
+ - **Override without forking**: UI app-config overrides, same-path component overrides, custom Shiki themes, and consumer CSS.
20
23
 
21
- | Runtime | Version |
22
- | --- | --- |
23
- | Node.js | `^22.19 \|\| ^24.11 \|\| >=26` |
24
- | pnpm | 12.4.1 or a compatible package manager for your project |
25
- | Nuxt peer | `^4.5.2` |
26
- | Vue peer | `^3.5.42` |
27
-
28
- Clarity is available from the npm registry as `clarity-theme`. It is part of your application runtime (the Nuxt build and static generation load the Layer directly), so install it as a regular dependency rather than a development dependency; a production install must still be able to resolve it.
29
-
30
- ## Installation
24
+ ## Choose your path
31
25
 
32
- ```bash
33
- pnpm add clarity-theme
34
- ```
26
+ | Starting point | Documentation |
27
+ | --- | --- |
28
+ | New blog | [Create a project](./docs/getting-started/new-project.md) |
29
+ | Existing blog-v3 site | [Migrate from blog-v3](./docs/getting-started/migration-from-blog-v3.md) · Agent skill: `migrate-blog-v3-to-clarity` |
30
+ | Manual installation into an existing Nuxt app | [Manual installation](./docs/getting-started/manual-installation.md) |
35
31
 
36
- ### Git commit installation (development fallback)
32
+ For an Agent-assisted migration, ask your agent to use the `migrate-blog-v3-to-clarity` skill. The full skill lives in [`skills/migrate-blog-v3-to-clarity`](./skills/migrate-blog-v3-to-clarity/SKILL.md).
37
33
 
38
- For unreleased commits, local debugging, or reviewing a specific change before it is published, install directly from GitHub instead:
34
+ ## Quick start
39
35
 
40
36
  ```bash
41
- pnpm add github:iicemeta/clarity-theme#<commit>
37
+ pnpm create clarity-theme@beta my-blog
38
+ cd my-blog
39
+ pnpm dev
42
40
  ```
43
41
 
44
- This path is intended for development only. Released sites should consume the published npm version so installs are reproducible and covered by the release verification matrix.
45
-
46
- ## Quick Start
47
-
48
- ### 1. Extend the Layer
42
+ The creator package is published separately as `create-clarity-theme`; the `@beta` dist-tag is used while its initial prerelease is the published channel. See [`create-clarity-theme/README.md`](./create-clarity-theme/README.md) for all options. The manual path is four files:
49
43
 
50
44
  ```ts
51
45
  // nuxt.config.ts
@@ -54,8 +48,6 @@ export default defineNuxtConfig({
54
48
  })
55
49
  ```
56
50
 
57
- ### 2. Define site configuration
58
-
59
51
  ```ts
60
52
  // clarity.config.ts
61
53
  import { defineClarityConfig } from 'clarity-theme/config'
@@ -65,18 +57,11 @@ export default defineClarityConfig({
65
57
  title: 'My Blog',
66
58
  description: 'Notes about technology and life',
67
59
  url: 'https://example.com/',
68
- author: {
69
- name: 'My Name',
70
- avatar: '/avatar.webp',
71
- },
60
+ author: { name: 'My Name', avatar: '/avatar.webp' },
72
61
  },
73
62
  })
74
63
  ```
75
64
 
76
- `site.title`, `site.description`, `site.url`, and `site.author.name` are required. Article, feed, stats, integration, feature, and changelog groups are optional and receive documented defaults.
77
-
78
- ### 3. Create the Content schema
79
-
80
65
  ```ts
81
66
  // content.config.ts
82
67
  import { createClarityContentConfig } from 'clarity-theme/content'
@@ -85,257 +70,46 @@ import clarityConfig from './clarity.config'
85
70
  export default createClarityContentConfig(clarityConfig)
86
71
  ```
87
72
 
88
- Place articles under `content/posts/` and other Content pages under `content/`.
89
-
90
- ### 4. Optionally provide friend data
91
-
92
- ```ts
93
- // feeds.ts
94
- import type { FeedGroup } from 'clarity-theme/config'
95
-
96
- const feeds: FeedGroup[] = []
97
-
98
- export default feeds
99
- ```
100
-
101
- Without this file, the friend page and OPML output use empty data and the build logs a warning.
102
-
103
- ### 5. Generate or develop
104
-
105
73
  ```bash
74
+ pnpm add clarity-theme
106
75
  pnpm dev
107
- pnpm generate
108
76
  ```
109
77
 
110
- For a complete walkthrough from an existing blog-v3 project, see [Migration](./docs/MIGRATION.md). Theme data and user content are deliberately separate: the package never carries your articles, friend links, redirects, deployment settings, or package patches.
111
-
112
- ## Basic Configuration
78
+ Place articles under `content/posts/` and other Content pages under `content/`. See [Manual installation](./docs/getting-started/manual-installation.md) for the optional `feeds.ts` friend data and deployment notes.
113
79
 
114
- | File | Responsibility |
115
- | --- | --- |
116
- | `clarity.config.ts` | Site identity, article semantics, feeds, stats, integrations, feature flags, changelog |
117
- | `app/app.config.ts` | Optional reactive UI overrides only |
118
- | `content.config.ts` | Nuxt Content collection/schema |
119
- | `feeds.ts` | Optional friend data |
120
- | consumer `runtimeConfig` | Environment-specific values and the only valid place for secrets |
121
-
122
- Field-by-field defaults, visibility, and examples are documented in [Configuration](./docs/CONFIGURATION.md).
123
-
124
- Example optional groups:
125
-
126
- ```ts
127
- export default defineClarityConfig({
128
- site: {
129
- title: 'My Blog',
130
- description: 'A Nuxt blog',
131
- url: 'https://example.com/',
132
- author: { name: 'My Name' },
133
- },
134
- article: {
135
- defaultCategory: 'Uncategorized',
136
- categories: {
137
- Tech: { icon: 'tabler:code', color: '#7777ff' },
138
- },
139
- types: { tech: {}, story: {} },
140
- },
141
- feed: { limit: 50, enableStyle: true },
142
- features: {
143
- atom: true,
144
- opml: true,
145
- stats: true,
146
- antiMirror: false,
147
- },
148
- })
149
- ```
150
-
151
- Never place tokens or private deployment credentials in `clarity.config.ts` or `app/app.config.ts`; both can affect generated client output.
152
-
153
- ## Public API
80
+ ## Requirements
154
81
 
155
- | Entry | API |
82
+ | Runtime | Version |
156
83
  | --- | --- |
157
- | `clarity-theme` | Nuxt Layer root |
158
- | `clarity-theme/config` | `defineClarityConfig()` and configuration/schema types |
159
- | `clarity-theme/content` | `createClarityContentConfig()` and `ArticleSchema` |
160
- | `clarity-theme/schema` | All `clarity*` Zod schemas and derived types |
161
- | `clarity-theme/img` | Avatar/favicon/image URL helpers |
162
-
163
- The Layer also exposes the `useClarityConfig()`, `useClaritySite()`, `useClarityArticle()`, and `useClaritySiteFeedEntry()` runtime auto-imports, plus the `#clarity/feeds` injection. They are Layer contracts rather than standalone package subpaths.
164
-
165
- The exact export/type boundary is documented in [docs/API.md](./docs/API.md).
166
-
167
- ## Customization
168
-
169
- ### UI configuration
170
-
171
- ```ts
172
- // app/app.config.ts
173
- export default defineAppConfig({
174
- clarity: {
175
- header: { emojiTail: ['📝'] },
176
- pagination: { perPage: 10 },
177
- nav: [
178
- {
179
- title: '',
180
- items: [
181
- { icon: 'tabler:files', text: 'Articles', url: '/' },
182
- { icon: 'tabler:link', text: 'Friends', url: '/link' },
183
- { icon: 'tabler:archive', text: 'Archive', url: '/archive' },
184
- ],
185
- },
186
- ],
187
- },
188
- })
189
- ```
190
-
191
- Objects merge deeply; arrays replace the Theme value entirely.
192
-
193
- ### Components
194
-
195
- Create a Layer-relative component at the same path to replace it, for example:
196
-
197
- ```text
198
- app/components/content/Badge.vue
199
- ```
200
-
201
- Consumer components take precedence over Layer components. Nuxt currently emits a duplicate-name warning for this intentional override pattern.
202
-
203
- ### Shiki themes
204
-
205
- Provide `app/shiki.config.ts` in the consumer project. The Theme fallback is used only when this file does not exist.
206
-
207
- UI groups, same-path component overrides, CSS overrides, server/route customization, and Shiki ownership are described together in [Customization](./docs/CUSTOMIZATION.md).
208
-
209
- ## Compatibility and Verification
210
-
211
- The verification suite is designed to cover:
212
-
213
- - Playground static generation
214
- - Independent `pnpm pack` consumer installation
215
- - Five package exports in Node and TypeScript
216
- - Three configuration branches
217
- - Markdown/MDC/code/math/Mermaid/music/image rendering
218
- - Production SSR, real browser rendering, and dev hydration
219
- - Search, pagination, archive, TOC, SEO, robots, sitemap, LLMs, Atom, OPML, stats, permalink, 404, Twikoo branches, anti-mirror injection, UI override, and component override
220
- - Theme purity, peer dependencies, sync tooling, and upstream drift
221
-
222
- The generated release matrix lives in [Compatibility](./docs/COMPATIBILITY.md). Current exact counts, known limitations, technical debt, and release blockers live in [Project status](./docs/PROJECT-STATUS.md) and [Roadmap](./docs/ROADMAP.md). A release must rerun the ordered suite on the exact commit; earlier results are not a substitute.
84
+ | Node.js | `^22.19 \|\| ^24.11 \|\| >=26` |
85
+ | pnpm | 12.4.1 or a compatible package manager for your project |
86
+ | Nuxt peer | `^4.5.2` |
87
+ | Vue peer | `^3.5.42` |
223
88
 
224
- Site-specific dependency patches are intentionally owned by consumers; see [Patches](./docs/PATCHES.md).
89
+ Clarity is part of your application runtime (the Nuxt build and static generation load the Layer directly), so install it as a regular dependency rather than a development dependency.
225
90
 
226
91
  ## Documentation
227
92
 
228
- All documents are also available in 简体中文 as sibling `*.zh-CN.md` files.
93
+ All documents are also available in 简体中文 as sibling `*.zh-CN.md` files. Start from the [documentation index](./docs/README.md):
229
94
 
230
- | Document | Purpose |
231
- | --- | --- |
232
- | [Project status](./docs/PROJECT-STATUS.md) | Current snapshot, verified capabilities, limitations, debt, gaps, and milestone |
233
- | [Roadmap](./docs/ROADMAP.md) | Prioritized P0/P1/P2 debt register, deferred decisions, and milestone order |
234
- | [Migration](./docs/MIGRATION.md) | Preserve blog-v3 content, configuration, redirects, patches, custom code, and assets while adopting Clarity |
235
- | [Architecture](./docs/ARCHITECTURE.md) | Theme/consumer boundary and build/runtime data flows |
236
- | [API](./docs/API.md) | Public package/Layer API versus internal implementation |
237
- | [Configuration](./docs/CONFIGURATION.md) | Field-level Clarity configuration contract and examples |
238
- | [Customization](./docs/CUSTOMIZATION.md) | UI, component, Shiki, CSS, server, and route overrides |
239
- | [Compatibility](./docs/COMPATIBILITY.md) | Generated release compatibility matrix |
240
- | [Upstream sync](./docs/UPSTREAM.md) | Baseline, manifest, commands, conflicts, and workflow |
241
- | [Patches](./docs/PATCHES.md) | Consumer patch ownership and current conclusions |
242
- | [Release audit](./docs/RELEASE-AUDIT.md) | Pre-closing engineering audit and remaining release gates |
243
- | [Release checklist](./docs/RELEASE-CHECKLIST.md) | Exact final checks, remaining blockers, and verification evidence |
244
- | [Publishing](./docs/PUBLISHING.md) | Versioning, tags, GitHub Releases, OIDC publishing, provenance, and rollback policy |
245
- | [Changelog](./CHANGELOG.md) | Consumer-facing release history |
246
- | [Extraction history](./docs/history/2026-09-layer-extraction.md) | Historical phases and one-time differential validation |
247
-
248
- ## Repository Layout
249
-
250
- The repository root is the engineering layer; all Theme runtime source lives
251
- under `src/`:
252
-
253
- ```
254
- clarity-theme/
255
- ├─ src/ # Theme runtime source (Layer srcDir)
256
- │ ├─ assets/ components/ composables/ layouts/ middleware/
257
- │ ├─ pages/ plugins/ stores/ types/ utils/
258
- │ ├─ app.config.ts app.vue error.vue shiki.config.ts
259
- │ ├─ config/ # config API sources (npm ./config ./content ./schema)
260
- │ ├─ img/ # img API sources (npm ./img)
261
- │ ├─ modules/ # source-layout bootstrap + clarity-config modules
262
- │ ├─ public/ server/ shared/ remark-plugins/
263
- ├─ skills/ # Agent workflow skills (not part of the npm package)
264
- ├─ docs/ # Human documentation
265
- ├─ playground/ # Workspace-linked development consumer
266
- ├─ scripts/ tests/ # Verification and tooling
267
- └─ nuxt.config.ts, package.json, sync-manifest.json, …
268
- ```
269
-
270
- `nuxt.config.ts` stays at the package root. Its first module,
271
- `src/modules/clarity-source-layout`, applies the `src/` directory metadata to
272
- the Clarity layer only; static `srcDir`/`serverDir`/`dir.*` values are not
273
- used because c12 would merge them into consumer root config. npm, Git-commit,
274
- and local-directory installs therefore resolve the same layout without
275
- overriding a consumer's own application directories.
276
-
277
- The npm package, the Agent skill, and the docs are three separate concerns:
278
-
279
- - **`clarity-theme` (npm package)** — the runtime Nuxt Layer installed with
280
- `extends: ['clarity-theme']`. Its `files` field ships only `src/` plus the
281
- root entry files; dev assets never enter the tarball.
282
- - **`skills/migrate-blog-v3-to-clarity`** — the canonical Agent workflow for
283
- migrating an existing blog-v3 project. It is versioned with the repository
284
- but intentionally **not** bundled into the npm package.
285
- - **`docs/`** — human-readable documentation mirrored in English and Chinese.
286
-
287
- ### Installing the migration skill
288
-
289
- ```bash
290
- npx skills add iicemeta/clarity-theme --list # discover available skills
291
- npx skills add iicemeta/clarity-theme --skill migrate-blog-v3-to-clarity
292
- ```
293
-
294
- For development, `npx skills add ./skills --list` discovers the local copy.
295
- To migrate a blog-v3 site with an Agent, ask it to use the
296
- `migrate-blog-v3-to-clarity` skill; the human walkthrough remains
297
- [Migration](./docs/MIGRATION.md).
95
+ - **Getting started** — [new project](./docs/getting-started/new-project.md), [manual installation](./docs/getting-started/manual-installation.md), [migrating from blog-v3](./docs/getting-started/migration-from-blog-v3.md)
96
+ - **Guides** — [configuration](./docs/guides/configuration.md), [content](./docs/guides/content.md), [customization](./docs/guides/customization.md), [integrations](./docs/guides/integrations.md)
97
+ - **Reference** — [public API](./docs/reference/api.md), [routes and outputs](./docs/reference/routes-and-outputs.md), [compatibility matrix](./docs/reference/compatibility.md)
98
+ - **Concepts** — [architecture](./docs/concepts/architecture.md)
99
+ - **Maintainers** — [development](./docs/maintainers/development.md), [testing](./docs/maintainers/testing.md), [upstream sync](./docs/maintainers/upstream-sync.md), [patches](./docs/maintainers/patches.md), [publishing](./docs/maintainers/publishing.md), [release checklist](./docs/maintainers/release-checklist.md), [project status](./docs/maintainers/project-status.md), [roadmap](./docs/maintainers/roadmap.md), [documentation rules](./docs/maintainers/documentation.md)
100
+ - **Release history** — [CHANGELOG](./CHANGELOG.md); historical records live under [docs/history](./docs/history/)
298
101
 
299
102
  ## Development
300
103
 
301
104
  ```bash
302
- pnpm install # Theme + playground workspace
303
- pnpm dev # Playground dev server
304
- pnpm generate # Playground static generation
305
- pnpm lint
105
+ pnpm install # Theme + playground workspace
106
+ pnpm dev # Playground dev server
107
+ pnpm generate # Playground static generation
108
+ pnpm lint # ESLint + Stylelint
306
109
  pnpm typecheck
307
- pnpm verify # Purity/static leak checks
308
- pnpm peers check
309
- pnpm test:sync
310
- pnpm test:migration
311
- pnpm test:contract
312
- pnpm test:consumer
313
- pnpm test:compatibility
314
- pnpm pack --dry-run # inspect the npm tarball without writing it
315
- ```
316
-
317
- CI derives Node and pnpm versions from package metadata. It runs lint/typecheck/verify/sync/migration/contract/peers on the fixed Node matrix, then playground generate, real consumer acceptance, and rendering compatibility on the primary Node version. A separate weekly workflow only detects and reports upstream drift.
318
-
319
- See [Project status → CI](./docs/PROJECT-STATUS.md#10-ci) for the exact CI stages and permissions.
320
-
321
- ## Upstream Synchronization
322
-
323
- Clarity is extracted from an upstream Nuxt blog and records the exact reviewed baseline in `sync-manifest.json`. The synchronization tooling separates directly includable paths, consumer-owned exclusions, transformed Theme contracts, and manual review paths; unknown upstream changes block apply. Use:
324
-
325
- ```bash
326
- pnpm sync:check # compare manifest baseline with remote
327
- pnpm sync:diff # classify upstream changes
328
- pnpm sync:apply # transactionally apply reviewed include-only changes
329
- pnpm sync:verify # rerun Theme purity and baseline checks
330
110
  ```
331
111
 
332
- The weekly workflow only detects and reports drift. It never applies, commits, or pushes changes. See [Upstream sync](./docs/UPSTREAM.md).
333
-
334
- ## Release Status
335
-
336
- Clarity Theme is a **v0.1.2 gated npm release**. The Layer/package boundary, validated configuration, Content factory, rendering pipeline, server outputs, playground, real-consumer acceptance, compatibility matrix, three-layer CI, upstream-sync baseline, release gate, and OIDC publish workflow are implemented. See the [release checklist](./docs/RELEASE-CHECKLIST.md) for the exact remaining manual publication steps.
337
-
338
- The v0.1.0 correctness gates from [Roadmap](./docs/ROADMAP.md) are resolved: server/client configuration is split, feature-off routes return 404 at runtime, anti-mirror navigation is verified in a real browser, the no-op random-permalink field is removed, and multi-pattern stats are covered by a regression test. Remaining deferred items are recorded in the roadmap and release notes.
112
+ See [development](./docs/maintainers/development.md) and [testing](./docs/maintainers/testing.md) for the full verification matrix, upstream synchronization, and release workflow.
339
113
 
340
114
  ## License
341
115
 
package/README.zh-CN.md CHANGED
@@ -1,51 +1,45 @@
1
1
  # Clarity Theme
2
2
 
3
+ [![CI](https://github.com/iicemeta/clarity-theme/actions/workflows/ci.yml/badge.svg)](https://github.com/iicemeta/clarity-theme/actions/workflows/ci.yml)
4
+ [![npm version](https://img.shields.io/npm/v/clarity-theme)](https://www.npmjs.com/package/clarity-theme)
5
+ [![License: MIT](https://img.shields.io/npm/l/clarity-theme)](./LICENSE)
6
+
3
7
  [English](./README.md) | **简体中文**
4
8
 
5
9
  Clarity Theme 是一个从 [L33Z22L11/blog-v3](https://github.com/L33Z22L11/blog-v3) 抽取出来的可复用 **Nuxt 4 Layer 博客主题**。它提供通用的博客 UI、页面结构、Markdown/MDC 渲染、SEO 集成以及 feed/服务端输出；你的项目只需要提供全部站点数据与内容。
6
10
 
7
- ## 功能特性
8
-
9
- - 通过一条 `extends` 配置即可完成 Nuxt 4 Layer 安装
10
- - 带默认值校验的站点配置，并严格拒绝未知字段
11
- - 用于文章元数据与站点地图数据的 Nuxt Content 集合工厂
12
- - Markdown、MDC 组件、Shiki 代码高亮、KaTeX、Mermaid、ABC 乐谱与富图片
13
- - 文章列表、归档、分页、目录（TOC）、搜索、主题切换、小部件、预览与 404 路由
14
- - Atom、OPML、统计、robots、sitemap 与 LLMs 输出
15
- - 由使用方配置驱动的 Twikoo、head 脚本与反镜像集成
16
- - UI 默认值、app config 覆盖、自定义 Shiki 主题与同路径组件覆盖
17
- - 自动化的 workspace、tarball 消费者、SSR、浏览器、水合、纯度、契约、peer 与上游同步检查
18
-
19
- ## 环境要求
11
+ ## 为什么选择 Clarity？
20
12
 
21
- | 运行时 | 版本 |
22
- | --- | --- |
23
- | Node.js | `^22.19 \|\| ^24.11 \|\| >=26` |
24
- | pnpm | 12.4.1，或适用于你项目的兼容包管理器 |
25
- | Nuxt peer | `^4.5.2` |
26
- | Vue peer | `^3.5.42` |
13
+ Clarity 取代传统的 sync fork 工作流。你不需要把上游数千行代码合并进博客仓库，而是以 Layer 方式消费主题，只维护自己的文件：
27
14
 
28
- Clarity 已通过 npm 注册表以 `clarity-theme` 分发。它属于应用运行时的一部分（Nuxt 构建与静态生成会直接加载 Layer），因此请将其安装为常规依赖（dependency），而不是开发依赖（devDependency）；生产环境安装也必须能解析到它。
15
+ - **一条 `extends` 配置**即可安装完整的博客应用骨架
16
+ - **Theme 与 Consumer 分离**：文章、友链、重定向、部署配置、密钥与依赖补丁永远不会进入主题包
17
+ - **配置带校验**：`clarity.config.ts` 由 schema 校验，提供默认值并严格拒绝未知字段
18
+ - **Content 工厂**：Nuxt Content 集合与文章 schema 由你的配置派生
19
+ - **富渲染**：Markdown、MDC 组件、Shiki 代码高亮、KaTeX、Mermaid、ABC 乐谱与富图片
20
+ - **完整输出**：文章列表、归档、分页、目录（TOC）、搜索、主题切换、小部件、Atom、OPML、统计、robots、sitemap 与 LLMs
21
+ - **集成仍归你所有**：Twikoo、head 脚本与反镜像均由消费方配置驱动
22
+ - **覆盖而无需 fork**：UI app config 覆盖、同路径组件覆盖、自定义 Shiki 主题与消费方 CSS
29
23
 
30
- ## 安装
24
+ ## 选择你的路径
31
25
 
32
- ```bash
33
- pnpm add clarity-theme
34
- ```
26
+ | 起点 | 文档 |
27
+ | --- | --- |
28
+ | 新博客 | [创建项目](./docs/getting-started/new-project.zh-CN.md) |
29
+ | 现有 blog-v3 站点 | [从 blog-v3 迁移](./docs/getting-started/migration-from-blog-v3.zh-CN.md) · Agent Skill：`migrate-blog-v3-to-clarity` |
30
+ | 手动接入现有 Nuxt 应用 | [手动安装](./docs/getting-started/manual-installation.zh-CN.md) |
35
31
 
36
- ### Git commit 安装（开发回退方式）
32
+ 如需 Agent 协助迁移，直接让你的 Agent 使用 `migrate-blog-v3-to-clarity` Skill。完整 Skill 位于 [`skills/migrate-blog-v3-to-clarity`](./skills/migrate-blog-v3-to-clarity/SKILL.md)。
37
33
 
38
- 如需使用未发布的 commit、本地调试，或在发布前审查某个具体变更，可以直接从 GitHub 安装：
34
+ ## 快速开始
39
35
 
40
36
  ```bash
41
- pnpm add github:iicemeta/clarity-theme#<commit>
37
+ pnpm create clarity-theme@beta my-blog
38
+ cd my-blog
39
+ pnpm dev
42
40
  ```
43
41
 
44
- 该方式仅用于开发场景。正式站点应使用已发布的 npm 版本，以保证安装可复现并被发布验证矩阵覆盖。
45
-
46
- ## 快速开始
47
-
48
- ### 1. 继承 Layer
42
+ 创建包以独立的 `create-clarity-theme` npm 包分发；当前初始预发布位于 `@beta` dist-tag。完整参数见 [`create-clarity-theme/README.md`](./create-clarity-theme/README.md)。手动接入只需四个文件：
49
43
 
50
44
  ```ts
51
45
  // nuxt.config.ts
@@ -54,8 +48,6 @@ export default defineNuxtConfig({
54
48
  })
55
49
  ```
56
50
 
57
- ### 2. 定义站点配置
58
-
59
51
  ```ts
60
52
  // clarity.config.ts
61
53
  import { defineClarityConfig } from 'clarity-theme/config'
@@ -65,18 +57,11 @@ export default defineClarityConfig({
65
57
  title: 'My Blog',
66
58
  description: 'Notes about technology and life',
67
59
  url: 'https://example.com/',
68
- author: {
69
- name: 'My Name',
70
- avatar: '/avatar.webp',
71
- },
60
+ author: { name: 'My Name', avatar: '/avatar.webp' },
72
61
  },
73
62
  })
74
63
  ```
75
64
 
76
- `site.title`、`site.description`、`site.url` 与 `site.author.name` 为必填项。article、feed、stats、integration、feature 与 changelog 分组均为可选，并使用文档中记载的默认值。
77
-
78
- ### 3. 创建 Content schema
79
-
80
65
  ```ts
81
66
  // content.config.ts
82
67
  import { createClarityContentConfig } from 'clarity-theme/content'
@@ -85,276 +70,47 @@ import clarityConfig from './clarity.config'
85
70
  export default createClarityContentConfig(clarityConfig)
86
71
  ```
87
72
 
88
- 文章放在 `content/posts/` 下，其他 Content 页面放在 `content/` 下。
89
-
90
- ### 4. 可选：提供友链数据
91
-
92
- ```ts
93
- // feeds.ts
94
- import type { FeedGroup } from 'clarity-theme/config'
95
-
96
- const feeds: FeedGroup[] = []
97
-
98
- export default feeds
99
- ```
100
-
101
- 如果没有这个文件，友链页面和 OPML 输出会使用空数据，并且构建时会记录一条警告。
102
-
103
- ### 5. 生成或开发
104
-
105
73
  ```bash
74
+ pnpm add clarity-theme
106
75
  pnpm dev
107
- pnpm generate
108
- ```
109
-
110
- 从现有 blog-v3 项目完整迁移的操作流程，见[迁移指南](./docs/MIGRATION.zh-CN.md)。主题数据与用户内容是被刻意分开的：这个包永远不会携带你的文章、友链、重定向、部署配置或包补丁。
111
-
112
- ## 从 blog-v3 迁移
113
-
114
- 完整的人工迁移指南见[迁移指南](./docs/MIGRATION.zh-CN.md)。如果你希望让当前 Agent 使用 `migrate-blog-v3-to-clarity` Skill 自动执行迁移，可以直接使用下面的提示词：
115
-
116
- ```markdown
117
- 请使用 `migrate-blog-v3-to-clarity` Skill，把当前这个 blog-v3 项目迁移到 Clarity Theme。
118
-
119
- 要求：
120
-
121
- 1. 先只读扫描项目，不立即修改。
122
- 2. 判断当前项目是否属于支持的 blog-v3 结构。
123
- 3. 检查 blog.config.ts、app/app.config.ts、content.config.ts、nuxt.config.ts、feeds.ts、redirects.json、patches、content、public、custom components、server、modules。
124
- 4. 生成迁移计划，并把所有风险项标出来。
125
- 5. 不修改文章正文和 frontmatter。
126
- 6. 不删除 content、public、redirects、patches 或未知自定义代码。
127
- 7. 能自动迁移的部分自动处理。
128
- 8. 需要人工判断的部分暂停修改并记录原因。
129
- 9. 迁移完成后执行 typecheck、generate 和兼容性验证。
130
- 10. 最后输出完整 migration report，包括修改文件、保留配置、人工处理项和测试结果。
131
-
132
- 整个过程只使用当前 Agent 串行执行，不启动并行 Agent。
133
76
  ```
134
77
 
135
- ## 基础配置
78
+ 文章放在 `content/posts/` 下，其他 Content 页面放在 `content/` 下。可选的 `feeds.ts` 友链数据与部署说明见[手动安装](./docs/getting-started/manual-installation.zh-CN.md)。
136
79
 
137
- | 文件 | 职责 |
138
- | --- | --- |
139
- | `clarity.config.ts` | 站点身份、文章语义、友链、统计、集成、功能开关、更新日志 |
140
- | `app/app.config.ts` | 仅限可选的响应式 UI 覆盖 |
141
- | `content.config.ts` | Nuxt Content 集合/schema |
142
- | `feeds.ts` | 可选的友链数据 |
143
- | 使用方 `runtimeConfig` | 环境相关配置，以及唯一合法的密钥存放位置 |
144
-
145
- 逐字段的默认值、可见性与示例见[配置说明](./docs/CONFIGURATION.zh-CN.md)。
146
-
147
- 可选分组示例：
148
-
149
- ```ts
150
- export default defineClarityConfig({
151
- site: {
152
- title: 'My Blog',
153
- description: 'A Nuxt blog',
154
- url: 'https://example.com/',
155
- author: { name: 'My Name' },
156
- },
157
- article: {
158
- defaultCategory: 'Uncategorized',
159
- categories: {
160
- Tech: { icon: 'tabler:code', color: '#7777ff' },
161
- },
162
- types: { tech: {}, story: {} },
163
- },
164
- feed: { limit: 50, enableStyle: true },
165
- features: {
166
- atom: true,
167
- opml: true,
168
- stats: true,
169
- antiMirror: false,
170
- },
171
- })
172
- ```
173
-
174
- 绝不要把 token 或私有部署凭据放在 `clarity.config.ts` 或 `app/app.config.ts` 中；这两者都可能影响生成的客户端产物。
175
-
176
- ## 公共 API
80
+ ## 环境要求
177
81
 
178
- | 入口 | API |
82
+ | 运行时 | 版本 |
179
83
  | --- | --- |
180
- | `clarity-theme` | Nuxt Layer 根入口 |
181
- | `clarity-theme/config` | `defineClarityConfig()` 与配置/schema 类型 |
182
- | `clarity-theme/content` | `createClarityContentConfig()` 与 `ArticleSchema` |
183
- | `clarity-theme/schema` | 全部 `clarity*` Zod schema 及派生类型 |
184
- | `clarity-theme/img` | 头像/favicon/图片 URL 辅助函数 |
185
-
186
- Layer 还暴露了 `useClarityConfig()`、`useClaritySite()`、`useClarityArticle()` 与 `useClaritySiteFeedEntry()` 运行时自动导入，以及 `#clarity/feeds` 注入。它们是 Layer 契约，而不是独立的包子路径。
187
-
188
- 确切的导出/类型边界记录在 [API 文档](./docs/API.zh-CN.md) 中。
189
-
190
- ## 自定义
191
-
192
- ### UI 配置
193
-
194
- ```ts
195
- // app/app.config.ts
196
- export default defineAppConfig({
197
- clarity: {
198
- header: { emojiTail: ['📝'] },
199
- pagination: { perPage: 10 },
200
- nav: [
201
- {
202
- title: '',
203
- items: [
204
- { icon: 'tabler:files', text: 'Articles', url: '/' },
205
- { icon: 'tabler:link', text: 'Friends', url: '/link' },
206
- { icon: 'tabler:archive', text: 'Archive', url: '/archive' },
207
- ],
208
- },
209
- ],
210
- },
211
- })
212
- ```
213
-
214
- 对象会深度合并；数组会整体替换主题的值。
215
-
216
- ### 组件
217
-
218
- 在使用方项目中创建同路径的 Layer 相对组件即可替换，例如：
219
-
220
- ```text
221
- app/components/content/Badge.vue
222
- ```
223
-
224
- 使用方组件优先于 Layer 组件。Nuxt 目前会针对这种有意的覆盖模式输出重名警告。
225
-
226
- ### Shiki 主题
227
-
228
- 在使用方项目中提供 `app/shiki.config.ts`。只有当该文件不存在时，才会使用主题的回退配置。
229
-
230
- UI 分组、同路径组件覆盖、CSS 覆盖、服务端/路由自定义与 Shiki 归属详见[自定义说明](./docs/CUSTOMIZATION.zh-CN.md)。
231
-
232
- ## 兼容性与验证
233
-
234
- 验证套件覆盖：
235
-
236
- - Playground 静态生成
237
- - 独立的 `pnpm pack` 消费者安装
238
- - Node 与 TypeScript 中的五个包导出
239
- - 三种配置分支
240
- - Markdown/MDC/代码/数学公式/Mermaid/乐谱/图片渲染
241
- - 生产 SSR、真实浏览器渲染与开发水合
242
- - 搜索、分页、归档、TOC、SEO、robots、sitemap、LLMs、Atom、OPML、统计、固定链接、404、Twikoo 分支、反镜像注入、UI 覆盖与组件覆盖
243
- - 主题纯度、peer 依赖、同步工具与上游漂移
244
-
245
- 生成的发布矩阵见[兼容性说明](./docs/COMPATIBILITY.zh-CN.md)。当前的精确数量、已知限制、技术债与发布阻塞项见[项目状态](./docs/PROJECT-STATUS.zh-CN.md)与[路线图](./docs/ROADMAP.zh-CN.md)。发布前必须在确切的 commit 上重新按顺序运行整套验证；早先的结果不能替代。
84
+ | Node.js | `^22.19 \|\| ^24.11 \|\| >=26` |
85
+ | pnpm | 12.4.1，或适用于你项目的兼容包管理器 |
86
+ | Nuxt peer | `^4.5.2` |
87
+ | Vue peer | `^3.5.42` |
246
88
 
247
- 站点相关的依赖补丁刻意由使用方持有；见[补丁说明](./docs/PATCHES.zh-CN.md)。
89
+ Clarity 属于应用运行时的一部分（Nuxt 构建与静态生成会直接加载 Layer），因此请将其安装为常规依赖，而不是开发依赖。
248
90
 
249
91
  ## 文档
250
92
 
251
- | 文档 | 用途 |
252
- | --- | --- |
253
- | [项目状态](./docs/PROJECT-STATUS.zh-CN.md) | 当前快照、已验证能力、限制、技术债、缺口与里程碑 |
254
- | [路线图](./docs/ROADMAP.zh-CN.md) | 按优先级排序的 P0/P1/P2 技术债清单、延后决策与里程碑顺序 |
255
- | [迁移指南](./docs/MIGRATION.zh-CN.md) | 在采用 Clarity 的同时保留 blog-v3 的内容、配置、重定向、补丁、自定义代码与资源 |
256
- | [架构](./docs/ARCHITECTURE.zh-CN.md) | 主题/使用方边界与构建/运行时数据流 |
257
- | [API](./docs/API.zh-CN.md) | 公共包/Layer API 与内部实现的边界 |
258
- | [配置说明](./docs/CONFIGURATION.zh-CN.md) | 字段级 Clarity 配置契约与示例 |
259
- | [自定义说明](./docs/CUSTOMIZATION.zh-CN.md) | UI、组件、Shiki、CSS、服务端与路由覆盖 |
260
- | [兼容性说明](./docs/COMPATIBILITY.zh-CN.md) | 生成的发布兼容性矩阵 |
261
- | [上游同步](./docs/UPSTREAM.zh-CN.md) | 基线、manifest、命令、冲突与工作流 |
262
- | [补丁说明](./docs/PATCHES.zh-CN.md) | 使用方补丁归属与当前结论 |
263
- | [发布审计](./docs/RELEASE-AUDIT.zh-CN.md) | 收尾前工程审计与剩余发布门槛 |
264
- | [发布清单](./docs/RELEASE-CHECKLIST.zh-CN.md) | 确切的最终检查、剩余阻塞项与验证证据 |
265
- | [发布指南](./docs/PUBLISHING.zh-CN.md) | 版本管理、tag、GitHub Release、OIDC 发布、provenance 与回滚策略 |
266
- | [更新日志](./CHANGELOG.md) | 面向使用者的发布历史 |
267
- | [抽取历史](./docs/history/2026-09-layer-extraction.zh-CN.md) | 历史阶段与一次性差分验证 |
268
-
269
- ## 仓库结构
270
-
271
- 仓库根目录是工程管理层；Theme 的全部运行时源码统一放在 `src/`：
272
-
273
- ```
274
- clarity-theme/
275
- ├─ src/ # Theme 运行时源码（Layer srcDir）
276
- │ ├─ assets/ components/ composables/ layouts/ middleware/
277
- │ ├─ pages/ plugins/ stores/ types/ utils/
278
- │ ├─ app.config.ts app.vue error.vue shiki.config.ts
279
- │ ├─ config/ # config API 源码（npm ./config ./content ./schema）
280
- │ ├─ img/ # img API 源码（npm ./img）
281
- │ ├─ modules/ # source-layout 引导模块 + clarity-config 模块
282
- │ ├─ public/ server/ shared/ remark-plugins/
283
- ├─ skills/ # Agent 工作流 Skill（不进入 npm 包）
284
- ├─ docs/ # 人工文档
285
- ├─ playground/ # workspace 链接的开发用消费项目
286
- ├─ scripts/ tests/ # 验证与工具脚本
287
- └─ nuxt.config.ts、package.json、sync-manifest.json、…
288
- ```
289
-
290
- `nuxt.config.ts` 保留在包根目录。它最先加载的
291
- `src/modules/clarity-source-layout` 只为 Clarity 自身 layer 应用 `src/`
292
- 目录元数据；不静态声明 `srcDir`/`serverDir`/`dir.*`，是因为 c12 会把它们
293
- 合并进未显式覆盖这些键的 consumer root 配置。因此 npm 安装、Git commit
294
- 安装与本地目录安装解析到同一份布局，同时不会覆盖 consumer 自己的
295
- 应用目录。
296
-
297
- npm 包、Agent Skill 与文档三者职责分离：
298
-
299
- - **`clarity-theme`（npm 包）** — 运行时 Nuxt Layer，通过
300
- `extends: ['clarity-theme']` 使用。`files` 只发布 `src/` 与根入口文件，
301
- 开发资产不会进入 tarball。
302
- - **`skills/migrate-blog-v3-to-clarity`** — 迁移既有 blog-v3 项目的
303
- Agent 工作流 Skill。它与仓库一起版本化，但**刻意不**打进 npm 包。
304
- - **`docs/`** — 中英双语的人工文档。
305
-
306
- ### 安装迁移 Skill
93
+ 所有文档都有对应的简体中文版本（同名 `*.zh-CN.md` 文件）。入口见[文档索引](./docs/README.zh-CN.md)：
307
94
 
308
- ```bash
309
- npx skills add iicemeta/clarity-theme --list # 发现可用 Skill
310
- npx skills add iicemeta/clarity-theme --skill migrate-blog-v3-to-clarity
311
- ```
312
-
313
- 开发环境可用 `npx skills add ./skills --list` 发现本地副本。让 Agent 迁移
314
- blog-v3 站点时，请让它使用 `migrate-blog-v3-to-clarity` Skill；人工流程
315
- 见[迁移指南](./docs/MIGRATION.zh-CN.md)。
95
+ - **入门** — [创建新项目](./docs/getting-started/new-project.zh-CN.md)、[手动安装](./docs/getting-started/manual-installation.zh-CN.md)、[从 blog-v3 迁移](./docs/getting-started/migration-from-blog-v3.zh-CN.md)
96
+ - **指南** — [配置](./docs/guides/configuration.zh-CN.md)、[内容](./docs/guides/content.zh-CN.md)、[自定义](./docs/guides/customization.zh-CN.md)、[集成](./docs/guides/integrations.zh-CN.md)
97
+ - **参考** — [公共 API](./docs/reference/api.zh-CN.md)、[路由与输出](./docs/reference/routes-and-outputs.zh-CN.md)、[兼容性矩阵](./docs/reference/compatibility.zh-CN.md)
98
+ - **概念** — [架构](./docs/concepts/architecture.zh-CN.md)
99
+ - **维护者** — [开发](./docs/maintainers/development.zh-CN.md)、[测试](./docs/maintainers/testing.zh-CN.md)、[上游同步](./docs/maintainers/upstream-sync.zh-CN.md)、[补丁](./docs/maintainers/patches.zh-CN.md)、[发布](./docs/maintainers/publishing.zh-CN.md)、[发布清单](./docs/maintainers/release-checklist.zh-CN.md)、[项目状态](./docs/maintainers/project-status.zh-CN.md)、[路线图](./docs/maintainers/roadmap.zh-CN.md)、[文档规则](./docs/maintainers/documentation.zh-CN.md)
100
+ - **发布历史** — [CHANGELOG](./CHANGELOG.md)；历史记录位于 [docs/history](./docs/history/)
316
101
 
317
102
  ## 开发
318
103
 
319
104
  ```bash
320
- pnpm install # 主题 + playground workspace
321
- pnpm dev # Playground 开发服务器
322
- pnpm generate # Playground 静态生成
323
- pnpm lint
105
+ pnpm install # Theme + playground workspace
106
+ pnpm dev # Playground dev server
107
+ pnpm generate # Playground static generation
108
+ pnpm lint # ESLint + Stylelint
324
109
  pnpm typecheck
325
- pnpm verify # 纯度/静态泄漏检查
326
- pnpm peers check
327
- pnpm test:sync
328
- pnpm test:migration
329
- pnpm test:contract
330
- pnpm test:consumer
331
- pnpm test:compatibility
332
- pnpm pack --dry-run # 不落盘检查 npm tarball
333
110
  ```
334
111
 
335
- CI 从包元数据推导 Node 与 pnpm 版本。它先在固定的 Node 矩阵上运行 lint/typecheck/verify/sync/migration/contract/peers，再在主 Node 版本上运行 playground 生成、真实消费者验收与渲染兼容性。另有一个每周工作流只检测并报告上游漂移。
336
-
337
- 确切的 CI 阶段与权限见[项目状态 → CI](./docs/PROJECT-STATUS.zh-CN.md#10-ci)。
338
-
339
- ## 上游同步
340
-
341
- Clarity 从一个上游 Nuxt 博客抽取而来，并在 `sync-manifest.json` 中记录确切的已审查基线。同步工具区分可直接包含的路径、使用方持有的排除项、经过转换的主题契约与人工审查路径；未知的上游变更会阻止 apply。使用：
342
-
343
- ```bash
344
- pnpm sync:check # 比较 manifest 基线与远端
345
- pnpm sync:diff # 对上游变更分类
346
- pnpm sync:apply # 事务式应用已审查的 include-only 变更
347
- pnpm sync:verify # 重新运行主题纯度与基线检查
348
- ```
349
-
350
- 每周工作流只检测并报告漂移，绝不会 apply、commit 或 push 变更。见[上游同步](./docs/UPSTREAM.zh-CN.md)。
351
-
352
- ## 发布状态
353
-
354
- Clarity Theme 是一个 **v0.1.2 门禁 npm 发布版本**。Layer/包边界、已校验配置、Content 工厂、渲染管线、服务端输出、playground、真实消费者验收、兼容性矩阵、三层 CI、上游同步基线、发布门禁与 OIDC 发布工作流均已实现。剩余的人工发布步骤见[发布检查清单](./docs/RELEASE-CHECKLIST.zh-CN.md)。
355
-
356
- [路线图](./docs/ROADMAP.zh-CN.md)中的 v0.1.0 正确性门禁已解决：服务端/客户端配置已拆分、功能关闭路由在运行时返回 404、反镜像导航已在真实浏览器中验证、no-op 随机固定链接字段已移除，多模式统计已增加回归测试。其余推迟事项记录在路线图与发布说明中。
112
+ 完整验证矩阵、上游同步与发布流程见[开发](./docs/maintainers/development.zh-CN.md)与[测试](./docs/maintainers/testing.zh-CN.md)。
357
113
 
358
114
  ## 许可证
359
115
 
360
- 主题代码采用 MIT 许可证。上游博客的文章不包含在本包中。
116
+ 主题代码为 MIT。上游博客的文章不包含在本包中。
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "clarity-theme",
3
3
  "type": "module",
4
- "version": "0.1.2",
4
+ "version": "0.1.3",
5
5
  "description": "Clarity Theme — 从 blog-v3 提取的可复用 Nuxt 4 Layer 博客主题",
6
6
  "license": "MIT",
7
7
  "publishConfig": {
@@ -129,6 +129,7 @@
129
129
  "lint": "eslint && stylelint \"src/**/*.{vue,scss}\" \"playground/app/**/*.vue\"",
130
130
  "lint:fix": "eslint --fix && stylelint \"src/**/*.{vue,scss}\" \"playground/app/**/*.vue\" --fix",
131
131
  "typecheck": "pnpm --dir playground typecheck",
132
+ "docs:check": "node scripts/check-docs.mjs",
132
133
  "verify": "node scripts/verify-theme.mjs",
133
134
  "test:sync": "node --test tests/sync-upstream.test.mjs",
134
135
  "test:migration": "node --test tests/migration-skill.test.mjs",
@@ -136,6 +137,9 @@
136
137
  "test:release": "pnpm verify && pnpm test:consumer && pnpm test:compatibility",
137
138
  "test:consumer": "node scripts/test-consumer.mjs",
138
139
  "test:compatibility": "node scripts/test-compatibility.mjs",
140
+ "test:create": "pnpm --dir create-clarity-theme test",
141
+ "test:create:e2e": "pnpm --dir create-clarity-theme test:e2e",
142
+ "test:create:tarball": "pnpm --dir create-clarity-theme test:tarball",
139
143
  "test:registry-consumer": "node scripts/test-registry-consumer.mjs",
140
144
  "release:check": "node scripts/release-check.mjs",
141
145
  "sync:check": "node scripts/sync-upstream.mjs check",
package/src/components/widget/BlogTech.vue CHANGED
@@ -27,6 +27,8 @@ const ciPlatform = computed(() => {
27
27
 
28
28
  const service = computed(() => ([
29
29
  ...ci ? [{ label: '构建平台', value: ciPlatform }] : [],
30
+ { label: '图片存储', value: () => [h(Icon, { name: 'devicon:cloudflare' }), ' R2'] },
31
+ { label: '软件协议', value: 'MIT' },
30
32
  { label: '文章许可', value: clarity.site.copyright?.abbr || '未配置' },
31
33
  { label: '规范域名', value: getDomain(clarity.site.url) },
32
34
  ]))
package/src/config/define.mjs CHANGED
@@ -13,7 +13,7 @@ export function defineClarityConfig(config) {
13
13
  .join('\n')
14
14
  throw new Error(
15
15
  `clarity.config.ts 校验失败：\n${issues}\n`
16
- + '未知字段会被拒绝：请检查拼写，或参考 docs/config-api-audit.md 的字段归属表。',
16
+ + '未知字段会被拒绝：请检查拼写，或参考 docs/guides/configuration.md 的字段契约。',
17
17
  { cause: result.error },
18
18
  )
19
19
  }
package/src/config/define.ts CHANGED
@@ -15,7 +15,7 @@ export function defineClarityConfig(config: ClarityConfigInput): ClarityConfig {
15
15
  .join('\n')
16
16
  throw new Error(
17
17
  `clarity.config.ts 校验失败：\n${issues}\n`
18
- + '未知字段会被拒绝：请检查拼写，或参考 docs/config-api-audit.md 的字段归属表。',
18
+ + '未知字段会被拒绝：请检查拼写，或参考 docs/guides/configuration.md 的字段契约。',
19
19
  { cause: result.error },
20
20
  )
21
21
  }
package/src/config/public.ts CHANGED
@@ -10,7 +10,7 @@ import type {
10
10
  /**
11
11
  * 由 clarity.config.ts 注入 appConfig 的客户端可见配置。
12
12
  *
13
- * 可见性约定（详见 docs/config-api-audit.md）：
13
+ * 可见性约定（详见 docs/guides/configuration.md）：
14
14
  * - 只有客户端渲染确实需要的字段进入 appConfig；
15
15
  * - feed、完整 stats、features 与 site.author.email 等服务端/构建期字段
16
16
  * 改由 Nitro 私有 runtimeConfig 提供（config/server.ts），不进入客户端 bundle；