Doxygen首页内容由mainpage.dox文件控制，需置于INPUT路径下、以Doxygen注释标记开头并匹配MAIN_PAGE配置，否则将被静默忽略。
Doxygen首页内容由哪个文件控制
Doxygen的首页内容默认来自项目根目录下的 mainpage.dox（或 mainpage.h、mainpage.md，取决于配置），不是 index.html 或 Doxyfile 本身。它只在 ENABLED_SECTIONS 或注释块被识别时才生效，且必须在 INPUT 路径中显式包含该文件。
常见错误是把 Markdown 写进 Doxyfile 里，或者放在子目录但没加进 INPUT —— Doxygen 根本不会扫描它。
-
mainpage.dox是最稳妥的选择，支持 Doxygen 命令（如@section、@author）和内联 HTML - 若用
MARKDOWN_SUPPORT = YES，也可用mainpage.md，但部分 Doxygen 特性（如@ref跨模块链接）可能不生效 - 文件名必须匹配
MAIN_PAGE配置项（默认就是mainpage.dox），改名后需同步更新Doxyfile中的MAIN_PAGE
如何让 mainpage.dox 正确被识别并渲染
即使写了 mainpage.dox，Doxygen 也常静默忽略它——根本原因是它没被纳入解析范围。关键检查点有三个：
- 确保
INPUT = .（或包含该文件的路径），不能只写src/却把mainpage.dox放在项目根目录 - 确认
FILE_PATTERNS包含*.dox（默认已启用；若手动清空过，需补上） - 文件开头必须有 Doxygen 注释标记，例如：
/** @mainpage My Project Overview * * This is the landing page... */
，仅写普通 Markdown 或纯文本无效
在首页插入代码示例或模块链接的注意事项
首页常需要展示快速上手代码或跳转到核心模块，但直接贴代码或写链接容易失效：
立即学习“C++免费学习笔记（深入）”；
- 用
@include引入真实源码片段（如@include example.cpp）比手动复制更可靠，避免文档与代码脱节 - 模块链接优先用
@ref module_name而非硬编码 URL；目标模块需有@defgroup或@name定义，否则链接变死链 - 如果首页要显示类图或调用关系，
CLASS_DIAGRAMS = YES必须开启，且对应类得在INPUT中——否则图里一片空白
中文标题、特殊字符与生成失败的排查线索
首页出现乱码、标题不显示或整个页面空白，大概率不是编码问题，而是解析中断：
- Doxygen 对
mainpage.dox中的未闭合注释（如漏掉*/）、非法@命令（如@brief用在非函数上下文）极其敏感，会跳过后续全部内容 - 中文标题没问题，但避免在
@mainpage后直接跟长段落——先换行再写正文，否则可能被截断 - 运行
doxygen -d Preprocessor可查看预处理日志，确认mainpage.dox是否被加载；若无相关输出，说明路径或匹配规则有问题
首页不是模板引擎，没有 layout 概念，所有内容都依赖单个文件的解析完整性。一个错位的星号或缩进异常，就可能导致整页消失。
