GitHub Pages Markdown代码语法高亮不生效问题咨询

你当前_config.yml里的kramdown+rouge配置本身符合GitHub Pages的构建规范，失效问题按以下优先级排查即可：

• 检查高亮样式文件是否被正确引入
  打开问题页面的开发者工具，在Elements面板查看页面加载的CSS规则，搜索.highlight类对应的样式是否存在。
  这类问题最常见的诱因是自定义站点样式时，覆盖了主题默认的样式入口文件，却没有导入主题自带的rouge高亮样式。你可以直接打开站点根目录下的assets/css/style.scss，确认文件头下方存在以下导入语句：

  ---
  ---
  @import "minimal";
  @import "rouge-github";
  

  如果缺失这两行，直接补上提交即可，主题自带的高亮样式不会自动生效，必须在主样式文件中显式导入。
• 检查Rouge是否正确生成了带语法标记的HTML结构
  查看页面源代码，定位到代码块位置：正常经过Rouge处理的代码块，外层会包裹带class="highlight"的div标签，内部不同语法成分（关键字、注释、字符串等）会带上对应的类名。
  如果代码块只是普通的<pre><code>结构、没有任何highlight相关类名，说明Rouge没有正常处理代码块：
  • 先清理_config.yml中所有和代码高亮相关的冗余配置，不要混入coderay、pygments等其他高亮器的配置项，仅保留你当前贴出的kramdown+rouge配置即可
  • 写代码块时使用GFM标准的三反引号写法，且明确标注语言类型，避免缩进式代码块被识别为普通预格式化文本
  • 不要使用未在GitHub Pages插件白名单内的第三方代码高亮插件，这类插件在云端构建时不会被加载
• 检查自定义CSS是否覆盖了高亮样式
  在开发者工具中选中代码块内的关键字元素，查看CSS规则面板，确认是否存在你自定义的pre、code相关样式设置了全局统一的文字颜色，且优先级高于Rouge生成的高亮样式规则。如果存在这类覆盖，要么调整自定义样式的加载顺序（把自定义基础样式放在Rouge样式之前引入），要么降低自定义规则的选择器优先级。
• 排查本地与云端构建环境的版本差异
  如果本地bundle exec jekyll serve预览时高亮正常，推送到GitHub后失效，说明本地依赖版本和GitHub Pages的构建环境版本不匹配。在站点根目录添加标准Gemfile，指定使用官方github-pages依赖包，提交Gemfile和对应的lock文件后重新触发构建即可，避免kramdown、rouge版本差异导致的语法标记生成异常。

补充说明：Markdown文件在仓库代码浏览页面能正常高亮，和GitHub Pages站点的高亮逻辑完全独立——仓库预览使用GitHub内置的前端高亮逻辑，不依赖Jekyll构建时生成的标记和站点加载的样式，不能作为站点配置正常的判断依据。

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