在GitHub Pages的Jekyll站点中嵌入交互式R-Markdown HTML文件的问题

问题根源 #

你碰到的报错，是因为R Markdown生成的HTML里包含{{ ... }}格式的JavaScript代码（比如plotly的渲染逻辑），被GitHub Pages的Liquid模板引擎误判为未闭合的变量标签，导致渲染失败。而格式错乱则是因为Jekyll的Markdown解析器把R代码块当成了LaTeX公式，同时Gradfolio的样式覆盖了R Markdown的默认样式。

解决方案 #

方案1：用iframe嵌入（推荐，完整保留交互和格式） #

这是最稳妥的方法，直接把R Markdown生成的HTML作为独立页面嵌入，完全规避Jekyll的解析冲突：

1. 在GitHub仓库根目录新建assets/html文件夹，把RStudio编织好的项目HTML文件放进去
2. 在Projects栏目对应的.md文章里添加以下代码：

   <iframe src="/assets/html/你的项目文件名.html" width="100%" height="800px" frameborder="0"></iframe>
   

   • 可根据内容长度调整height值
   • 这种方式会完整保留plotly的悬停提示、代码块格式和所有交互效果，不会被Jekyll或Gradfolio的样式干扰

方案2：转义Liquid语法（适合不想用iframe的场景） #

如果必须直接嵌入HTML内容，需要先处理Liquid语法冲突，再避免样式覆盖：

1. 打开R Markdown生成的HTML文件，全局替换：
   • 把所有{{替换为{{ '{{' }}
   • 把所有}}替换为{{ '}}' }}
     这样Jekyll渲染时会把这些转义成原始的大括号，不会当成模板变量解析
2. 将处理后的HTML文件放到仓库的_includes目录下
3. 在Projects的.md文章里用raw标签包裹include语句，防止Liquid解析内容：

   {% raw %}
   {% include 你的项目文件名.html %}
   {% endraw %}
   

4. 为避免Gradfolio样式覆盖R Markdown格式，在R Markdown文件开头添加自定义CSS隔离：

   ---
   title: "你的项目标题"
   output:
     html_document:
       css: custom.css
   ---
   

   然后在custom.css里添加：

   .rmarkdown-container {
     all: unset;
     width: 100%;
   }
   

   并把R Markdown生成的HTML内容包裹在<div class="rmarkdown-container"></div>里

注意事项 #

• 方案1的iframe方法无需修改任何R Markdown生成的文件，操作最简单，且能100%还原本地打开的效果
• 方案2需要处理代码转义和样式隔离，容易出现样式冲突，仅在特殊场景下使用

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