Doxygen配置FORMULA_MACROFILE不读取宏文件，MathJax报未定义命令错误

问题根因 #

Doxygen的FORMULA_MACROFILE配置项仅作用于原生LaTeX编译生成公式图片的工作流，开启USE_MATHJAX = YES时，Doxygen不会自动将macros.inc中的命令注入到HTML页面的MathJax初始化配置中，因此会出现宏未定义的报错。

解决方案 #

方案1：保留MathJax模式（推荐） #

手动将自定义宏添加到Doxygen生成的HTML页面的MathJax配置中即可，操作步骤如下：

1. 导出Doxygen默认的HTML模板文件：

   doxygen -w html header.html footer.html customdoxygen.css
   

2. 编辑导出的header.html，找到MathJax初始化配置段，在TeX配置块中添加你的自定义宏：
   • 如果你使用的是MathJax 2（Doxygen 1.8及更早版本默认）：

     MathJax.Hub.Config({
       extensions: ["tex2jax.js"],
       jax: ["input/TeX","output/HTML-CSS"],
       TeX: {
         extensions: ["AMSmath.js","AMSsymbols.js"],
         // 添加自定义宏
         Macros: {
           mA: ["\\mathbf{A}", 0]
           // 其余宏按相同格式添加，第二个参数为宏的入参数量，无参填0
         }
       },
       messageStyle: "none"
     });
     

   • 如果你使用的是MathJax 3（Doxygen 1.9及更新版本默认）：

     window.MathJax = {
       tex: {
         macros: {
           mA: "\\mathbf{A}"
           // 带参数的宏写法示例：customMacro: ["\\mathbf{#1}", 1]
         }
       }
     };
     

3. 修改Doxyfile配置，指定使用自定义HTML头：

   HTML_HEADER = header.html
   

4. 重新运行Doxygen生成文档即可。

如果自定义宏数量较多，可以写个简单的脚本批量解析macros.inc中的\newcommand规则，自动转换为MathJax要求的宏格式注入到头文件，无需手动逐一录入。

方案2：切换为LaTeX编译公式图片模式 #

如果不需要MathJax的交互特性，关闭MathJax后FORMULA_MACROFILE会自动生效：

1. 修改Doxyfile配置：

   USE_MATHJAX = NO
   

2. 确保本地环境安装了完整LaTeX发行版（包含latex、dvips、dvisvgm等工具）。
3. 重新运行Doxygen生成文档即可。

内容的提问来源于stack exchange，提问作者Steve Wolligandt