如何在GitHub Pages上的MkDocs（Material）生成网站中嵌入仓库内的PDF文件

首先得明确一个关键：GitHub Pages是把你仓库里的docs文件夹作为网站的根目录来部署的，所以所有文件的路径都要相对于docs来写，而不是仓库的根目录。之前方法失效就是因为路径指向了仓库根，而部署后的网站根本没有这个层级。

下面是针对你两种方法的修正方案，以及额外的优化选项：

方法1：嵌入PDF到页面内（修正版） #

把HTML代码里的路径改成相对于docs的相对路径或者网站根路径就行。比如你的PDF放在docs/files/report.pdf，那路径就写成/files/report.pdf（斜杠开头代表网站根，也就是docs的位置）：

<object data="/files/report.pdf" type="application/pdf" width="100%" height="600px">
  <!-- 备用内容：如果浏览器不支持嵌入，显示下载链接 -->
  <p>无法预览PDF，请<a href="/files/report.pdf">点击下载</a>查看。</p>
</object>

这里我加了宽高设置和备用内容，体验会更好——毕竟不是所有浏览器都支持直接嵌入PDF。

方法2：PDF下载/预览链接（修正版） #

同样调整路径，比如PDF在docs/assets/guide.pdf，代码改成：

<a href="/assets/guide.pdf" class="image fit" target="_blank">
  <i class="fas fa-file-pdf"></i> 查看指南PDF
</a>

加个target="_blank"可以让PDF在新标签页打开，用户体验更友好；补充文字说明也比单纯图标更清晰。

额外优化：用MkDocs Material的内置功能（更优雅） #

如果你不想写原生HTML，MkDocs Material其实支持直接用Markdown语法插入PDF预览。只要路径正确，直接写：

![PDF预览](/files/report.pdf)

这个会自动生成一个可点击的PDF预览图（需要浏览器支持），点击后可以查看完整文档。

验证路径的小技巧 #

部署前可以先本地运行mkdocs serve，然后在本地访问http://localhost:8000/files/report.pdf（对应你的PDF路径），如果能打开，说明路径是对的，部署到GitHub Pages后也肯定能正常工作。

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