PortalJS项目中标题提取逻辑的优化与实现

在PortalJS项目中，我们近期优化了Markdown文档标题的提取逻辑。本文将详细介绍这一改进的背景、技术实现及其重要性。

背景分析 PortalJS作为文档站点生成工具，需要智能地处理文档标题显示问题。当文档未明确设置标题时，系统会自动从内容中提取标题。原实现存在两个主要问题：

1. 提取范围过广：不仅会提取h1标题，还会降级提取h2标题
2. 提取位置不精确：会提取文档中任意位置的标题

技术改进 新版本实现了更严格的标题提取规则：

1. 优先级规则：仅当文档没有设置title元数据时才会尝试提取
2. 层级限制：只识别h1级别的标题（#开头的Markdown语法）
3. 位置要求：标题必须是文档正文的第一个非空内容（忽略前导空白和元数据）

实现意义 这一改进带来了多重好处：

1. 一致性：确保所有文档遵循统一的标题显示规则
2. 可预测性：开发者可以准确预判系统将如何显示文档标题
3. 语义正确：h1作为最高级标题，最能代表文档主题

升级注意 需要注意的是，现有站点需要重新构建才能使这一改进生效。这是因为标题提取是在构建阶段完成的，改进后的逻辑需要重新处理所有文档。

最佳实践建议

1. 显式设置title元数据是最可靠的方式
2. 如需自动提取，确保在文档开头使用单个h1标题
3. 避免在文档开头放置其他内容（如引言段落）后再使用h1

这一改进体现了PortalJS对文档处理严谨性的追求，使自动生成的文档结构更加合理和可维护。