{ "version": "https://jsonfeed.org/version/1", "title": "Bean Blog", "home_page_url": "https://ccbeango.github.io", "feed_url": "https://ccbeango.github.io/feed.json", "description": "记录工程实践、技术思考与持续学习。", "icon": "https://ccbeango.github.io/favicon.png", "author": { "name": "Bean", "url": "https://ccbeango.github.io" }, "items": [ { "id": "https://ccbeango.github.io/blog/guide/getting-started", "content_html": "

Bean Blog 是一个基于 VitePress 2、Vue 3、TypeScript 和 Tailwind CSS 4 的静态博客。文章保存在仓库中，发布时生成纯静态页面，不需要数据库或应用服务器。

\n

环境要求 ​

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
工具要求
Node.js22.12 或更高版本
pnpm11.24.0
VitePress精确锁定为 2.0.0-alpha.19
\n

VitePress 当前使用 alpha 版本，因此升级版本后应重新检查 Markdown 渲染、标题锚点、系列导航和主题行为。

\n

安装依赖 ​

\n

在项目根目录执行：

\n
powershell
pnpm install --frozen-lockfile
\n
1

pnpm-lock.yaml 已固定完整依赖树。除非确实需要升级依赖，否则不要删除 lockfile 或改用其他包管理器重新生成。

\n

运行开发环境 ​

\n
powershell
pnpm dev
\n
1

默认地址为 http://localhost:5173。正文修改支持热更新；新增文章，或修改文章标题、系列归属与排序后，需要重启开发服务，因为系列 sidebar 在 VitePress 配置阶段生成。

\n

开发环境会显示 draft: true 的文章并标记为草稿。生产构建会从路由、列表、搜索、归档、标签、 sitemap 和 feed 中排除草稿。

\n

项目目录 ​

\n
text
packages/\n  lxgw-wenkai-lite-webfont/ # 自托管中文字体子包\nsrc/\n  .vitepress/\n    build/                  # robots、manifest 与 feed\n    data/                   # 文章校验和集合转换\n    markdown/               # 图片与 Live Photo 扩展\n    theme/                  # 自定义主题与 Tailwind 入口\n    config.ts               # VitePress 配置\n    site.config.ts          # 站点身份和第三方配置\n  posts/                    # Markdown 文章来源\n    guide/                  # 当前使用手册\n  public/                   # 图标、封面和文章媒体\n  blog/                     # /blog 动态路由入口\ntests/                      # Vitest 与 Playwright
\n
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

src/posts 的目录不会公开为 /posts。文章文件的相对路径会转换为 /blog/<nested-slug>。

\n

常用命令 ​

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
命令用途
pnpm dev启动开发服务并预览草稿
pnpm format使用 ESLint 格式化代码和排序 Tailwind class
pnpm lint检查代码规范与格式
pnpm typecheck检查 TypeScript 与 Vue 类型
pnpm test运行单元测试
pnpm audit:styles检查 Tailwind authored styles 边界
pnpm build生成生产静态站点
pnpm test:e2e运行浏览器回归测试
\n

项目不使用 Prettier，也不启用 @antfu/eslint-config 的外部 formatters。VS Code 的保存修复与 Alt+Shift+F、命令行的 pnpm format 都读取同一份 ESLint Flat Config。

\n

.editorconfig、.gitattributes 和工作区 VS Code 设置统一使用 LF，并保证文件末尾换行。JS、TS 与 Vue 代码最多 120 字符；URL、字符串、模板字符串、正则和独立 Tailwind class 属性行不强制拆断。Vue 标签有多个属性时，ESLint 会自动整理为每行一个属性；无法安全自动重排的 TypeScript 长表达式会由 pnpm lint 报告，需要按语义手工换行。

\n

主题不使用 Tailwind 默认色板。颜色、排版、布局尺寸、控件尺寸、圆角、容器、层级、阴影、模糊、媒体比例和动效统一定义在 src/.vitepress/theme/tailwind.css；颜色值全部使用 oklab()。暗色模式通过根节点的 dark:theme-dark 覆盖同名 token，因此普通组件无需为同一语义重复编写 dark: 颜色。完整命名和扩展规则见配置站点信息。

\n

下一步 ​

\n\n", "url": "https://ccbeango.github.io/blog/guide/getting-started", "title": "开始使用 Bean Blog", "summary": "安装依赖、启动开发服务，并了解 Bean Blog 的目录结构与日常命令。", "date_modified": "2026-09-02T00:00:00.000Z", "date_published": "2026-09-02T00:00:00.000Z", "author": { "name": "Bean", "url": "https://ccbeango.github.io" } }, { "id": "https://ccbeango.github.io/blog/guide/site-configuration", "content_html": "

项目有两个配置入口，它们服务于不同层级：

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
文件职责什么时候修改
src/.vitepress/site.config.ts站点名称、作者、导航、社交入口、分页、图标、Feed 和评论搭建自己的博客时需要修改
src/.vitepress/config.tsVitePress 路由、Markdown、侧栏、SEO、资源注入和构建钩子调整工程能力时才修改
\n

日常配置优先集中在 site.config.ts。页面组件和构建逻辑会读取这里的数据，不应在组件中重复写作者名称、域名或社交账号。

\n

环境变量 ​

\n

域名和部署路径由环境变量注入，不建议硬编码到 site.config.ts。

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
变量必填用途示例值
SITE_URL生产构建必填站点完整来源地址，用于 canonical、Open Graph、sitemap、robots 和 Feedhttps://username.github.io
SITE_BASE否站点部署子路径；根站点使用 // 或 /blog/
\n

SITE_URL 不包含末尾 /。SITE_BASE 应同时保留开头和结尾的 /；未设置或设置为 / 时表示部署在域名根路径。

\n

本地开发不要求 SITE_URL。需要检查生产输出时，项目已提供固定占位域名的命令：

\n
powershell
pnpm build:local\npnpm preview
\n
1
2

GitHub Pages workflow 在 .github/workflows/deploy.yml 中声明：

\n
yaml
env:\n  SITE_URL: https://${{ github.repository_owner }}.github.io\n  SITE_BASE: /
\n
1
2
3

如果仓库发布到项目子路径，需要把 SITE_BASE 改成 /<repository>/，并保证 Pages 的实际访问路径与之相同。

\n

站点信息 ​

\n

siteConfig.site 控制全站公共信息和输出路径。

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
配置类型建议修改用途当前值示例
titlestring是VitePress 站点标题、页面标题后缀和首页标题Bean Blog
namestring是页头品牌名和 Web App Manifest 名称Bean Blog
descriptionstring是默认站点描述；页面未单独声明时用于 SEO 和 Feed记录工程实践、技术思考与持续学习。
keywordsstring[]是普通页面的默认 SEO 关键词["VitePress", "前端开发"]
urlstring否从 SITE_URL 读取并移除末尾 /https://username.github.io
basestring否从 SITE_BASE 或 Vite BASE_URL 读取并规范为首尾带 / 的路径/
localestring按需Open Graph 地区代码zh_CN
languagestring按需HTML、VitePress 和 Feed 的语言代码zh-CN
featuredPostsLimitnumber按需首页“推荐阅读”最多展示的最新文章数量5
postsPerPagenumber按需文章列表每页显示的文章数量3
faviconobject是浏览器和设备图标路径，字段见下表见下表
manifeststring按需Web App Manifest 的公开路径/site.webmanifest
feedsobject按需RSS、Atom 和 JSON Feed 的输出路径见下表
\n

图标配置 ​

\n

favicon 的文件应保存在 src/public，配置值使用以 / 开头的公开路径。构建时会自动拼接 SITE_BASE。

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
配置类型建议修改用途当前值
favicon.icostring是兼容性 favicon/favicon.ico
favicon.pngstring是PNG favicon/favicon.png
favicon.svgstring是SVG favicon/favicon.svg
\n

Feed 配置 ​

\n

这些路径同时用于静态文件生成、页面 <head> 声明和站内 RSS 链接。

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
配置类型建议修改用途当前值
feeds.rssstring按需RSS 2.0 主地址/rss.xml
feeds.rssAliasstring按需RSS 兼容别名/index.xml
feeds.atomstring按需Atom Feed 地址/atom.xml
feeds.jsonstring按需JSON Feed 地址/feed.json
\n

作者信息 ​

\n

siteConfig.author 用于首页、文章信息和 Feed 作者信息。

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
配置类型建议修改用途当前值示例
namestring是作者显示名称Bean
emailstring是Feed 等输出中的作者邮箱hello@example.com
biostring是首页作者简介一名持续学习的软件工程师。
\n

导航配置 ​

\n

siteConfig.navigation 是 NavItem[]。有 href 的项目是直接链接，有 children 的项目显示为下拉菜单；children 仍是 NavItem[]，因此支持继续嵌套。

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
NavItem 字段类型必填用途
titlestring是导航显示文字
hrefstring否目标地址；内部地址以 / 开头，外部地址使用完整 HTTPS URL
childrenNavItem[]否子导航列表
\n
ts
const navigation = [\n  { title: \"文章\", href: \"/blog\" },\n  { title: \"使用手册\", href: \"/blog/guide/getting-started\" },\n  {\n    title: \"浏览\",\n    children: [\n      { title: \"标签\", href: \"/tags\" },\n      { title: \"归档\", href: \"/archives\" },\n    ],\n  },\n];
\n
1
2
3
4
5
6
7
8
9
10
11

社交入口 ​

\n

homeSocials 控制首页的文字社交入口。Header 只保留导航、搜索和主题切换，不显示社交图标。

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
SocialLink 字段类型必填用途
labelstring是首页显示文字和链接的无障碍名称
hrefstring是平台地址或站内 Feed 地址
\n
ts
const homeSocials = [\n  { label: \"GitHub\", href: \"https://github.com/username\" },\n  { label: \"RSS\", href: \"/rss.xml\" },\n];
\n
1
2
3
4

没有有效地址的平台应直接从数组中移除，不保留空链接。

\n

Giscus 评论 ​

\n

siteConfig.giscus 的类型是 GiscusConfig | null。不需要评论时保持 null；启用前先在 Giscus 获取仓库和分类参数。

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
配置类型必填用途常用值
repo`${string}/${string}`是已启用 Discussions 的公开仓库owner/repository
repoIdstring是Giscus 提供的仓库 IDR_...
categorystring是Discussion 分类名称Announcements
categoryIdstring是Giscus 提供的分类 IDDIC_...
mapping"pathname" | "url" | "title" | "og:title"是页面与 Discussion 的映射方式pathname
reactionsEnabled"0" | "1"是是否启用主贴表态"1"
inputPosition"top" | "bottom"是评论输入框位置"bottom"
langstring是Giscus 界面语言zh-CN
\n
ts
const giscus = {\n  repo: \"owner/repository\",\n  repoId: \"R_...\",\n  category: \"Announcements\",\n  categoryId: \"DIC_...\",\n  mapping: \"pathname\",\n  reactionsEnabled: \"1\",\n  inputPosition: \"bottom\",\n  lang: \"zh-CN\",\n};
\n
1
2
3
4
5
6
7
8
9
10

全部字段有效时评论区才会加载。组件固定使用 strict="0"、emit-metadata="0" 和 loading="lazy"；评论主题会自动跟随 VitePress 的 appearance 状态，不需要在配置中重复声明。

\n

VitePress 基础配置 ​

\n

src/.vitepress/config.ts 导出异步 UserConfigFn<DefaultTheme.Config>。它组合 site.config.ts、文章数据和 Markdown plugins，属于工程基础设施；只更换博客信息时不需要改这个文件。

\n

顶层选项 ​

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
配置当前值或来源建议修改作用
langsiteConfig.site.language否设置文档和 HTML 语言
titlesiteConfig.site.title否设置全站标题
titleTemplate`:title | ${siteConfig.site.title}`按需组合页面标题与站点标题
descriptionsiteConfig.site.description否设置默认页面描述
basesiteConfig.site.base否设置 VitePress 部署基础路径
srcExclude["posts/**/*.md"]否不让源文章直接生成 /posts/... 页面；文章由 /blog 动态路由统一发布
cleanUrlstrue按需生成不带 .html 的公开 URL
lastUpdatedtrue按需让 VitePress 收集 Git 最后更新时间
appearancetrue按需启用 VitePress 明暗模式状态和切换能力
themeConfig.sidebar自动生成否根据文章 frontmatter 的 series 生成官方格式 sidebar
vite.plugins[tailwindcss()]否使用 Tailwind CSS 4 的 Vite plugin 处理主题样式
\n

配置函数还会根据 command 区分环境：开发服务的系列侧栏包含草稿，生产构建会排除草稿；执行生产构建前调用 requireSiteUrl()，缺少 SITE_URL 时主动失败，避免发布带错误绝对地址的页面。

\n

Markdown 选项 ​

\n

这些能力由 VitePress 官方 Markdown 配置和 markdown-it plugins 提供，自定义主题只负责展示，不重复实现解析行为。

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
配置当前值作用
markdown.lineNumberstrue代码块显示行号
markdown.mathtrue启用数学公式解析
markdown.image.lazyLoadtrue为普通 Markdown 图片启用原生懒加载
markdown.codeCopyButton.tooltipText复制代码复制按钮默认提示文字
markdown.codeCopyButton.copiedText已复制复制成功后的提示文字
markdown.theme.lightgithub-light亮色模式 Shiki 代码主题
markdown.theme.darkgithub-dark暗色模式 Shiki 代码主题
\n

Custom Containers 使用 VitePress 保留的英文关键字，界面标题改为中文：

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
英文关键字默认中文标题
info信息
note备注
tip提示
important重要
warning警告
danger危险
caution注意
details详细信息
image-grid图片布局
live-photoLive Photo
\n

markdown.config(md) 依次注册下列 plugins：

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
plugin作用
markdown-it-task-lists将 Markdown 任务列表转换为可访问的 checkbox markup
imageGridPlugin解析 ::: image-grid 多图布局
livePhotoPlugin解析 ::: live-photo 并输出可播放的 Motion Photo
photoPreviewPlugin为普通图片和图片布局补充统一照片预览数据
\n

具体写法分别见《使用 Markdown 扩展》《编排多图布局》和《使用 Live Photo》章节。

\n

Sitemap、head 与构建钩子 ​

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
配置启用条件作用
sitemap.hostname存在 SITE_URL使用站点来源地址生成 sitemap
sitemap.transformItemssitemap 已启用从 sitemap 中排除 404 页面
head始终注入 favicon、manifest、RSS、Atom 和 JSON Feed 链接
transformHead每个页面生成 description、keywords、canonical、Open Graph 和 Twitter Card metadata
buildEnd构建结束调用 generateStaticAssets(config.outDir) 生成 Feed、robots 和 manifest 等静态文件
\n

transformHead 优先使用动态页面参数中的 title、description、keywords、url 和 canonical，缺失时回退到页面数据及 siteConfig.site。带文章 slug 的页面输出 og:type=article，其它页面输出 website。

\n

配置辅助函数 ​

\n

site.config.ts 还导出三个辅助函数，通常不需要修改：

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
函数用途
isGiscusConfigured()检查 Giscus 必填字段是否完整，供评论组件决定是否加载
requireSiteUrl()在生产构建开始时确认 SITE_URL 已设置
withBasePath()为站内公开资源拼接规范化后的 SITE_BASE，外部 URL 保持不变
\n

主题设计令牌 ​

\n

项目参考 shadcn-vue 的语义主题方式，将可复用视觉值集中放在 src/.vitepress/theme/tailwind.css 的 @theme 中。组件以 Tailwind utility 为主，不直接读取具体颜色或尺寸数值。唯一例外是 ArticlePage.vue 底部的 <style scoped>：它负责适配 VitePress 动态生成的 Markdown DOM，并直接读取相同的设计令牌。该适配层使用标准 CSS Nesting 将规则收拢在 .article-content 下，由现有 Tailwind CSS 4 + Vite 构建链处理，不需要额外的 nesting 插件或 PostCSS 配置。

\n

颜色角色 ​

\n

Tailwind 默认颜色命名空间已经关闭。通用 surface 使用基础 token / -foreground 配对，保证背景和其上的内容一起变化：

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
分组token用途
页面background / foreground页面画布与默认正文
容器card / card-foreground、popover / popover-foreground内容卡片与浮层
操作primary、secondary、accent 及各自 -foreground主要操作、次要表面、hover 与 active 状态
辅助muted / muted-foreground低强调表面与辅助文字
边界border、border-strong、ring容器边界、强边界与键盘焦点
遮罩overlay / overlay-foregrounddialog mask 及直接显示在 mask 上的内容
状态info、success、important、warning、destructive、caution 及各自 -foreground容器、Alerts 与草稿提示
代码领域code-background、code-card、code-muted-foreground、code-border、code-accent 和代码行状态固定深色代码画布
\n

所有 --color-* 和阴影中的颜色必须使用 oklab()。亮色值定义在 @theme；@utility theme-dark 只覆盖确实不同的同名 token。根布局通过 dark:theme-dark 一次加载暗色值，组件继续使用 bg-background、text-foreground、border-border 等相同 utility。照片预览与搜索 dialog 的 mask 都使用 overlay；照片预览内直接落在 mask 上的图标和信息栏使用其通用配对 overlay-foreground，LIVE 标识和页面侧栏入口继续复用其它通用角色，不为单个组件建立专属色板。只有固定代码画布这类通用角色确实无法表达的功能才建立领域前缀，不能按页面或某次使用创建 header-*、search-* 一类颜色。

\n

可维护尺度 ​

\n

除颜色外，项目集中管理所有对博客有长期价值的设计尺度：

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
类别namespace当前用途
字体与字重font-*、font-weight-*中文正文字体、代码字体和字体包真实提供的 400 / 500
字号与行高text-*、leading-*基础 type scale、文章标题/正文/章节、紧凑 label、callout 和代码行高
字距tracking-*全局字距策略与 Live Photo 标识
间距与尺寸spacing、spacing-page-*、spacing-header、spacing-control-*、spacing-side-rail-*基础 4px spacing scale、页面 gutter、页头、控件和侧轨位置
圆角radius、radius-sm 至 radius-xl从单一基准派生的交互控件和容器圆角
容器container-*列表内容、文章正文、三轨布局、导航、搜索和照片详情宽度
响应式breakpoint-sm 至 breakpoint-xl项目实际使用的四个布局断点
层级z-index-content、z-index-control、z-index-navigation内容附属项、浮动控件和导航浮层
景深shadow-*、blur-*卡片、dialog、磨玻璃预览和代码 focus blur
媒体aspect-*横图、竖图、混排图和文章封面比例
动效duration-*、ease-*、animate-*默认过渡、即时缩放、慢速宽度变化、loading 和 Live Photo
\n

基础数值尺度使用 Tailwind 熟悉的 sm、md、lg；只有跨组件且用途稳定的值才使用 page-gutter、side-rail-top 这类语义名称。项目没有表单系统、统计图表或 dashboard sidebar，因此不会照搬 shadcn-vue 中没有实际消费者的 token；照片详情宽度属于稳定布局尺寸，可以保留 container-photo-inspector，但这不意味着照片功能需要独立颜色领域。

\n

新增与修改规则 ​

\n

调整全站视觉时先修改已有 token。确需新增时，先确认它满足以下条件：在多个位置重复，或代表不会随组件名称变化的稳定语义；名称描述角色而非颜色值或当前页面；有源码消费者和必要的回归断言。surface 颜色必须补齐 -foreground 配对，独立领域内部也遵循 background、foreground、card、muted、border、accent 等一致后缀。

\n

视口 calc()、响应内容的 minmax() grid track、伪元素 content 和组合 transition property 依赖上下文，可以保留 arbitrary value。普通字号、字距、圆角、模糊、图片比例和动画已有命名尺度，不得再写 arbitrary value。不要使用 Tailwind 内置色板或任意硬编码颜色，也不要在文章 Markdown 适配层以外新增普通 CSS；pnpm audit:styles 会检查唯一 scoped CSS 例外、必需 namespace、颜色配对和旧 token 回归。

\n

发布前检查 ​

\n

发布前至少确认：

\n\n", "url": "https://ccbeango.github.io/blog/guide/site-configuration", "title": "配置站点信息", "summary": "完整说明站点身份、作者、导航、社交入口、评论，以及 VitePress 工程配置。", "date_modified": "2026-09-01T00:00:00.000Z", "date_published": "2026-09-01T00:00:00.000Z", "author": { "name": "Bean", "url": "https://ccbeango.github.io" } }, { "id": "https://ccbeango.github.io/blog/guide/writing-articles", "content_html": "

每篇文章都是 src/posts 下的 Markdown 文件。新增文件并填写 frontmatter 后，文章会自动进入列表、标签、归档、搜索和 feed，不需要再维护一份文章清单。

\n

文件路径与公开 URL ​

\n

文件相对 src/posts 的路径就是完整 slug：

\n
text
src/posts/guide/writing-articles.md -> /blog/guide/writing-articles\nsrc/posts/travel/2026/sichuan.md     -> /blog/travel/2026/sichuan
\n
1
2

slug 支持多个路径段，但完整 slug 必须唯一。文章来源目录不会生成 /posts 公开路由。

\n

Frontmatter 示例 ​

\n
yaml
---\ntitle: 文章标题\ndate: 2026-09-01\nupdated: 2026-09-02\nsummary: 列表与 feed 使用的摘要\ndescription: SEO description，省略时使用 summary\nkeywords:\n  - VitePress\n  - 静态博客\nfeatured: true\nseries:\n  name: 内容写作\n  order: 1\n  sidebar: Bean Blog 使用手册\n  sidebarOrder: 2\ntags:\n  - 工程实践\ndraft: false\ncover: /media/live-photo-sample-poster.png\ncanonical: https://example.com/original-article\n---
\n
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
字段必填说明
title是非空文章标题
date是可解析日期，建议使用 YYYY-MM-DD
updated否最近更新日期
summary否首页、列表、搜索和 feed 摘要
description否SEO description，省略时回退到 summary
keywords否SEO 与搜索关键词数组
featured否是否进入首页“推荐阅读”，默认 false
series否自动系列侧栏信息
tags否标签数组，会规范化、去重和计数
draft否草稿状态，默认 false
cover否src/public 下资源的根路径地址
canonical否内容另有首发地址时使用的完整 URL
\n

无效日期、错误字段类型或重复 slug 会让配置加载失败，并在错误中指出对应文件和字段。

\n

草稿与精选文章 ​

\n

draft: true 的文章只在开发环境中出现，并显示“草稿预览”。生产环境会从所有公开入口排除草稿，包括系列 sidebar、搜索、标签、归档、sitemap 和 feed。

\n

featured: true 只控制文章是否进入首页“推荐阅读”候选，不会影响 /blog 列表中的可见性。首页按日期从新到旧最多展示 siteConfig.site.featuredPostsLimit 篇，默认上限为 5；超过上限的推荐文章仍可在 /blog 中访问。发布前将 draft 改为 false，再按需要设置 featured。

\n

仓库中的 src/posts/guide/draft-preview.md 是草稿过滤的可运行示例。

\n

单系列侧栏 ​

\n

为文章添加同名 series.name，再使用正整数 series.order 控制顺序：

\n
yaml
series:\n  name: TypeScript 入门\n  order: 1
\n
1
2
3

同一系列不能重复使用相同 order。新增系列文章只需填写 frontmatter，不需要修改 site.config.ts 或手写 themeConfig.sidebar。

\n

多分组侧栏 ​

\n

多个系列需要同时出现在左侧时，为它们设置相同 sidebar，并用 sidebarOrder 排列分组：

\n
yaml
# “入门与配置”系列\nseries:\n  name: 入门与配置\n  order: 1\n  sidebar: Bean Blog 使用手册\n  sidebarOrder: 1
\n
1
2
3
4
5
6
yaml
# “内容写作”系列\nseries:\n  name: 内容写作\n  order: 1\n  sidebar: Bean Blog 使用手册\n  sidebarOrder: 2
\n
1
2
3
4
5
6

sidebar 是内部关联作用域，不会显示在页面中。sidebar 与 sidebarOrder 必须成对填写；同一系列的声明必须一致，同一 sidebar 中不同系列的 sidebarOrder 不能重复。

\n

系列 sidebar 在 VitePress 启动时生成。新增文章或修改标题、系列归属、sidebar 与顺序后需要重启开发服务。左侧系列导航用于切换手册文章，右侧本文目录用于定位当前文章标题，两者互不替代。

\n

图片与静态资源 ​

\n

将公开资源放在 src/public 的明确子目录中，并在 Markdown 中使用根路径：

\n
md
![图片说明](/media/live-photo-sample-poster.png)
\n
1

为图片提供有意义的 alt。普通正文图片由 VitePress 增加 loading="lazy"；文章封面通过 frontmatter 的 cover 设置。

\n

文章封面 ​

\n

在 frontmatter 中填写 cover，即可在文章标题上方显示封面：

\n
yaml
cover: /media/live-photo-sample-poster.png
\n
1

封面文件放在 src/public 中，配置值使用从站点根路径开始的公开地址。封面下缘会渐隐到当前主题的页面背景，标题轻微上移到过渡区，让图片与文章信息形成连续头部；没有 cover 时不会生成空占位，也不会改变标题间距。点击封面可以进入与正文图片相同的照片预览，并支持缩放、拖动和照片信息查看。

\n

发布一篇文章 ​

\n
    \n
  1. 在 src/posts 下创建 Markdown 文件。
    2. \n
  2. 填写 title、date 和需要的可选 frontmatter。
    3. \n
  3. 使用 pnpm dev 检查正文、目录、图片和窄屏布局。
    4. \n
  4. 确认完整 slug、系列 order 与 sidebarOrder 没有冲突。
    5. \n
  5. 将 draft 设置为 false，提交文章及引用的静态资源。
    6. \n
\n", "url": "https://ccbeango.github.io/blog/guide/writing-articles", "title": "创建和组织文章", "summary": "说明文章路径、frontmatter、草稿、精选文章、系列侧栏与静态资源的写法。", "date_modified": "2026-08-31T00:00:00.000Z", "date_published": "2026-08-31T00:00:00.000Z", "author": { "name": "Bean", "url": "https://ccbeango.github.io" } }, { "id": "https://ccbeango.github.io/blog/guide/markdown-extensions", "content_html": "

文章默认支持标准 Markdown、VitePress 官方扩展和少量已注册的 Vue 内容组件。本页中的示例就是当前主题的真实渲染结果，也由自动化测试直接验证。

\n\n

表格与任务列表 ​

\n

GFM 表格和任务列表无需额外配置：

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
能力构建阶段浏览器阶段
代码高亮Shiki复制按钮
搜索索引生成本地匹配
目录标题提取章节跟踪
\n\n

数学公式 ​

\n

行内公式 E=mc2 可以直接出现在段落中。块级公式使用成对的 $$，在窄屏中会限制在正文宽度内：

\nT(n)=T(n−1)+O(1)=O(n)

代码块 ​

\n

fenced code block 只需要声明语言。高亮、语言标签和复制行为均由 VitePress 与 Shiki 提供：

\n
ts
interface Post {\n  title: string;\n  slug: string;\n  draft?: boolean;\n}\n\nconst published = (posts: Post[]) => posts.filter(post => !post.draft);
\n
1
2
3
4
5
6
7

Custom Containers ​

\n

基础容器包括 info、tip、warning、danger 和原生可展开的 details。默认标题已经配置为中文。

\n

默认标题 ​

\n

信息

\n

适合补充背景、上下文或中性说明。

\n
\n

提示

\n

适合给出建议、最佳实践或更便捷的做法。

\n
\n

警告

\n

适合提醒需要留意但仍可继续的情况。

\n
\n

危险

\n

适合说明可能造成数据丢失或不可逆影响的操作。

\n
\n
详细信息\n

这是浏览器原生的可展开内容，默认保持收起。

\n
\n

自定义标题 ​

\n

在容器类型后直接添加标题：

\n

停止

\n

危险区域，请先确认影响范围再继续。

\n
\n
点击查看代码\n
ts
const message = \"Hello, VitePress!\";
\n
1
\n

GitHub Alerts ​

\n

GitHub 风格 Alerts 支持 NOTE、TIP、IMPORTANT、WARNING 和 CAUTION：

\n

备注

\n

用于补充读者应该了解的信息。

\n
\n

提示

\n

用于帮助读者更顺利地完成操作。

\n
\n

重要

\n

用于强调完成目标所必需的信息。

\n
\n

警告

\n

用于提示需要立即关注的风险。

\n
\n

注意

\n

用于说明某个操作可能带来的负面后果。

\n
\n

Code Groups ​

\n

Code Group 使用带标题的 fenced code block，标签切换由 VitePress 客户端处理：

\n
\n
sh
pnpm dev
\n
1
sh
npm run dev
\n
1
\n

代码行状态 ​

\n

行高亮、focus、diff、error 和 warning 使用 VitePress/Shiki 标记：

\n
ts
const stable = true;\nconst focused = true; \nconst added = \"new\"; \nconst removed = \"old\"; \nconst invalid = false; \nconst pending = true;
\n
1
2
3
4
5
6

标题锚点与内部链接 ​

\n

二级和三级标题由 VitePress 自动生成锚点。点击标题左侧的 # 或右侧本文目录后，URL hash 会更新，固定页头也不会遮挡目标标题。

\n

普通内部链接使用公开 /blog 地址。需要显示更完整的入口时，可以使用已注册的 LinkedCard：

\n

不要在 Markdown 中任意引入 Vue 组件。新增内容组件时，应在 theme enhanceApp 中注册，并补充 renderer 和浏览器测试。

\n

普通图片 ​

\n

普通图片继续使用标准 Markdown 语法，并提供有意义的 alt：

\n

\"Markdown

\n

VitePress 会为正文图片增加原生 loading="lazy"。多张图片的组合方式见编排多图布局。

\n", "url": "https://ccbeango.github.io/blog/guide/markdown-extensions", "title": "使用 Markdown 扩展", "summary": "通过可直接运行的示例使用 GFM、数学公式、代码块、容器、Alerts、Code Groups 和内容组件。", "date_modified": "2026-08-30T00:00:00.000Z", "date_published": "2026-08-30T00:00:00.000Z", "author": { "name": "Bean", "url": "https://ccbeango.github.io" } }, { "id": "https://ccbeango.github.io/blog/guide/image-layouts", "content_html": "

普通 Markdown 图片不需要特殊写法，会独占正文宽度并按文章顺序出现。

\n

\"海边的横向风景\"

\n

点击普通图片或多图布局中的任意图片，会先以全屏纯图模式完整展示原图。右上角的详情 icon 可以切换拍摄信息：宽屏时照片在左、信息在右，窄屏时改为上下排列。再次点击 icon 会恢复纯图模式，按 Escape 或右上角关闭按钮退出预览。

\n

桌面端可以把鼠标移到照片上滚动滚轮缩放，并在放大后按住左键拖动平移。双击照片或点击右上角出现的重置 icon 都会恢复原尺寸和居中位置；触控设备仍使用原生滚动，不会接管双指手势。

\n

拍摄信息在打开详情后才会按需读取，可能包含文件名、尺寸、拍摄时间、相机、镜头、焦距、光圈、快门和 ISO。没有 EXIF 的图片仍可正常预览，只会提示没有可读取的拍摄参数；GPS 不会被读取或展示。远程图片若要显示拍摄信息，需要允许博客域名通过 CORS 读取原文件。

\n

需要组合多张图片时，使用 VitePress 风格的三冒号 container 包围普通图片，并用空行分隔：

\n
md
::: image-grid r73\n![横向图片](/media/live-photo-sample-poster.png)\n\n![纵向图片](/media/live-photo-sample-poster.png)\n:::
\n
1
2
3
4
5

image-grid 是本博客注册的 VitePress Custom Container。构建时，VitePress 负责解析三冒号区块，博客插件再把合法内容增强为响应式布局。

\n

为减少仓库中的演示资源，本页所有格子重复使用同一张 /media/live-photo-sample-poster.png，通过不同布局裁切展示排版效果。实际文章可以为每个位置填写不同的本地路径或图床 URL。

\n

可用布局 ​

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
mode图片数量宽屏布局
landscape2 至 4 张等宽 4:3 横图；四张时为 2×2 宫格
portrait2 至 4 张等宽 3:4 竖图；四张时为 2×2 宫格
r732 张左宽右窄，约 7:3
r372 张左窄右宽，约 3:7
r642 张左宽右窄，约 64:36
r462 张左窄右宽，约 36:64
\n

全部布局在窄屏下都会恢复为单列，并保留 Markdown 源顺序。

\n

等宽横图与四张宫格 ​

\n

landscape 支持两至四张图片。四张图片写在同一个 block 中即可形成 2×2 宫格，不需要新的 mode。

\n
\n

\"山谷中的横向风景\"

\n

\"建筑与天空的横向风景\"

\n

\"山间拱门的横向裁切\"

\n

\"海岸日落的横向裁切\"

\n
\n

等宽竖图 ​

\n

portrait 支持两至四张图片，所有容器使用 3:4 画幅。

\n
\n

\"山间的纵向风景\"

\n

\"光影中的纵向建筑\"

\n

\"海岸边的纵向景色\"

\n
\n

七三布局 ​

\n

r73 让左图更宽、右图更窄，适合一张横图搭配一张竖图。

\n
\n

\"作为主体的横向风景\"

\n

\"作为补充的纵向风景\"

\n
\n

三七布局 ​

\n

r37 将窄图放在左侧、宽图放在右侧。

\n
\n

\"左侧纵向风景\"

\n

\"右侧横向风景\"

\n
\n

六四布局 ​

\n

r64 的宽度差异更克制，左侧使用横向画幅，右侧使用纵向画幅。

\n
\n

\"左侧横向建筑\"

\n

\"右侧纵向建筑\"

\n
\n

四六布局 ​

\n

r46 是六四布局的镜像。

\n
\n

\"左侧纵向建筑\"

\n

\"右侧横向建筑\"

\n
\n

输入约束 ​

\n

block 中只允许普通 Markdown 图片和换行。比例布局固定为两张图片，等宽布局允许两至四张。以下情况会产生包含文件与行号的错误：

\n\n", "url": "https://ccbeango.github.io/blog/guide/image-layouts", "title": "编排多图布局", "summary": "使用 VitePress 三冒号 image-grid 区块，在文章中编排横图、竖图、四张宫格和混合比例图片。", "date_modified": "2026-08-29T00:00:00.000Z", "date_published": "2026-08-29T00:00:00.000Z", "author": { "name": "Bean", "url": "https://ccbeango.github.io" } }, { "id": "https://ccbeango.github.io/blog/guide/live-photo", "content_html": "

Live Photo 在正文中首先是一张普通图片。读者点击左上角的 LIVE 后，动态片段才会在图片原位置播放；再次点击或播放结束后恢复静态首帧。点击首帧的其他区域会打开全屏照片预览，预览左上角同样可以播放 Live Photo，右上角的详情 icon 可以按需读取拍摄参数。

\n

Android Motion Photo 原文件 ​

\n

采用“JPEG 主图后追加 MP4”结构的 Android Motion Photo 可以直接引用原始 .jpg，不需要预先分离视频：

\n
md
::: live-photo android\n![Android Motion Photo 演示](/live-images/android-motion-photo.jpg)\n:::
\n
1
2
3
\n

正文或照片预览中首次播放时，浏览器才会读取 JPEG 二进制、从文件末尾向前定位 MP4 的 ftyp，并创建 video/mp4 Blob。各自停止后再次播放会复用各自的 Blob URL；关闭照片预览或离开文章时会释放对应资源。

\n

使用独立 MP4 ​

\n

已经分离好的静态首帧和浏览器可播放的 MP4 可以直接配对：

\n
md
::: live-photo /media/live-photo-sample.mp4\n![独立 MP4 的静态首帧](/media/live-photo-sample-poster.png)\n:::
\n
1
2
3
\n

独立 MP4 mode 在激活前只加载静态首帧，不提前请求视频。

\n

资源要求 ​

\n

同源文件建议放在 src/public/live-images 或 src/public/media。远程图片必须允许当前博客域名通过 CORS 读取响应；只能由 <img> 显示但不允许跨域读取的地址无法解析 Motion Photo，也无法在预览中读取 EXIF，但仍可作为普通静态图片查看。

\n

CDN、图片压缩服务和对象存储处理链必须保留 Android 原文件，不能重新编码 JPEG、删除文件尾部数据或只返回优化后的静态图。独立视频应使用目标浏览器可播放的 MP4 编码。

\n

当前 Android mode 不转码 HEVC、AV1 等浏览器不支持的编码，也不解析 Apple HEIC 与 MOV 文件对。解析失败或视频无法播放时，组件会恢复为普通静态图片。

\n

区块语法 ​

\n

live-photo 是本博客注册的 VitePress Custom Container。区块内必须且只能包含一张普通 Markdown 图片，图片继续提供静态首帧、alt 和资源地址。

\n

开始行只能使用 ::: live-photo android 或在 live-photo 后提供一个非空 MP4 地址。缺少图片、包含正文、嵌套 block 或遗漏结束 ::: 都会在开发时报告文件与行号。旧的 HTML comment 写法不再解析。

\n", "url": "https://ccbeango.github.io/blog/guide/live-photo", "title": "使用 Live Photo", "summary": "使用独立 MP4 或 Android Motion Photo 原文件，在文章中提供按需播放的动态照片。", "date_modified": "2026-08-28T00:00:00.000Z", "date_published": "2026-08-28T00:00:00.000Z", "author": { "name": "Bean", "url": "https://ccbeango.github.io" } }, { "id": "https://ccbeango.github.io/blog/guide/deployment", "content_html": "

所有平台都安装同一份依赖、执行同一条构建命令，并发布 VitePress 的静态输出目录。

\n

通用构建设置 ​

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
设置值
Install commandpnpm install --frozen-lockfile
Build commandpnpm build
Output directorysrc/.vitepress/dist
Node.js22.12 或更高
必需环境变量SITE_URL=https://你的域名
\n

生产构建缺少 SITE_URL 会失败，避免发布错误的 canonical、robots、sitemap 和 feed URL。

\n

本地验证当前 GitHub Pages 根站点时，可以直接使用已经写入 package.json 的命令：

\n
powershell
pnpm build:local\npnpm preview
\n
1
2

build:local 通过 cross-env 注入 SITE_URL=https://username.github.io 和 SITE_BASE=/，因此在 Windows、macOS 与 Linux 上行为一致。pnpm build 仍要求调用方显式提供发布环境变量。

\n

GitHub Pages ​

\n

当前 workflow 位于 .github/workflows/deploy.yml，在 master 分支 push 或手动触发时构建并发布 src/.vitepress/dist。它直接声明当前根站点配置：

\n
text
SITE_URL=https://username.github.io\nSITE_BASE=/
\n
1
2

workflow 使用 github.repository_owner 动态生成实际 SITE_URL。根站点要求 GitHub 仓库名为 username.github.io，其中 username 替换为仓库所有者，并在仓库 Settings -> Pages -> Build and deployment 中选择 GitHub Actions。普通仓库无法仅通过把 SITE_BASE 改为 / 占用用户根路径。

\n

如果继续使用普通仓库名，例如项目站点 https://username.github.io/bean-blog/，则需要同步修改 workflow：

\n
text
SITE_URL=https://username.github.io\nSITE_BASE=/bean-blog/
\n
1
2

workflow 使用 GitHub Pages 官方 artifact 和 OIDC 部署，不需要个人 Access Token 或手工维护 gh-pages 分支。切换自定义域名后，把 SITE_URL 改为最终 HTTPS 域名；根路径部署时保持 SITE_BASE=/。

\n

Cloudflare Pages ​

\n
    \n
  • Framework preset：None
    • \n
  • Build command：pnpm build
    • \n
  • Build output directory：src/.vitepress/dist
    • \n
  • Environment variables：设置 SITE_URL，子路径部署时再设置 SITE_BASE
    • \n
\n

绑定 custom domain 后，SITE_URL 必须与读者最终访问的 HTTPS origin 一致。

\n

Vercel ​

\n
    \n
  • Framework preset：Other
    • \n
  • Build command：pnpm build
    • \n
  • Output directory：src/.vitepress/dist
    • \n
  • Environment variables：为 Production 设置 SITE_URL
    • \n
\n

Vercel 根域部署通常不设置 SITE_BASE。如果 Preview deployment 也执行生产构建，需要为 Preview 提供对应绝对 URL。

\n

Netlify ​

\n
toml
[build]\ncommand = \"pnpm build\"\npublish = \"src/.vitepress/dist\"
\n
1
2
3

在 Site configuration 中设置 SITE_URL。使用子路径代理时，再设置带首尾 / 的 SITE_BASE。

\n

发布检查 ​

\n
powershell
$env:SITE_URL='https://username.github.io'\n$env:SITE_BASE='/'\npnpm check
\n
1
2
3

pnpm check 会生成资源，校验字体和样式边界，执行 lint、类型检查、单元测试、生产构建、静态产物检查和浏览器回归。

\n

完成后运行 pnpm preview，并确认以下地址可访问：

\n
    \n
  • /robots.txt 与 /sitemap.xml
    • \n
  • /rss.xml、/index.xml、/atom.xml 与 /feed.json
    • \n
  • /site.webmanifest 和 favicon
    • \n
  • /blog、文章详情、标签、归档和分页
    • \n
\n

最后检查 canonical 使用正式域名、草稿没有进入公开产物，并在桌面与移动视口抽查目录、系列导航、代码和媒体内容。

\n", "url": "https://ccbeango.github.io/blog/guide/deployment", "title": "部署与发布", "summary": "配置 SITE_URL 与 SITE_BASE，并将静态产物部署到主流托管平台。", "date_modified": "2026-08-27T00:00:00.000Z", "date_published": "2026-08-27T00:00:00.000Z", "author": { "name": "Bean", "url": "https://ccbeango.github.io" } } ] }