跳到主要内容

网站开发规范

TypeScript 风格、命名约定、文档 front matter 的具体规范。

TypeScript​

严格模式。延续现有配置和主题文件风格：

  • 2 空格缩进，保留分号。
  • 尽量保持小函数、单一职责。
  • React 主题覆盖应尽量小而明确，放在 src/theme/<组件名>/ 下。

文档 front matter​

每个 Markdown 文档必须保留 front matter，例如：

---
slug: /health
icon: apple-whole
description: 健康是一套长期系统，目标是在可持续前提下改善身体、情绪、关系和生活质量。
content_type: hub
---

slug​

文件名使用中文，slug 使用 / 开头的简短英文路径，例如 slug: /cybersecurity-law。slug 必须稳定——一旦发布不应随意变更。

icon​

根据主体内容设置合理的 icon。图标系统使用 src/components/ItsHoverIcon/icons/ 下的 ItsHover 图标，或 src/components/ItsHoverIcon/index.tsx 中 ICON_ALIASES 已注册的别名。

新增或修改 icon 前需先确认对应图标真实存在，避免使用未注册的 Lucide 名称导致侧边栏图标缺失。

description（必须）​

所有新文档必须在 front matter 中携带 description。用途：站点 SEO、社交分享卡片的 OG/Twitter 摘要。要求：

  • 长度 ≤ 160 字（中文按字符计，英文按词计）。
  • 高度概括本文的核心结论或核心问题，不复述标题。
  • 避免「本文介绍」「本文探讨」「通过 X 阐述 Y」这类废话开头。
  • 直接陈述价值主张，使用与正文相同的判断语气。
  • 多个并列要点时用顿号或分号分隔，不要写成段落。

content_type（新文档必须）​

content_type 表示页面对读者承担的主要职责。新增文档必须填写，结构性重写旧文档时补齐；修正错别字、链接或格式时不要求顺手迁移。

  • hub：栏目入口，只保留核心判断、当前重点和阅读路径。
  • article：围绕一个问题展开的观点文或方法文。
  • tutorial：可以按步骤复现并验证结果的实操教程。
  • reference：数据、法律原文、清单、术语或长期查询资料。
  • review：年度或阶段复盘，解释结果、原因、错误和后续调整。
  • archive：演讲、旧文等保留历史语境且正文冻结的快照。
  • essay：依靠场景和叙事推进的散文、游记。
  • gallery：以照片或其他媒体归档为主要目的的页面。
  • dashboard：以结构化数据和交互组件为主体的看板。

一页只填写一个主要类型。页面同时包含多种内容时，先判断读者打开它要完成的首要任务；其他任务下沉到独立页面或附录，不用多个类型掩盖职责混杂。

未完成状态不属于内容类型。暂不应公开的提纲、半成品或素材页使用 Docusaurus 的 draft: true，完成编辑后再移除；不能用 archive、gallery 等类型掩盖未完成状态。

last_reviewed（时效内容必须）​

tutorial、reference 以及包含医疗、投资、法律、产品版本、价格或政策结论的时效性 hub、article、review 必须填写最后人工复核日期：

last_reviewed: '2026-07-10'

日期表示正文中的环境、来源和关键结论在当天完成过复核，不等同于文章首次发布时间。只改排版或措辞时不更新；重新验证命令、版本、法规、数据源或判断边界后再更新。

image（可选）​

文档有配图时填写 image，取正文中第一张图的相对路径（相对于 static/）。无图文档不写 image，让社交分享回退到站点默认 OG 图。

sidebar_badge: { text: '演讲' }​

带 演讲 徽标的文章属于历史快照，不修改正文。需更新观点时应复制为新文件后再编辑，原文件保留不动。

sidebar_badge: { text: 'SKILL' }​

带 SKILL 徽标的文档是给 AI 协作助手使用的工作规则文件，统一放在 docs/05-吴飞飞/01-关于/关于FEEI.CN/。读者不必阅读，但维护者更新时需遵循本文档的全部规范。

本章内容大纲