GitHub 小技巧：让仓库里的 HTML 文件变成真正网页
温馨提示：若页面不能正常显示数学公式和代码，请阅读原文获得更好的阅读体验。
作者：艾米丽 (连享会)
邮箱：lianxhcn@163.com
- Title: GitHub 小技巧：让仓库里的 HTML 文件变成真正网页
- Keywords: GitHub Pages, R Markdown, RStudio, Quarto, Jupyter Notebook
很多人用 R Markdown、Quarto 或 Jupyter Notebook 生成过.html文件。本地双击打开时，图表、目录、公式都正常；可是把它上传到 GitHub 仓库后，再点开链接，看到的却是 GitHub 的文件浏览界面。
问题不在 HTML 文件本身，而在链接类型。
GitHub 仓库里的这个链接：
https://github.com/user/repo/blob/main/path/file.html本质上是一个代码浏览链接。它适合看文件内容，但不适合作为网页发给读者。
如果希望读者看到正常渲染后的网页，需要用 GitHub Pages 生成另一个链接：
https://user.github.io/repo/path/file.html本文介绍一个很实用的操作：把 GitHub 仓库中的 HTML 文件发布成可以正常浏览的网页。
1. 问题：GitHub 默认显示的是文件，不是网页
下面这张图是一个已经上传到 GitHub 仓库中的 HTML 文件。
可以看到，地址栏中的链接是：https://github.com/lianxhcn/lianxh_blog/blob/main/codes/B875-Viviens-2026-DID_CIC_simu_R_codes.html。这个页面不是网页预览页，而是 GitHub 的文件浏览页。它会把.html文件当作仓库中的一个文件展示，而不是当作一个网页发布出来。
这也是很多 RStudio 用户经常遇到的问题：本地生成的 HTML 报告没有问题，但上传到 GitHub 后，读者无法直接看到网页效果。
2. 方法：启用 GitHub Pages
解决方法是启用 GitHub Pages。
在仓库页面中，点击Settings，然后在左侧找到Pages。在Build and deployment部分，把Source设为Deploy from a branch，分支选择main，目录一般选择/(root)。
设置完成后，GitHub 会给这个仓库生成一个 Pages 地址。以后仓库中的静态网页文件就可以通过github.io域名访问。
对本文这个例子来说，原始文件链接是：
https://github.com/lianxhcn/lianxh_blog/blob/main/codes/B875-Viviens-2026-DID_CIC_simu_R_codes.html
对应的网页链接是：
带有样本选择的 DID 和 CiC：模拟附件
链接转换规则可以这样理解：
https://github.com/user/repo/blob/main/path/file.html改成：
https://user.github.io/repo/path/file.html其中，user是 GitHub 用户名或组织名，repo是仓库名，path/file.html是 HTML 文件在仓库中的相对路径。
3. 结果：HTML 文件可以正常渲染为网页
设置完成后，再打开新的github.io链接，就能看到正常的 网页效果。
这时，读者看到的不再是 GitHub 文件页面，而是完整渲染后的 HTML 报告。R Markdown 或 Quarto 生成的目录、代码块、图形和表格都可以正常显示。
这个技巧适合很多场景：
- 把 R Markdown 生成的课程讲义发布给学生；
- 把论文复现代码的运行结果做成在线附件；
- 把模拟代码、图形生成过程和结果说明放在 GitHub 仓库中；
- 把
.ipynb、.qmd或.Rmd转出的 HTML 报告发给合作者； - 给推文或论文附录提供一个长期可访问的网页链接。
对经管类论文写作来说，这个方法尤其适合存放复现材料。读者不需要下载整个仓库，也不需要在本地配置 R 或 Python 环境，打开网页链接就能看到代码、图形和结果说明。
4. 几个常见问题
如果新链接打不开，通常有以下几种原因。
GitHub Pages 刚设置完成后，不一定马上生效。可以等几分钟再刷新。
如果页面显示404，先检查仓库名、用户名和文件路径是否写对。GitHub 的路径区分大小写，文件名中的大小写、下划线和连字符都要保持一致。
如果网页能打开，但图形没有显示，通常是 HTML 文件中的图片路径仍然指向本地电脑。例如：
C:/Users/yourname/Desktop/fig1.png这种路径只在自己的电脑上有效。要让网页正常显示图片，应把图片一起上传到仓库，或者使用稳定的在线图床链接。
如果 GitHub Pages 选择的是/docs目录，而 HTML 文件放在仓库根目录或其他文件夹中，也可能导致访问失败。最简单的做法是：普通仓库先选择main分支和/(root)目录，等熟悉之后再调整目录结构。
5. 什么时候用这个方法？
如果只是自己临时查看 HTML 文件，本地双击打开就够了。
如果要把 HTML 文件发给学生、合作者、读者或审稿人，建议发布成 GitHub Pages 链接。它比网盘链接更清晰，也更适合和代码仓库放在一起长期保存。
这个技巧的价值不在于「建一个网站」，而在于把本地生成的分析报告变成一个可以引用、可以分享、可以复查的网页。
简言之，GitHub 仓库放代码，GitHub Pages 负责把 HTML 文件展示成网页。把这两个链接区分清楚，很多复现材料和课程讲义的发布问题就解决了。
温馨提示：若页面不能正常显示数学公式和代码，请阅读原文获得更好的阅读体验。