简介

什么是 Jupyter Book？

Jupyter Book 是一个开源工具，专为组织和展示 Jupyter Notebook 内容设计。它可以将 .ipynb 文件、Markdown 文档、以及其他格式的内容整合为一个美观、交互性强的文档站点。无论是数据科学项目、教学材料，还是技术文档，Jupyter Book 都能以网页的形式呈现，让内容更加易于分享和访问。

Jupyter Book 的功能与优势

1. 支持多种内容格式

   • 可以直接展示 Jupyter Notebook，支持代码块和交互式输出。
   • 兼容 Markdown 和 reStructuredText，便于撰写说明性文档。
   • 支持嵌入图片、图表、音频等多媒体内容。

2. 可交互性

   • 配合 Binder 或 Thebe，用户可以直接在浏览器中运行代码。
   • 动态展示代码结果，为读者提供深度学习和实践的机会。

3. 自动化和美观

   • 自动生成目录、索引和导航结构。
   • 提供现代化的主题设计，支持响应式布局，在不同设备上均有良好体验。

4. 轻松部署与共享

   • 与 GitHub Pages、Netlify 等静态网站托管平台无缝集成。
   • 易于维护和更新，适合持续迭代的项目。

搭建

创建一个新的Github仓库

安装 Jupyter Book

确保你已经安装了 Python（推荐使用虚拟环境）。然后运行以下命令安装 Jupyter Book：

pip install jupyter-book

初始化 Jupyter Book 项目

将项目克隆到本地后，进入项目的根目录

jupyter-book create my-jupyter-book

这会自动生成一个初始结构。

配置

配置 _config.yml

# Book settings
# Learn more at https://jupyterbook.org/customize/config.html

title: Arno's Projects Collection
author: Arno Zeng
logo: img/Arno.jpg

# Force re-execution of notebooks on each build.
# See https://jupyterbook.org/content/execute.html
execute:
  execute_notebooks: off  # ("auto", "force", "cache", "off")

# Define the name of the latex output file for PDF builds
latex:
  latex_documents:
    targetname: book.tex

# Add a bibtex file so that we can create citations
bibtex_bibfiles:
  - references.bib

# Information about where the book exists on the web
repository:
  url: https://github.com/arnozeng98/data-science-archive  # Online location
  branch: gh-pages

# Add GitHub buttons to your book
# https://jupyterbook.org/customize/config.html#add-a-link-to-your-repository
html:
  favicon: img/favicon.ico
  navbar_footer_text: "Copyright © 2025"
  use_issues_button: true
  use_repository_button: true

配置目录文件 _toc.yml

# 目录结构
format: jb-book
root: archive/intro       # 起始页面
chapters:
- file: archive/project1  # 项目 1 的 Notebook
- file: archive/project2  # 项目 2 的 Notebook

构建文档站

jupyter-book build .

成功后，你会在 _build/html/ 文件夹中看到生成的 HTML 文件。

部署 Github Pages

在 GitHub 上，创建一个新的分支名为gh-pages。启用 gh-pages 分支为 Pages 的发布源：

• 打开仓库的 Settings > Pages。
• 设置 Branch 为 gh-pages。

安装ghp-import：

pip install ghp-import

在本地的main分支下运行：

ghp-import -n -p -f _build/html

然后就可以通过 https://your-username.github.io/my-jupyter-book 访问站点。