Add a toc for html and latex exporter

CHANGELOG.md

@@ -1634,6 +1634,7 @@ raw template
 {%- endblock in_prompt -%}
     """
 
+
 exporter_attr = AttrExporter()
 output_attr, _ = exporter_attr.from_notebook_node(nb)
 assert "raw template" in output_attr

Untitled.ipynb

@@ -0,0 +1,57 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "id": "e1ecc100-fae0-422f-bcf6-73fbb2bdd215",
+   "metadata": {},
+   "source": [
+    "#test"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "23c99cdf-7405-4c4f-889e-2ce72db47d23",
+   "metadata": {},
+   "source": [
+    "##test1"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "422906ca-be89-4a2a-823f-e498ea193767",
+   "metadata": {},
+   "source": [
+    "##test2"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "ac26a764-016b-4a8d-82b0-b34f2961c36a",
+   "metadata": {},
+   "source": [
+    "##test3"
+   ]
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "Python 3 (ipykernel)",
+   "language": "python",
+   "name": "python3"
+  },
+  "language_info": {
+   "codemirror_mode": {
+    "name": "ipython",
+    "version": 3
+   },
+   "file_extension": ".py",
+   "mimetype": "text/x-python",
+   "name": "python",
+   "nbconvert_exporter": "python",
+   "pygments_lexer": "ipython3",
+   "version": "3.13.1"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 5
+}

nbconvert/exporters/html.py

@@ -27,7 +27,11 @@
 from nbformat import NotebookNode
 
 from nbconvert.filters.highlight import Highlight2HTML
-from nbconvert.filters.markdown_mistune import IPythonRenderer, MarkdownWithMath
+from nbconvert.filters.markdown_mistune import (
+    IPythonRenderer,
+    MarkdownWithMath,
+    extract_titles_from_notebook_node,
+)
 from nbconvert.filters.widgetsdatatypefilter import WidgetsDataTypeFilter
 from nbconvert.utils.iso639_1 import iso639_1
 
@@ -355,6 +359,7 @@ def resources_include_url(name):
             return markupsafe.Markup(src)
 
         resources = super()._init_resources(resources)
+
         resources["theme"] = self.theme
         resources["include_css"] = resources_include_css
         resources["include_lab_theme"] = resources_include_lab_theme
@@ -370,4 +375,5 @@ def resources_include_url(name):
         resources["should_sanitize_html"] = self.sanitize_html
         resources["language_code"] = self.language_code
         resources["should_not_encode_svg"] = self.skip_svg_encoding
+        resources["extract_titles_from_nodebook_node"] = extract_titles_from_notebook_node
         return resources

nbconvert/exporters/templateexporter.py

@@ -207,6 +207,9 @@ def default_config(self):
     enable_async = Bool(False, help="Enable Jinja async template execution").tag(
         affects_environment=True
     )
+    include_tableofcontents = Bool(
+        False, allow_none=True, help="Enable to include a table of contents"
+    ).tag(config=True, affects_template=True)
 
     _last_template_file = ""
     _raw_template_key = "<memory>"
@@ -684,4 +687,5 @@ def get_prefix_root_dirs(self):
     def _init_resources(self, resources):
         resources = super()._init_resources(resources)
         resources["deprecated"] = deprecated
+        resources["include_tableofcontents"] = self.include_tableofcontents
         return resources

nbconvert/filters/markdown_mistune.py

@@ -12,6 +12,8 @@
 from typing import TYPE_CHECKING, Any, ClassVar, Dict, Iterable, Match, Optional, Protocol, Tuple
 
 import bs4
+import mistune
+from mistune.renderers.markdown import MarkdownRenderer
 from pygments import highlight
 from pygments.formatters import HtmlFormatter
 from pygments.lexer import Lexer
@@ -504,3 +506,39 @@ def render(self, source: str) -> str:
 def markdown2html_mistune(source: str) -> str:
     """Convert a markdown string to HTML using mistune"""
     return MarkdownWithMath(renderer=IPythonRenderer(escape=False)).render(source)
+
+
+class HeadingExtractor(MarkdownRenderer):
+    """A renderer to capture headings"""
+
+    def __init__(self):
+        """Initialize the class."""
+        super().__init__()
+        self.headings = []
+
+    def heading(self, text, level):
+        """Return an empty string for the headings to avoid outputting them."""
+        self.headings.append((level, text))
+        return ""
+
+
+def extract_titles_from_markdown_input(markdown_input):
+    """Create a Markdown parser with the HeadingExtractor renderer to collect all the headings of a notebook"""
+    """ The input argument is markdown_input that is a single string with all the markdown content concatenated """
+    """ The output is an array containing information about the headings such as their level, their text content, an identifier and a href that can be used in case of html converter.s"""
+    titles_array = []
+    renderer = HeadingExtractor()
+    extract_titles = mistune.create_markdown(renderer=renderer)
+    extract_titles(markdown_input)
+    headings = renderer.headings
+
+    """ Iterate on all headings to get the necessary information on the various titles """
+    for __, title in headings:
+        children = title["children"]
+        attrs = title["attrs"]
+        raw_text = children[0]["raw"]
+        header_level = attrs["level"]
+        id = raw_text.replace(" ", "-")
+        href = "#" + id
+        titles_array.append([header_level, raw_text, id, href])
+    return titles_array

nbconvert/nbconvertapp.py

@@ -186,6 +186,10 @@ def validate(self, obj, value):
             },
             """Whether the HTML in Markdown cells and cell outputs should be sanitized..""",
         ),
+        "toc": (
+            {"TemplateExporter": {"include_tableofcontents": True}},
+            "Generate a table of contents in the output (only compatible with HTML and Latex exporters)",
+        ),
     }
 )
 
@@ -675,5 +679,6 @@ def _default_export_format(self):
 # Main entry point
 # -----------------------------------------------------------------------------
 
+
 main = launch_new_instance = NbConvertApp.launch_instance
 dejavu_main = DejavuApp.launch_instance

share/templates/lab/base.html.j2

@@ -2,6 +2,7 @@
 {% from 'celltags.j2' import celltags %}
 {% from 'cell_id_anchor.j2' import cell_id_anchor %}
 
+
 {% block codecell %}
 {%- if not cell.outputs -%}
 {%- set no_output_class="jp-mod-noOutputs" -%}

share/templates/lab/index.html.j2

@@ -100,6 +100,56 @@ a.anchor-link {
     display: block;
   }
 }
+/* Table of Contents for the html exporter */
+.jp-RenderedHTMLTOC-Title {
+  font-family: var(--jp-content-font-family);
+  font-size: 14px;
+  margin: 16px 0;
+  padding-left: 64px;
+  font-weight: bold;
+}
+
+.jp-RenderedHTMLTOC-Item-h1 {
+  font-family: var(--jp-content-font-family);
+  font-size: 14px;
+  margin: 0;
+  padding-left: 88px;
+}
+
+.jp-RenderedHTMLTOC-Item-h2 {
+  font-family: var(--jp-content-font-family);
+  font-size: 12px;
+  margin: 4px;
+  padding-left: 112px;
+}
+
+.jp-RenderedHTMLTOC-Item-h3 {
+  font-family: var(--jp-content-font-family);
+  font-size:10px;
+  margin: 4px;
+  padding-left: 136px;
+}
+
+.jp-RenderedHTMLTOC-Item-h4 {
+  font-family: var(--jp-content-font-family);
+  font-size: 8px;
+  margin: 4px;
+  padding-left: 160px;
+}
+
+.jp-RenderedHTMLTOC-Item-h5 {
+  font-family: var(--jp-content-font-family);
+  font-size: 7px;
+  margin: 4px;
+  padding-left: 184px;
+}
+
+.jp-RenderedHTMLTOC-Item-h6 {
+  font-family: var(--jp-content-font-family);
+  font-size: 6px;
+  margin: 2px;
+  padding-left: 208px;
+}
 </style>
 
 {% endblock notebook_css %}
@@ -126,6 +176,34 @@ a.anchor-link {
 <body class="jp-Notebook" data-jp-theme-light="true" data-jp-theme-name="JupyterLab Light">
 {% endif %}
 <main>
+{%- block tableofcontents -%}
+{%- if resources.include_tableofcontents -%}
+{%- set tableofcontents= resources.extract_titles_from_nodebook_node(nb) -%}
+<div class="jp-RenderedHTMLTOC-Title">Table of contents</div>
+{%- for item in tableofcontents -%}
+{%- set (header, level, href) = item -%}
+<div class="
+{%- if level==1 -%}
+jp-RenderedHTMLCommon jp-RenderedHTMLTOC-Item-h1
+{%- elif level==2 -%}
+jp-RenderedHTMLCommon jp-RenderedHTMLTOC-Item-h2
+{%- elif level==3 -%}
+jp-RenderedHTMLCommon jp-RenderedHTMLTOC-Item-h3
+{%- elif level==4 -%}
+jp-RenderedHTMLCommon jp-RenderedHTMLTOC-Item-h4
+{%- elif level==5 -%}
+jp-RenderedHTMLCommon jp-RenderedHTMLTOC-Item-h5
+{%- elif level==6 -%}
+jp-RenderedHTMLCommon jp-RenderedHTMLTOC-Item-h6
+{%- endif -%}"
+>
+<a href={{href}}>
+{{header | safe}}
+</a>
+</div>
+{%- endfor -%}
+{%- endif -%}
+{% endblock tableofcontents %}
 {%- endblock body_header -%}
 
 {% block body_footer %}

share/templates/latex/base.tex.j2

@@ -232,11 +232,17 @@ override this.-=))
 ((* endblock header *))
 
 ((* block body *))
+
 \begin{document}
     ((* block predoc *))
     ((* block maketitle *))\maketitle((* endblock maketitle *))
     ((* block abstract *))((* endblock abstract *))
     ((* endblock predoc *))
+    ((* block tableofcontents *))
+      ((* if resources.include_tableofcontents *))
+        \tableofcontents
+      ((* endif *))
+    ((* endblock tableofcontents *))
 
     ((( super() )))