JSDoc首页读取README.md文件内容显示异常问题求助
问题原因
jsdoc.json配置文件中source.excludePattern参数的正则表达式错误,当前配置的正则末尾多了冗余下划线_,错误的过滤规则会干扰JSDoc的文件解析逻辑,导致README内容无法正常渲染。- README.md中使用了HTML注释语法,部分版本的JSDoc markdown插件解析HTML注释时会出现适配问题,破坏页面排版结构。
- 若执行JSDoc构建命令的工作目录与README.md存放目录不一致,
opts.readme填写的相对路径README.md也会导致文件读取失败,引发显示异常。
修复方案
- 修正
jsdoc.json中的excludePattern配置,删除末尾多余的下划线,同时将readme路径补全为更稳妥的相对路径写法,修正后的完整配置如下:
{ "source": { "include": ["src"], "includePattern": ".+\\.js(doc|x)?$", "excludePattern": "(node_modules/|docs)" }, "plugins": ["plugins/markdown"], "tags": { "allowUnknownTags": true, "dictionaries": ["jsdoc","closure"] }, "templates": { "cleverLinks": true, "monospaceLinks": true }, "opts":{ "recurse": true, "destination": "./docs/", "tutorials": "./tutorials", "readme": "./README.md" } }
- 调整README.md的注释写法,将HTML注释替换为标准Markdown注释
[comment]: <> (注释内容),不需要保留的注释直接删除即可,修正后的README示例:
# LearningJenkins ## Tutorials [Link to tutorials](https://codenameninja.github.io/LearningJenkins/)
- 删除已生成的旧
docs目录,重新执行JSDoc构建命令即可正常渲染。
内容的提问来源于stack exchange,提问作者Mitchell Yuen
相关产品推荐
相关产品推荐

