Frontmatter 配置项详解与示例
本页详细整理了文档中常用的 Frontmatter配置项 和 自定义配置项，提供详细的解释说明以及使用方法，帮助在实际应用中灵活配置
key的命名规则
- 统一采用驼峰式命名，如
lastUpdated - 避免使用连字符形式，如
last-updated
常规Frontmatter配置项
| 配置项 | 说明 |
|---|---|
title | 页面标题 |
description | 页面描述 |
lastUpdated | 最后更新时间 (自动显示更新日期) |
outline | 页面导航 控制右侧大纲栏显示层级 deep：显示所有标题[number]：显示指定层级 |
meta | 自定义数据，可包含多种数据内容组合 |
配置示例:
---
title: 我的文档标题
description: 这是页面的简要描述
lastUpdated: 2025-02-20
outline: deep
meta:
- name: 文档名称
content: 关于内容简介
---核心配置项详解
1 title
作用：浏览器标签页标题 + 左边侧边栏显示名称
最佳实践
# 正确示例 (驼峰式)
title: TypeScript 高级类型解析
# 错误示例 (连字符)
title: typescript-advanced-types2 description
作用：搜索引擎结果摘要 + 页面元描述。
示例对比
# 有效描述 (具体且含关键词)
description: 10个提升React渲染性能的实战技巧，包含memoization、代码分割等方案
# 低效描述 (过于笼统)
description: 本文介绍React性能优化方法AI工具集成
在实际应用中，建议使用AI工具生成更具吸引力的描述内容，以提高搜索引擎排名和用户点击率。
自定义配置项
tags
为文章打上专题标签，用来把分散在不同栏目（新闻、签证、政策、生活等）的文章，自动聚合到一个跨栏目的「专题 / 合订本」页面里。文章仍归属于它原本的栏目，tags 只是额外的聚合入口，无需为专题重复归档。
工作原理
系统会扫描全站 Markdown，凡是同时有 tags 和 title 的页面，就按每个标签归入对应的合订本。需要留意：
tags支持单个字符串，也支持列表（数组），两种写法都可以。- 一篇文章可以带多个标签，会同时出现在多个专题里。
- 必须有
title，否则文章不会被收录。 - 同一专题内的文章按
createdDate倒序排列（缺日期的排最后），日期相同再按标题排序——所以请保持createdDate准确。 - 仅聚合简体中文内容，
docs/en/下的英文镜像会被自动跳过。
使用示例
在文章 frontmatter 中添加 tags：
---
title: H1B RFE 应对策略
description: 拆解 H1B RFE 的常见类型与应对思路
createdDate: 2026-06-15
tags: [h1b-rfe, 签证策略] # 单个标签也可写成 tags: h1b-rfe
---然后在专题（合订本）页面里用 BoundVolume 组件渲染某个标签下的全部文章：
<BoundVolume tag="h1b-rfe" />新增带同名标签的文章后，专题列表会自动更新，无需手动维护合订本页面。完整示例可参考国家安全（合订本）。
requiredRoles
若需限制特定页面的访问权限，可使用requiredRoles配置项对不同用户群体进行权限管理。添加该配置项后，只有具备指定角色的用户才能访问对应页面，未满足条件的用户将无法查看页面内容。
角色说明
| 角色名称 | 说明 |
|---|---|
MANAGER | 管理员，拥有网站最高权限 |
BASIC | 普通用户，仅可访问基础内容 |
使用示例
---
title: 管理员文档
requiredRoles: ["MANAGER"]
---在requiredRoles配置项中列出所有允许访问该文档的用户角色，系统将根据当前用户的角色进行匹配，用户仅需满足其中任意一个角色要求，即可访问该页面。
passwordKey
在文档需要密码保护时，可使用passwordKey配置项设置当前markdown文章的密码密钥，以保护文档内容。用户访问受保护页面时，需输入正确的密码密钥才能查看文档内容。
使用示例
在frontmatter中添加passwordKey配置项，设置当前文档的密码密钥，如下所示：
---
title: 文件名字
passwordKey: passwordKey
lastUpdated: 2025-02-23
---在文件中配合PasswordReveal组件使用，包围住需要密码保护的范围，如下所示：
<PasswordReveal>
<!-- 此处为受保护内容 -->
密码保护内容
</PasswordReveal>expired
在Job Compass中使用，用来标记这个岗位是否还有效，如果这个招聘信息被撤掉了或者岗位关闭了，我们就把它标记为
expired: true