处理非代码文件

渲染和比较图像

GitHub 可以显示多种常见图像格式，包括 PNG、JPG、GIF、PSD 和 SVG。除了仅仅显示这些图像之外，还有多种方式可以比较这些图像不同版本之间的差异。

查看图像

您可以直接在 GitHub 上浏览和查看仓库中的图像。

SVG 目前不支持内联脚本或动画。

查看差异

您可以使用三种不同模式直观地比较图像：并排、滑动和洋葱皮。

并排

并排是默认模式；它让您快速浏览两张图像。此外，如果图像在不同版本之间尺寸发生了变化，会显示实际的尺寸变化。这能够让您清晰地看到图像被重新调整大小的情况，例如资产升级到更高分辨率时。

滑动

滑动让您并列查看图像的不同部分。不确定不同版本之间颜色是否有变化？拖动滑动条到相关区域即可自行比较像素。

洋葱皮

洋葱皮在元素移动少量且难以察觉时特别有用。比如一个图标向左移动了两个像素？将不透明度滑块向后拖动一点，即可观察到变化。

3D 文件查看器

GitHub 可以托管并渲染 .stl 扩展名的 3D 文件。

在 GitHub 上直接查看 STL 文件时，您可以

• 点击并拖动以旋转模型。
• 右键点击并拖动以平移视图。
• 滚动以缩放。
• 点击不同的视图模式来切换视图。

解决性能慢的问题

如果您在查看器的角落看到在查看器的角落出现“WebGL powered hardware support not available”的提示，则说明您的浏览器不支持 WebGL 技术。

WebGL 对充分利用计算机硬件至关重要。我们建议您使用已启用 WebGL 的浏览器，例如 Chrome 或 Firefox。

错误：“无法显示”

如果您的模型无效，GitHub 可能无法显示该文件。此外，超过 10 MB 的文件也太大，GitHub 无法显示。

在其他位置嵌入模型

要在互联网上的其他地方显示您的 3D 文件，请修改此模板并将其放置在任何支持 JavaScript 的 HTML 页面上

<script src="https://embed.github.com/view/3d/<username>/<repo>/<ref>/<path_to_file>"></script>

例如，如果您的模型 URL 为 github.com/skalnik/secret-bear-clip/blob/master/stl/clip.stl，您的嵌入代码应为

<script src="https://embed.github.com/view/3d/skalnik/secret-bear-clip/master/stl/clip.stl"></script>

默认情况下，嵌入渲染器宽 420 像素、高 620 像素，但您可以通过在 URL 末尾添加 ?height=300&width=500 等参数来自定义高度和宽度。

在 Markdown 中渲染

您可以在 Markdown 中直接嵌入 ASCII STL 语法。了解更多信息，请参阅 创建图表。

渲染 CSV 和 TSV 数据

GitHub 支持以 .csv（逗号分隔）和 .tsv（制表符分隔）文件的形式渲染表格数据。

在查看时，任何提交到 GitHub 仓库的 .csv 或 .tsv 文件会自动渲染为交互式表格，带有标题行和行号。默认情况下，我们始终将第一行视为标题行。

您可以点击行号链接到特定行，或按住 Shift 键选择多行。只需复制 URL 并发送给朋友即可。

搜索数据

如果想在数据集中查找某个值，只需在文件上方的搜索栏中直接输入，行会自动过滤。

处理错误

有时，您可能会发现 CSV 或 TSV 文件未渲染。这种情况下，原始文本上方会出现一条消息，提示可能的错误原因。

常见错误包括

• 列数不匹配。每行必须拥有相同数量的分隔符，即使单元格为空也如此。
• 文件大小超出限制。我们的渲染仅支持最大 512 KB 的文件，超过该大小会拖慢浏览器。
• 使用了不受支持的分隔符，例如使用分号而非逗号。

渲染 PDF 文档

GitHub 支持渲染 PDF 文档。

目前，PDF 中的链接会被忽略。

在正文文档中渲染差异

包含正文文档的提交和 Pull Request 可以以源代码视图和渲染后视图展示这些文档。

