9 如何在 Quarto 中优雅地展示 `.ipynb` 文件？

ChatGPT 对话

在撰写 Quarto 教学材料或公开笔记时，我们经常会附上 Jupyter Notebook 文件（.ipynb）供读者参考。然而，直接使用相对路径链接往往导致显示异常，影响阅读体验。

9.1 问题：原始 `.ipynb` 显示效果很糟

最常见的做法是使用如下相对路径：

[点击查看原始 .ipynb 文件](../examples/sample_notebook_python.ipynb)

链接虽然有效，但 Quarto 渲染后，读者点击跳转的是 .ipynb 文件的原始 JSON 内容，页面混乱难读：

{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "7c5e1f3e",
   "source": ["## 标题", "第一段说明"]
  },
  ...

这并不是一个理想的展示方式。

GitHub 提供了对 .ipynb 文件的原生支持，能将其渲染为结构化、可阅读、可复制的 notebook 页面，非常适合教学阅读与代码学习。推荐链接格式如下：

[点击查看 notebook](https://github.com/lianxhcn/research_with_AI/blob/main/examples/sample_notebook_python.ipynb)

读者点击后会看到类似 Jupyter Lab 的网页视图，代码、Markdown 和输出完整呈现，体验良好。

缺点是默认字体不是等宽字体，导致代码的排版，尤其是对齐效果不佳。

如果你希望 notebook 的展示界面更加简洁、无干扰，可以使用 nbviewer.org 提供的免费服务。只需将 GitHub 上的 .ipynb 链接粘贴进去，即可获得更清爽的预览链接：

[在线预览 notebook](https://nbviewer.org/github/lianxhcn/research_with_AI/blob/main/examples/sample_notebook_python.ipynb)

nbviewer 的亮点 包括：

适用于希望发布静态网站、课程材料或展示成果时提供「无 GitHub 视觉干扰」的 notebook 预览。

下图对比了 GitHub 渲染和 nbviewer 预览的差异：

此外，nbviewer 还支持多种其他功能，如：

若你希望读者能下载 notebook 文件进行本地运行，则可以保留相对路径链接，但务必提示读者「右键另存为」，防止误点后进入 JSON 混乱页面。如下写法更稳妥：

[下载原始 .ipynb 文件](../examples/sample_notebook_python.ipynb) ←（右键另存为）

并配合一个提示框：

::: {.callout-warning title="注意"}

此链接指向的是 `.ipynb` 原始文件（JSON 格式），直接点击可能乱码。   

建议：右键另存为以下载文件。

:::

使用目的	推荐链接方式	示例格式
在线阅读	GitHub 渲染视图	`github.com/.../xxx.ipynb`
清爽展示	nbviewer 在线预览	`nbviewer.org/github/.../xxx.ipynb`
下载使用	相对路径 + 提示说明	`../examples/xxx.ipynb`