电子书层级内容用语约定

引言 #

在数字化阅读时代，电子书已成为知识传播的主要载体之一。清晰、一致的内容层级结构不仅能够提升阅读体验，还能帮助读者快速定位和理解信息。本文旨在建立一套统一的电子书层级内容用语约定，规范从导航结构到页面内部元素的命名和使用，确保文档的一致性、可读性和可维护性。

第一层：导航结构（左侧大纲） #

导航结构是电子书的骨架，帮助读者在不同页面间快速切换。清晰的导航层级能够降低读者的认知负担，提升内容的可发现性。

• 分类（一级导航）：用于组织相关主题的页面集合，例如 fumadocs 可作为一个分类，包含所有与该文档系统相关的内容。
• 页面（二级导航）：分类下的具体文档页面，例如 fumadocs 目录路由配置 是 fumadocs 分类下的一个具体页面。

第二层：页面内部结构（内容大纲） #

页面内部结构决定了单篇文档的信息组织方式。合理的层级划分能够引导读者循序渐进地理解内容，突出重点信息。

• 主要章节（H2）：页面的核心组成部分，代表内容的主要分支，例如「核心概念」「快速入门」等。
• 主题段落（H3）：每个主要章节下的具体讨论主题，对主要章节进行细化，例如「文件排序机制」是「目录路由配置」章节下的一个主题。
• 要点区（H4）：主题下的关键要点或子主题，用于进一步分解和阐述内容，例如「基于文件名的排序」是「文件排序机制」的一个要点。
• 技术细节（H5）：具体的实现细节、参数说明或技术原理，例如「字节顺序与UTF-8」解释了排序机制的底层技术。
• 备注区（H6）：补充说明、版本信息、兼容性提示或注意事项，例如「注意：非ASCII字符的特殊处理」提供了重要的使用警告。

语义化名称示例 #

为了更直观地展示上述层级结构的实际应用，以下是一个完整的Markdown文档示例，展示了从文档标题到补充说明的各级语义化名称：

1# 目录路由配置                         <- 文档标题
2## 核心概念                            <- 主要部分
3### 文件排序机制                        <- 主题
4#### 基于文件名的排序                   <- 子主题
5##### 字节顺序与UTF-8                   <- 细节
6###### 注意：非ASCII字符的特殊处理     <- 补充说明

文档实践指南 #

除了内容层级的命名约定，良好的文档实践还包括对URL标识（slug）的规范使用。Slug是文档在网络环境中的唯一标识，直接影响文档的可访问性和SEO表现。

1. 使用有意义的 slug #

Slug应准确反映文档内容，避免使用无意义的字符或临时名称：

1# ✅ 推荐
2slug: getting-started  # 清晰表达文档用途
3slug: api-reference    # 明确指示文档类型
4slug: advanced-topics  # 概括内容范围
5
6# ❌ 不推荐
7slug: page1           # 无意义的编号
8slug: doc-2024-01-01  # 仅包含日期，缺乏内容指示
9slug: temp            # 临时名称，不适合长期使用

2. 保持 slug 简洁 #

简洁的slug便于记忆和传播，避免使用过长的描述性短语：

1# ✅ 推荐
2slug: quick-start  # 简洁明了
3
4# ❌ 不推荐
5slug: how-to-get-started-with-our-amazing-product-in-5-minutes  # 过于冗长

3. 使用一致的命名风格 #

选择并坚持一种命名风格，确保整个文档系统的一致性：

1# ✅ 推荐：使用连字符（应用广泛，兼容性好）
2slug: api-reference
3slug: user-guide
4
5# 或者使用下划线（保持内部一致即可）
6slug: api_reference
7slug: user_guide

4. 在配置文件中优先使用 slug #

在文档系统的配置文件（如 meta.json）中，优先使用slug引用页面，提高配置的可读性和可维护性：

1{
2  "pages": [
3    "index",
4    "getting-started",  // ✅ 使用有意义的slug
5    "api-reference"     // ✅ 使用有意义的slug
6  ]
7}

总结 #

建立统一的电子书层级内容用语约定，有助于提升文档的专业性、可读性和用户体验。通过规范导航结构、页面内部层级和slug命名，我们可以创建更加一致、易于维护和使用的电子文档。这些约定不仅适用于技术文档，也可以推广到其他类型的电子书籍和在线内容中，为数字化阅读提供更好的体验。