源代码视图显示键入的原始文本，而渲染后视图展示这些文本在 GitHub 上渲染后的效果。例如，Markdown 中的 **bold** 与渲染后呈现的 bold 之间的区别。

正文渲染支持 github/markup 所支持的以下文档类型：

• Markdown
• AsciiDoc
• Textile
• ReStructuredText
• Rdoc
• Org
• Creole
• MediaWiki
• Pod

要查看提交中对文档所做的更改，请点击.

此“富差异”会高亮显示已添加和已删除的代码。

禁用 Markdown 渲染

在查看 Markdown 文件时，您可以点击文件顶部的 Code 来禁用 Markdown 渲染，改为查看文件的源代码。

禁用 Markdown 渲染后，您可以使用源代码视图的功能，例如行链接，这在查看渲染后的 Markdown 文件时是不可用的。

可视化属性更改

我们提供工具提示来描述属性的更改——这些更改不像文字那样在渲染文档中可见。例如，若链接 URL 从一个站点变为另一个站点，我们会显示类似以下的提示：“href: /octo-org-repo/blob/CONTRIBUTING -> /octo-org/octo-repo/blob/docs/CONTRIBUTING”。

对更改进行评论

提交评论只能在源代码视图中、逐行地添加到文件中。

链接到标题

与其他渲染后的正文文档类似，将鼠标悬停在文档标题上会出现链接图标。您可以将渲染后正文差异的读者链接到特定章节。

查看复杂差异

某些 Pull Request 涉及大量且复杂的文档更改。当分析这些更改所需时间过长时，GitHub 并不总能生成渲染视图。如果出现此情况，点击渲染按钮时会看到错误信息。

您仍然可以使用源代码视图来分析并评论更改。

查看 HTML 元素

我们并不直接支持对 HTML 文档提交的渲染视图。某些格式（如 Markdown）允许在文档中嵌入任意 HTML。当这些文档在 GitHub 上显示时，部分嵌入的 HTML 可以在预览中展示，而其他（例如嵌入的 YouTube 视频）则无法展示。

一般而言，包含嵌入式 HTML 的文档的渲染视图只会显示 GitHub 能够支持的元素的更改。含有嵌入式 HTML 的文档应始终在渲染视图和源代码视图中一起审阅，以保证完整性。

在 GitHub 上映射 GeoJSON/TopoJSON 文件

GitHub 支持在仓库中渲染 GeoJSON 与 TopoJSON 地图文件。可像平常一样提交后缀为 .geojson 或 .topojson 的文件。后缀为 .json 的文件同样受支持，但仅当其 type 被设置为 FeatureCollection、GeometryCollection 或 topology 时。随后，前往该 GeoJSON/TopoJSON 文件在 GitHub 上的路径即可查看。

几何类型

GitHub 上的地图使用 Leaflet.js，并支持 GeoJSON 规范 中列出的全部几何类型（Point、LineString、Polygon、MultiPoint、MultiLineString、MultiPolygon 与 GeometryCollection）。TopoJSON 文件应为 “Topology” 类型并遵循 TopoJSON 规范。

在其他位置嵌入您的地图

想在 GitHub 之外使用您的 GeoJSON 地图吗？只需修改此模板，并将其放置在任何支持 JavaScript 的 HTML 页面上（例如 GitHub Pages）。

<script src="https://embed.github.com/view/geojson/<username>/<repo>/<ref>/<path_to_file>"></script>

例如，如果您的地图 URL 为 github.com/benbalter/dc-wifi-social/blob/master/bars.geojson，您的嵌入代码应为

<script src="https://embed.github.com/view/geojson/benbalter/dc-wifi-social/master/bars.geojson"></script>

默认情况下，嵌入地图为 420 px × 620 px，但您可以在 URL 末尾添加 ?height=300&width=500 等参数来自定义高度和宽度。

在 Markdown 中映射

您可以在 Markdown 中直接嵌入 GeoJSON 与 TopoJSON。了解更多信息，请参阅 创建图表。

聚类

如果您的地图包含大量标记（约 750 条以上），GitHub 会在更高缩放级别自动对相邻标记进行聚类。只需点击聚类或放大即可查看单个标记。

