Add a toc for html and latex exporter

nbconvert/exporters/html.py

@@ -26,7 +26,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_markdown_input,
+)
 from nbconvert.filters.widgetsdatatypefilter import WidgetsDataTypeFilter
 from nbconvert.utils.iso639_1 import iso639_1
 
@@ -256,8 +260,17 @@ def from_notebook_node(  # type:ignore[explicit-override, override]
         highlight_code = self.filters.get(
             "highlight_code", Highlight2HTML(pygments_lexer=lexer, parent=self)
         )
+        markdown_collection = ""
+        for cell in nb.cells:
+            if cell.cell_type == "markdown":
+                markdown_collection = markdown_collection + cell.source + "\n"
 
         resources = self._init_resources(resources)
+        if resources is None:
+            resources = {}
+        resources.update(
+            {"tableofcontents": extract_titles_from_markdown_input(markdown_collection)}
+        )
 
         filter_data_type = WidgetsDataTypeFilter(
             notebook_metadata=self._nb_metadata, parent=self, resources=resources

nbconvert/exporters/templateexporter.py

@@ -203,6 +203,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>"
@@ -680,4 +683,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 Any, Callable, Dict, Iterable, Match, Optional, 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
@@ -487,3 +489,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,9 @@
 {% from 'celltags.j2' import celltags %}
 {% from 'cell_id_anchor.j2' import cell_id_anchor %}
 
+{%- block body_header -%}
+{%- endblock body_header -%}
+
 {% 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: 24px;
+  margin: 16px 0;
+  padding-left: 64px;
+  font-weight: bold;
+}
+
+.jp-RenderedHTMLTOC-Item-h1 {
+  font-family: var(--jp-content-font-family);
+  font-size: 20px;
+  margin: 0;
+  padding-left: 88px;
+}
+
+.jp-RenderedHTMLTOC-Item-h2 {
+  font-family: var(--jp-content-font-family);
+  font-size: 18px;
+  margin: 4px;
+  padding-left: 112px;
+}
+
+.jp-RenderedHTMLTOC-Item-h3 {
+  font-family: var(--jp-content-font-family);
+  font-size:16px;
+  margin: 4px;
+  padding-left: 136px;
+}
+
+.jp-RenderedHTMLTOC-Item-h4 {
+  font-family: var(--jp-content-font-family);
+  font-size: 14px;
+  margin: 4px;
+  padding-left: 160px;
+}
+
+.jp-RenderedHTMLTOC-Item-h5 {
+  font-family: var(--jp-content-font-family);
+  font-size: 12px;
+  margin: 4px;
+  padding-left: 184px;
+}
+
+.jp-RenderedHTMLTOC-Item-h6 {
+  font-family: var(--jp-content-font-family);
+  font-size: 10px;
+  margin: 2px;
+  padding-left: 208px;
+}
 </style>
 
 {% endblock notebook_css %}
@@ -126,6 +176,56 @@ 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 -%}
+<div class="jp-RenderedHTMLTOC-Title">Table of contents</div>
+{%- for item in resources.tableofcontents -%}
+{%- set (level, text, id, href) = item -%}
+{%- if level==1 -%}
+<div class="jp-RenderedHTMLCommon jp-RenderedHTMLTOC-Item-h1">
+<a href={{href}}>
+{{text}}
+</a>
+</div>
+{%- endif -%}
+{%- if level==2 -%}
+<div class="jp-RenderedHTMLCommon jp-RenderedHTMLTOC-Item-h2">
+<a href={{href}}>
+{{text}}
+</a>
+</div>
+{%- endif -%}
+{%- if level==3 -%}
+<div class="jp-RenderedHTMLCommon jp-RenderedHTMLTOC-Item-h3">
+<a href={{href}}>
+{{text}}
+</a>
+</div>
+{%- endif -%}
+{%- if level==4 -%}
+<div class="jp-RenderedHTMLCommon jp-RenderedHTMLTOC-Item-h4">
+<a href={{href}}>
+{{text}}
+</a>
+</div>
+{%- endif -%}
+{%- if level==5 -%}
+<div class="jp-RenderedHTMLCommon jp-RenderedHTMLTOC-Item-h5">
+<a href={{href}}>
+{{text}}
+</a>
+</div>
+{%- endif -%}
+{%- if level==6 -%}
+<div class="jp-RenderedHTMLCommon jp-RenderedHTMLTOC-Item-h6">
+<a href={{href}}>
+{{text}}
+</a>
+</div>
+{%- endif -%}
+{%- endfor -%}
+{%- endif -%}
+{% endblock tableofcontents %}
 {%- endblock body_header -%}
 
 {% block body_footer %}

share/templates/latex/base.tex.j2

@@ -213,11 +213,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() )))