如何将目录添加到 Jupyter / JupyterLab 笔记本？

Question

http://ipython.org/ipython-doc/stable/interactive/notebook.html 的文档说

您可以使用不同级别的标题为整个计算文档提供概念结构；共有 6 个级别，从 1 级（顶层）到 6 级（段落）。这些可以在以后用于构建目录等。

但是，我在任何地方都找不到有关如何使用分层标题来创建此类目录的说明。有没有办法做到这一点？

注意：如果有的话，我也会对使用 ipython 笔记本标题的其他类型的导航感兴趣。例如，从一个标题到另一个标题来回跳转以快速找到每个部分的开头，或者隐藏（折叠）整个部分的内容。这是我的愿望清单——但任何类型的导航都会引起人们的兴趣。谢谢！

Answer 1

您可以使用 Markdown 和 HTML 手动添加目录。以下是我添加的方式：

在 Jupyter Notebook 顶部创建 TOC：

## TOC:
* [First Bullet Header](#first-bullet)
* [Second Bullet Header](#second-bullet)

在整个正文中添加 html 锚点：

## First Bullet Header <a class="anchor" id="first-bullet"></a>

code blocks...

## Second Bullet Header <a class="anchor" id="second-bullet"></a>

code blocks...

这可能不是最好的方法，但它确实有效。希望这会有所帮助。

Answer 2

有一个ipython nbextension 为笔记本构建目录。它似乎只提供导航，不提供部分折叠。

Answer 3

JupyterLab ToC 说明

这个问题已经有很多很好的答案了， 但它们通常需要调整才能与 JupyterLab 中的笔记本正常工作。 我写了这个答案来详细说明包含 ToC 的可能方式 在 JupyterLab 中工作和导出时在笔记本中。

作为侧面板

jupyterlab-toc 扩展将 ToC 添加为侧面板 它可以对标题进行编号、折叠部分并用于导航（参见下面的 gif 以获取演示）。自 JupyterLab 3.0 起默认包含此扩展，在旧版本中您可以使用以下命令安装它

jupyter labextension install @jupyterlab/toc

---

在笔记本中作为一个单元格

目前， 这可以像马特丹乔的回答那样手动完成， 或自动通过toc2 jupyter notebook extension 在经典笔记本界面中。

首先， 将 toc2 作为jupyter_contrib_nbextensions bundle 的一部分安装：

conda install -c conda-forge jupyter_contrib_nbextensions

那么， 启动 JupyterLab， 去Help --> Launch Classic Notebook, 并打开要在其中添加 ToC 的笔记本。 单击工具栏中的 toc2 符号 调出浮动 ToC 窗口 （如果找不到，请参阅下面的 gif）， 单击齿轮图标并选中复选框 “添加笔记本 ToC 单元”。 保存笔记本，ToC 单元将在那里 当你在 JupyterLab 中打开它时。 插入的单元格是一个带有 html 的 markdown 单元格， 它不会自动更新。

toc2 的默认选项 可以在“Nbextensions”选项卡中配置 在经典笔记本启动页面中。 你可以例如选择给标题编号 并将 ToC 锚定为侧栏 （我个人认为看起来更干净）。

---

在导出的 HTML 文件中

nbconvert 可用于将笔记本导出为 HTML 遵循如何格式化导出的 HTML 的规则。 上面提到的toc2 扩展添加了一个名为html_toc 的导出格式， 可以在命令行中直接与nbconvert 一起使用 （在安装了toc2 扩展之后）：

jupyter nbconvert file.ipynb --to html_toc
# Append `--ExtractOutputPreprocessor.enabled=False`
# to get a single html file instead of a separate directory for images

请记住，shell 命令可以添加到笔记本单元格中 通过在它们前面加上感叹号!， 所以你可以把这条线贴在笔记本的最后一个单元格中 并始终生成一个带有 ToC 的 HTML 文件 当您点击“运行所有单元格”时 （或您希望从nbconvert 获得的任何输出）。 这边走， 您可以在工作时使用jupyterlab-toc 在笔记本中导航， 并且仍然在导出的输出中获得 ToC 无需求助于使用经典的笔记本界面 （对于我们中间的纯粹主义者）。

注意配置默认的 toc2 选项 如上所述， 不会更改nbconver --to html_toc 的格式。 需要在经典笔记本界面打开笔记本 将元数据写入 .ipynb 文件 （nbconvert 在导出时读取元数据） 或者， 您可以手动添加元数据 通过 JupyterLab 侧边栏的笔记本工具选项卡， 例如类似：

    "toc": {
        "number_sections": false,
        "sideBar": true
    }

如果您更喜欢 GUI 驱动的方法， 你应该可以打开经典笔记本 然后点击File --> Save as HTML (with ToC) （但请注意，我无法使用此菜单项）。

---

上面的 gif 文件链接自扩展的相应文档。

Answer 4

这里还有一个没有太多 JS 麻烦的选项：https://github.com/kmahelona/ipython_notebook_goodies

Answer 5

如何使用浏览器插件为您提供任何 html 页面的概览。我尝试了以下方法：

• HTML 5 Outliner Chrome
• Headings Map 用于火狐

它们都适用于 IPython Notebooks。我不愿意使用以前的解决方案，因为它们看起来有点不稳定，最终使用了这些扩展。

Answer 6

我最近为 Jupyter 创建了一个名为 jupyter-navbar 的小扩展。它搜索在降价单元格中编写的标题，并以分层方式在侧栏中显示指向它们的链接。侧边栏可调整大小且可折叠。请看下面的截图。

它易于安装，并利用了在打开笔记本时执行的“自定义”JS 和 CSS 代码，因此您无需手动运行它。

Answer 7

现在有两个包可用于处理 Jupyter 扩展：

1. jupyter_contrib_nbextensions 安装扩展，包括目录；

2. jupyter_nbextensions_configurator 提供图形用户界面，用于配置启用哪些 nbextensions（为每个笔记本自动加载），并提供用于配置 nbextensions 选项的控件。

更新：

从最新版本的jupyter_contrib_nbextensions 开始，至少对于conda，您不需要安装jupyter_nbextensions_configurator，因为它与这些扩展一起安装。

Answer 8

nbextensions ToC 说明

简介

正如@Ian 和@Sergey 所提到的，nbextensions 是一个简单的解决方案。为了详细说明他们的答案，这里提供了更多信息。

什么是 nbextensions？

nbextensions 包含一个扩展集合 为您的 Jupyter notebook 添加功能。

例如，仅举几个扩展名：

• 目录

• 可折叠的标题

安装 nbextensions

可以通过 Conda 或 PIP 进行安装

# If conda:
conda install -c conda-forge jupyter_contrib_nbextensions
# or with pip:
pip install jupyter_contrib_nbextensions

您将在 jupyter notebook 菜单中看到新标签 Nbextensions。取消选中顶部disable configuration for nbextensions without explicit compatibility (they may break your notebook environment, but can be useful to show for nbextension development) 的复选框，然后选中Table of Contents(2)。就这些。截图：

复制js和css文件

要将 nbextensions 的 javascript 和 css 文件复制到 jupyter 服务器的搜索目录中，请执行以下操作：

jupyter contrib nbextension install --user

切换扩展

注意，如果你不熟悉终端，最好安装 nbextensions 配置器（见下一节）

您可以启用/禁用您选择的扩展。正如文档所述，通用命令是：

jupyter nbextension enable <nbextension require path>

具体来说，要启用 ToC（目录）扩展，请执行以下操作：

jupyter nbextension enable toc2/main

安装配置界面（可选但有用）

正如其文档所述，nbextensions_configurator 为 nbextensions 提供配置接口。

如下所示：

如果你使用 conda 来安装它：

conda install -c conda-forge jupyter_nbextensions_configurator

如果您没有 Conda 或不想通过 Conda 安装，请执行以下 2 个步骤：

pip install jupyter_nbextensions_configurator
jupyter nbextensions_configurator enable --user

Answer 9

这是我的方法，虽然很笨重，但在 github 中可用：

放入第一个笔记本单元格，即导入单元格：

from IPythonTOC import IPythonTOC

toc = IPythonTOC()

在导入单元之后的某处，放入 genTOCEntry 单元，但不要运行它：

''' if you called toc.genTOCMarkdownCell before running this cell, 
the title has been set in the class '''

print toc.genTOCEntry()

在 genTOCEntry 单元格下方，将 TOC 单元格作为降价单元格：

<a id='TOC'></a>

#TOC

随着 notebook 的开发，在开始新部分之前放置这个 genTOCMarkdownCell：

with open('TOCMarkdownCell.txt', 'w') as outfile:

    outfile.write(toc.genTOCMarkdownCell('Introduction'))

!cat TOCMarkdownCell.txt

!rm TOCMarkdownCell.txt

将 genTOCMarkdownCell 向下移动到笔记本中要开始新部分的位置，并将 genTOCMarkdownCell 的参数设置为新部分的字符串标题，然后运行它。在它之后添加一个降价单元格，并将 genTOCMarkdownCell 的输出复制到开始新部分的降价单元格中。然后转到笔记本顶部附近的 genTOCEntry 单元格并运行它。例如，如果您如上所示为 genTOCMarkdownCell 设置参数并运行它，您将得到此输出 粘贴到新索引部分的第一个降价单元格中：

<a id='Introduction'></a>

###Introduction

然后，当您转到笔记本顶部并运行 genTocEntry 时，您会得到输出：

[Introduction](#Introduction)

复制此链接字符串并将其粘贴到目录标记单元格中，如下所示：

<a id='TOC'></a>

#TOC

[Introduction](#Introduction)

在您编辑 TOC 单元格以插入链接字符串然后按 shift-enter 后，指向新部分的链接将作为 Web 链接出现在您的笔记本目录中，单击它将浏览器定位到您的新部分部分。

我经常忘记的一件事是单击目录中的一行会使浏览器跳转到该单元格但不会选择它。当我们单击 TOC 链接时，任何处于活动状态的单元格仍然处于活动状态，因此向下或向上箭头或 shift-enter 指的是仍然处于活动状态的单元格，而不是我们通过单击 TOC 链接获得的单元格。

Answer 10

简单的markdown解决方案

您可以使用markdown超链接跳转到markdown标头，而无需定义html标签。无论您的标题中有多少个哈希#，都使用一个作为超链接。标题中的任何空格都将替换为连字符 -。

创建目录

# Contents
- [Section 1](#Section-1)
- [Section 2](#Section-2)
- [Section 3](#Section-3)

创建标题

# Section 1

## Section 2

您还可以将超链接添加回内容。

### Section 3
[top](#Contents)

这类似于 Matt Dancho 的 answer，但我总是觉得 html 锚点很繁琐。

Answer 11

正如 Ian 已经指出的，minrk 为 IPython Notebook 提供了一个目录扩展。我在让它工作时遇到了一些麻烦，并制作了这个IPython Notebook，它可以半自动地在 Windows 中为 minrk 的目录扩展生成文件。它不使用“curl”命令或链接，而是将 *.js 和 *.css 文件直接写入您的 IPython Notebook-profile-directory。

笔记本中有一个名为 '你需要做什么' 的部分 - 遵循它并有一个漂亮的浮动目录：)

这是一个已经显示的 html 版本： http://htmlpreview.github.io/?https://github.com/ahambi/140824-TOC/blob/master/A%20floating%20table%20of%20contents.htm