Merge pull request #2033 from ADBond/fix-mkdocs-rendering

Fix mkdocs rendering symbols in notebook code

docs/hooks/__init__.py

@@ -4,8 +4,10 @@
 from pathlib import Path
 
 from mkdocs.config.defaults import MkDocsConfig
+from mkdocs.plugins import event_priority
 from mkdocs.structure.files import Files
 from mkdocs.structure.pages import Page
+from nbconvert import MarkdownExporter
 
 INCLUDE_MARKDOWN_REGEX = (
     # opening tag and any whitespace
@@ -73,7 +75,23 @@ def re_route_links(markdown: str, page_title: str) -> str | None:
     return re.sub(docs_folder_regex, "", markdown)
 
 
-def on_page_markdown_hook(
+# hooks for use by mkdocs
+
+# priority last - run this after any other such hooks
+# this ensures we are overwriting mknotebooks config,
+# not the other way round
+@event_priority(-100)
+def on_config(config: MkDocsConfig) -> MkDocsConfig:
+    # convert ipynb to md rather than html directly
+    # this ensures we render symbols such as '<' correctly
+    # in codeblocks, instead of '%lt;'
+    md_exporter = MarkdownExporter(config=config)
+    # overwrite mknotebooks config option
+    config["notebook_exporter"] = md_exporter
+    return config
+
+
+def on_page_markdown(
     markdown: str, page: Page, config: MkDocsConfig, files: Files
 ) -> str | None:
     """

mkdocs.yml

@@ -67,9 +67,8 @@ plugins:
       match_path: blog/posts/.*
       date_from_meta:
         as_creation: date
-  - mkdocs-simple-hooks:
-      hooks:
-        on_page_markdown: "docs.hooks:on_page_markdown_hook"
+hooks:
+  - docs/hooks/__init__.py
 
 markdown_extensions:
   - abbr

scripts/docs-requirements.txt

@@ -7,7 +7,6 @@ mkdocs-autorefs
 mkdocs-material-extensions
 mkdocs-mermaid2-plugin
 mkdocs-monorepo-plugin
-mkdocs-simple-hooks==0.1.5
 mkdocstrings
 mkdocstrings-python
 mkdocstrings-python-legacy