Clarity Theme

English | 简体中文

Clarity Theme 是一个从 L33Z22L11/blog-v3 抽取出来的可复用 Nuxt 4 Layer 博客主题。它提供通用的博客 UI、页面结构、Markdown/MDC 渲染、SEO 集成以及 feed/服务端输出；你的项目只需要提供全部站点数据与内容。

为什么选择 Clarity？

Clarity 取代传统的 sync fork 工作流。你不需要把上游数千行代码合并进博客仓库，而是以 Layer 方式消费主题，只维护自己的文件：

• 一条 extends 配置即可安装完整的博客应用骨架
• Theme 与 Consumer 分离：文章、友链、重定向、部署配置、密钥与依赖补丁永远不会进入主题包
• 配置带校验：clarity.config.ts 由 schema 校验，提供默认值并严格拒绝未知字段
• Content 工厂：Nuxt Content 集合与文章 schema 由你的配置派生
• 富渲染：Markdown、MDC 组件、Shiki 代码高亮、KaTeX、Mermaid、ABC 乐谱与富图片
• 完整输出：文章列表、归档、分页、目录（TOC）、搜索、主题切换、小部件、Atom、OPML、统计、robots、sitemap 与 LLMs
• 集成仍归你所有：Twikoo、head 脚本与反镜像均由消费方配置驱动
• 覆盖而无需 fork：UI app config 覆盖、同路径组件覆盖、自定义 Shiki 主题与消费方 CSS

核心原则

• Clarity 是 blog-v3 的 Layer 化提取，不是重新实现的独立主题。上游 UI、布局与交互默认是 source of truth，除 tests/upstream-parity.manifest.json 中显式记录的机械路径改写外保持 byte-identical。
• 上游硬编码行为优先保留：泛化、配置化与清理属于后续路线，不属于本次 parity。
• 个人站点数据归消费方管理，边界以上游 init-project 重置范围为准。
• 漂移即缺陷：同步面内任何未登记差异都会让 pnpm test:upstream-parity 失败。

选择你的路径

| 起点 | 文档 | | --- | --- | | 新博客 | 创建项目 | | 现有 blog-v3 站点 | 从 blog-v3 迁移 · Agent Skill：migrate-blog-v3-to-clarity | | 手动接入现有 Nuxt 应用 | 手动安装 |

如需 Agent 协助迁移，直接让你的 Agent 使用 migrate-blog-v3-to-clarity Skill。完整 Skill 位于 skills/migrate-blog-v3-to-clarity。

快速开始

pnpm create clarity-theme my-blog
cd my-blog
pnpm dev

创建器会显示可编辑的站点默认值并自动检测系统时区；生成的项目自带 pnpm new-blog 写作命令。

创建包以独立的 create-clarity-theme npm 包分发，稳定版位于 latest dist-tag。完整参数见 create-clarity-theme/README.md。手动接入只需四个文件：

// nuxt.config.ts
export default defineNuxtConfig({
	extends: ['clarity-theme'],
})

// clarity.config.ts
import { defineClarityConfig } from 'clarity-theme/config'

export default defineClarityConfig({
	site: {
		title: 'My Blog',
		description: 'Notes about technology and life',
		url: 'https://example.com/',
		author: { name: 'My Name', avatar: '/avatar.webp' },
	},
})

// content.config.ts
import { createClarityContentConfig } from 'clarity-theme/content'
import clarityConfig from './clarity.config'

export default createClarityContentConfig(clarityConfig)

pnpm add clarity-theme
pnpm dev

文章放在 content/posts/ 下，其他 Content 页面放在 content/ 下。可选的 feeds.ts 友链数据与部署说明见手动安装。

环境要求

| 运行时 | 版本 | | --- | --- | | Node.js | ^22.19 \|\| ^24.11 \|\| >=26 | | pnpm | 12.4.1，或适用于你项目的兼容包管理器 | | Nuxt peer | ^4.5.2 | | Vue peer | ^3.5.42 |

Clarity 属于应用运行时的一部分（Nuxt 构建与静态生成会直接加载 Layer），因此请将其安装为常规依赖，而不是开发依赖。

文档

所有文档都有对应的简体中文版本（同名 *.zh-CN.md 文件）。入口见文档索引：

• 入门 — 创建新项目、手动安装、从 blog-v3 迁移
• 指南 — 配置、内容、自定义、集成
• 参考 — 公共 API、路由与输出、兼容性矩阵
• 概念 — 架构——upstream → sync-manifest → src/ → Layer 模块 → consumer 管线，以及 SOURCE / TRANSFORM / CLARITY-ONLY / LEGACY 源码分类
• 维护者 — 开发、测试与 Parity、上游同步、Transform 面治理、Legacy 政策、补丁、发布、发布清单、项目状态、路线图、文档规则
• 发布历史 — CHANGELOG；历史记录位于 docs/history（冻结叙事——不是现行规范）

开发

pnpm install        # Theme + playground workspace
pnpm dev            # Playground dev server
pnpm generate       # Playground static generation
pnpm lint           # ESLint + Stylelint
pnpm typecheck

完整验证矩阵、上游同步与发布流程见开发与测试。

许可证

主题代码为 MIT。上游博客的文章不包含在本包中。