底层地图出现问题

底层地图数据（街道名称、道路等）由 OpenStreetMap 提供，它是一个创建自由可编辑世界地图的协作项目。如果您发现地图有误，由于其开源，您只需注册并提交修正即可。

排查 GeoJSON/TopoJSON 文件问题

如果渲染 GeoJSON 文件时出现问题，请使用 GeoJSON 校验工具 检查文件是否有效。若点位未出现在预期位置（例如出现在海洋中央），可能是因为数据使用了当前不受支持的投影。GitHub 目前仅支持 urn:ogc:def:crs:OGC:1.3:CRS84 投影。

此外，如果您的 .geojson 文件特别大（超过 10 MB），浏览器无法渲染。此时通常会看到一条提示，说明我们无法显示如此大的文件。

仍可尝试通过将 .geojson 文件转换为 TopoJSON（一种在某些情况下可将文件大小压缩至原来的 20%）来渲染数据。当然，您也可以将文件拆分为更小的块（例如按州或年份），并在仓库中存放为多个文件。

关于 GeoJSON/TopoJSON 的进一步阅读

• Azure Maps 文档
• TopoJSON 维基

在 GitHub 上使用 Jupyter Notebook 文件

当您在 GitHub 中添加后缀为 .ipynb 的 Jupyter Notebook 或 IPython Notebook 文件时，它们会在仓库中渲染为静态 HTML 文件。

笔记本的交互式功能（如自定义 JavaScript 绘图）在 GitHub 仓库中无法工作。示例请参阅 Linking and Interactions.ipynb。

若要在 GitHub 之外查看带有 JavaScript 内容渲染的 Jupyter Notebook，或与他人共享 Notebook 文件，可使用 nbviewer。示例请参阅在 nbviewer 上渲染的 Linking and Interactions.ipynb。

若想查看 Jupyter Notebook 的完整交互版，可在本地搭建 Notebook 服务器。更多信息请参阅 Jupyter 官方文档。

排查 Jupyter Notebook 文件问题

如果在将 Jupyter Notebook 文件渲染为静态 HTML 时遇到问题，您可以在命令行本地使用 nbconvert 命令进行转换。

jupyter nbconvert --to html NOTEBOOK-NAME.ipynb

关于 Jupyter Notebook 的进一步阅读

• Jupyter Notebook 的 GitHub 仓库
• Jupyter Notebook 画廊

在 GitHub 上显示 Mermaid 文件

GitHub 支持在仓库中渲染 Mermaid 文件。请像平常一样提交后缀为 .mermaid 或 .mmd 的文件。随后，前往该 Mermaid 文件在 GitHub 上的路径即可查看。

例如，如果您在仓库中添加了如下内容的 .mmd 文件

graph TD
    A[Friend's Birthday] -->|Get money| B(Go shopping)
    B --> C{Let me think}
    C -->|One| D["Cool <br> Laptop"]
    C -->|Two| E[iPhone]
    C -->|Three| F[fa:fa-car Car]

当您在仓库中查看该文件时，它将被渲染为流程图。

排查 Mermaid 文件问题

如果图表完全不渲染，请使用 Mermaid 在线编辑器检查图表是否包含有效的 Mermaid Markdown 语法。

如果图表能够显示但效果不符预期，您可以创建新的 GitHub 社区讨论并添加 Mermaid 标签。

已知问题

• 序列图通常在图表下方额外留有填充，且图表越大填充越多。这是 Mermaid 库已知的问题。
• 在序列图中，带弹出菜单的角色节点无法正常工作。这是因为在使用 Mermaid 库的 API 渲染图表时，JavaScript 事件的添加方式出现了不一致。
• 并非所有图表都符合可访问性（a11y）标准，这可能会影响依赖屏幕阅读器的用户。

在 Markdown 中使用 Mermaid

您可以在 Markdown 中直接嵌入 Mermaid 语法。了解更多请参阅 创建图表。

关于 Mermaid 的进一步阅读

• Mermaid.js 文档
• Mermaid.js 在线编辑器