Sphinx layout.html模板添加JS后评论区未渲染问题

问题出在脚本插入位置和Utterances的默认挂载逻辑不匹配：

• Utterances脚本加载完成后，默认会在自身script标签的相邻后方插入评论区容器div。你把脚本写在extrahead块时，脚本最终会被渲染到页面<head>标签内部，生成的评论div也会被插入到head节点下。但浏览器只会渲染<body>标签内的可见内容，head内的普通div节点会被直接忽略，不会显示在页面中。
• 你把脚本直接写在Markdown文件底部时，脚本位置处于<body>节点的内容流末尾，生成的评论div会被正常插入到页面内容后方，自然可以正常显示。
• 额外注意：你当前重写extrahead块的写法没有调用{{ super() }}，会直接覆盖sphinx-book-theme原本写在这个块里的meta标签、静态资源引入逻辑，就算评论区问题解决，也可能引发其他样式、功能异常。

1. 不要把Utterances脚本放在extrahead块，改为重写页脚块，修改source/_templates/layout.html的代码如下：

{% extends "!layout.html" %}

{% block footer %}
{{ super() }}
<script
   type="text/javascript"
   src="https://utteranc.es/client.js"
   async
   repo="executablebooks/jupyter-book"
   issue-term="pathname"
   theme="github-light"
   label="💬 comment"
   crossorigin="anonymous">
</script>
{% endblock %}

2. 检查conf.py中的templates_path配置，确保已经包含你存放自定义模板的目录，默认配置为templates_path = ['_templates']，如果你的模板放在source目录下的_templates文件夹，注意路径层级不要写错。
3. 重新构建文档时加上-E参数强制全量重绘，避免缓存导致修改不生效：

sphinx-build -b html -E [你的源码目录] [你的输出目录]

构建完成后所有页面的页脚下方就会正常加载Utterances评论区。

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