From 58453f5c70fed35e0053db336bb56dfe7934ac0e Mon Sep 17 00:00:00 2001
From: parashardhapola <parashar.dhapola@gmail.com>
Date: Mon, 26 Oct 2026 20:07:51 +0100
Subject: [PATCH] Smooth documentation navigation and move Nygen link to footer

---
 THIRD_PARTY_NOTICES.md |  9 +++++
 docs/build_docs.py     | 87 +++++++++++++++++++++++++++++++++++++++++-
 docs/source/myst.yml   |  2 +-
 3 files changed, 95 insertions(+), 3 deletions(-)
 create mode 100644 THIRD_PARTY_NOTICES.md

diff --git a/THIRD_PARTY_NOTICES.md b/THIRD_PARTY_NOTICES.md
new file mode 100644
index 0000000..cf916e9
--- /dev/null
+++ b/THIRD_PARTY_NOTICES.md
@@ -0,0 +1,9 @@
+# Third party notices
+
+## MyST Book Theme
+
+- Source: <https://github.com/jupyter-book/myst-theme>
+- Copyright (c) 2023 Executable Books.
+- License: MIT
+- Used in: `docs/build_docs.py` adjusts the documentation theme so navigation sections
+  are expanded in the initial page and remain expanded when browser code starts.
diff --git a/docs/build_docs.py b/docs/build_docs.py
index cb5198d..a846551 100644
--- a/docs/build_docs.py
+++ b/docs/build_docs.py
@@ -393,6 +393,26 @@ def write_discovery_files(
         )
         if route.endswith("/"):
             script_url = "https://docs.nygen.io/assets/brand/docs.js"
+            links += (
+                '<link rel="preload" as="font" '
+                'href="https://docs.nygen.io/assets/brand/fonts/inter/latin.woff2" '
+                'type="font/woff2" crossorigin/>'
+            )
+            links += """<script>
+(() => {
+  const observer = new MutationObserver(() => {
+    if (!document.querySelector('main')) return;
+    observer.disconnect();
+    const sidebar = document.querySelector('.myst-primary-sidebar-nav');
+    const home = document.querySelector('.myst-home-link');
+    if (sidebar?.clientHeight && home) {
+      const saved = sessionStorage.getItem('nygen-docs-sidebar:' + home.pathname);
+      if (saved !== null) sidebar.scrollTop = Number(saved);
+    }
+  });
+  observer.observe(document.documentElement, {childList: true, subtree: true});
+})();
+</script>"""
             links += f'<script defer src="{script_url}"></script>'
         if not count:
             links = canonical_tag + links
@@ -630,7 +650,7 @@ def link_shared_brand_assets(html: Path) -> None:
         config["options"][key]: source_options[key]
         for key in ("logo", "logo_dark", "favicon", "style")
     }
-    nodes = [config["parts"]["navbar_end"]["mdast"]]
+    nodes = [config["parts"]["footer"]["mdast"]]
     symbols = []
     while nodes:
         node = nodes.pop()
@@ -694,6 +714,67 @@ def link_shared_brand_assets(html: Path) -> None:
     (html / "myst-theme.css").unlink()
 
 
+def prepare_site_template(site: Path) -> None:
+    template_url = yaml.safe_load((site / "myst.yml").read_text())["site"]["template"]
+    template = (
+        site
+        / "_build"
+        / "templates"
+        / "site"
+        / hashlib.sha256(template_url.encode()).hexdigest()
+    )
+    if not (template / "template.yml").is_file():
+        subprocess.run(
+            ["myst", "templates", "download", "--site", template_url],
+            cwd=site,
+            check=True,
+        )
+    replacements = {
+        "build/index.js": (
+            'Pje.default.useState(i);(0,Pje.useEffect)(()=>{o.state==="idle"'
+            "&&s(tzt([t],e,r).includes(t.id))}",
+            'Pje.default.useState(!0);(0,Pje.useEffect)(()=>{o.state==="idle"&&s(!0)}',
+        ),
+        "public/build/_shared/chunk-LS4ALTVG.js": (
+            '_0.default.useState(o);(0,_0.useEffect)(()=>{i.state==="idle"'
+            "&&a(DS([t],e,r).includes(t.id))}",
+            '_0.default.useState(!0);(0,_0.useEffect)(()=>{i.state==="idle"&&a(!0)}',
+        ),
+    }
+    fingerprint = hashlib.sha256(
+        json.dumps(replacements, sort_keys=True).encode()
+    ).hexdigest()[:12]
+    for filename, (original, expanded) in replacements.items():
+        path = template / filename
+        if not path.is_file() and filename.startswith("public/"):
+            path = path.with_stem(f"{path.stem}-{fingerprint}")
+        content = path.read_text()
+        if content.count(original) == 1 and expanded not in content:
+            path.write_text(content.replace(original, expanded))
+        elif original in content or content.count(expanded) != 1:
+            raise ValueError(f"Unexpected navigation component in {path}")
+    modules = list((template / "public" / "build").rglob("*.js"))
+    filenames = {
+        path.name: f"{path.stem}-{fingerprint}.js"
+        for path in modules
+        if not path.stem.endswith(f"-{fingerprint}")
+    }
+    if not filenames:
+        return
+    if len({path.name for path in modules}) != len(modules):
+        raise ValueError(f"Duplicate browser module filenames in {template}")
+    references = re.compile(r"(?<![\w$().\[\]-])[\w$().\[\]-]+\.js\b")
+    for path in [template / "build" / "index.js", *modules]:
+        path.write_text(
+            references.sub(
+                lambda match: filenames.get(match[0], match[0]), path.read_text()
+            )
+        )
+    for path in modules:
+        if path.name in filenames:
+            path.rename(path.with_name(filenames[path.name]))
+
+
 def main() -> None:
     parser = argparse.ArgumentParser(description=__doc__)
     parser.add_argument(
@@ -702,9 +783,11 @@ def main() -> None:
         help="Allow missing executions and label those pages as source previews",
     )
     args = parser.parse_args()
+    site = prepare_site(preview=args.preview)
+    prepare_site_template(site)
     subprocess.run(
         ["myst", "build", "--html", "--strict"],
-        cwd=prepare_site(preview=args.preview),
+        cwd=site,
         check=True,
     )
     revision = subprocess.run(
diff --git a/docs/source/myst.yml b/docs/source/myst.yml
index 0eadda3..e09c250 100644
--- a/docs/source/myst.yml
+++ b/docs/source/myst.yml
@@ -46,7 +46,7 @@ site:
   template: https://github.com/myst-templates/book-theme/archive/23f2df5493e23dfb1d9433c8aa64c87beb4232a3.zip
   parts:
     primary_sidebar_footer: <!-- No sidebar footer. -->
-    navbar_end: '<a class="docs-home-link" href="https://docs.nygen.io/"><img class="brand-symbol" src="https://docs.nygen.io/assets/brand/logo/nygen-symbol.svg" alt="Nygen documentation home" width="32" height="32"></a>'
+    footer: '<a class="docs-home-link" href="https://docs.nygen.io/"><img class="brand-symbol" src="https://docs.nygen.io/assets/brand/logo/nygen-symbol.svg" alt="Nygen documentation home" width="32" height="32"></a>'
   options:
     folders: true
     style: https://docs.nygen.io/assets/brand/myst.css