👌 Add class to loaded document

Author: chrisjsewell

docs/_static/custom.css

@@ -0,0 +1,9 @@
+/** Hide the header and footer of the Sphinx documentation,
+    when it is embedded in a sphinx-peek iframe.
+*/
+.sp-iframe-document .mobile-header,
+.sp-iframe-document .back-to-top,
+.sp-iframe-document .bottom-of-page,
+.sp-iframe-document .related-pages {
+  display: none;
+}

docs/conf.py

@@ -14,3 +14,4 @@
     "light_logo": "logo-light-mode.png",
     "dark_logo": "logo-dark-mode.png",
 }
+html_css_files = ["custom.css"]

docs/index.rst

@@ -41,7 +41,7 @@ Simply install and add ``sphinx_peek`` to your ``conf.py`` extensions list.
 .. important::
 
     The scroll-to-target behaviour, inside the iframe,
-    only works reliably for same-origin references, due to browser security restrictions (see `CORS reference <https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS>`__).
+    only works reliably for same-origin_ or CORS_ enabled references.
 
     To test the feature locally, rather than directly opening the ``.html`` file, you can serve the documentation using a simple HTTP server, e.g.:
 
@@ -64,6 +64,18 @@ Also, the CSS of the peek modal can be customized (see `html_css_files <https://
 - ``.sp-iframe``: the iframe containing the target document
 - ``.sp-overlay``: the overlay that covers the rest of the page
 
+After loading the page, into the iframe, the extension will also add a class ``.sp-iframe-document`` to the root document.
+This allows you to customize the CSS of the target document, e.g. to hide header and footer elements in the furo theme:
+
+.. code-block:: css
+
+    .sp-iframe-document .mobile-header,
+    .sp-iframe-document .back-to-top,
+    .sp-iframe-document .bottom-of-page,
+    .sp-iframe-document .related-pages {
+        display: none;
+    }
+
 More Examples
 -------------
 
@@ -83,3 +95,7 @@ A reference to :ref:`other:subsection` within a paragraph.
     :hidden:
 
     other
+
+
+.. _CORS: https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS
+.. _same-origin: https://developer.mozilla.org/en-US/docs/Web/Security/Same-origin_policy

src/sphinx_peek/assets/sphinx_peek.js

@@ -86,7 +86,7 @@ document.addEventListener("DOMContentLoaded", function () {
     let link_target = this.getAttribute("data-sp-link");
     this.insertAdjacentHTML(
       "beforeend",
-      `<div id="sp_overlay" class="sp-overlay"><div id="sp_modal" class="sp-modal"><iframe id="sp_preframe" class="sp-iframe" src="${link_target}" onload=scrollToContent(this)></iframe></div></div>`,
+      `<div id="sp_overlay" class="sp-overlay"><div id="sp_modal" class="sp-modal"><iframe id="sp_preframe" class="sp-iframe" src="${link_target}" onload=onIframeLoad(this)></iframe></div></div>`,
     );
     // stop click event propagation on the preview window,
     // to prevent closing the preview if we resize it (treated as a click)
@@ -195,67 +195,66 @@ function setPreviewPosition(preview, anchor, config) {
  *
  * @param {HTMLIFrameElement} iframe - The iframe that was loaded.
  */
-function scrollToContent(iframe) {
-  var target = iframe.getAttribute("src");
-  if (target === null) {
-    console.warn(
-      `Sphinx Peek: Cannot get iframe src attribute for '${target}'`,
-    );
-    return;
-  }
-  let targetIndex = target.indexOf("#");
-  var targetId = target.substring(targetIndex + 1);
-  if (targetIndex !== -1 && targetId !== "") {
-    setTimeout(function () {
-      // try to get iframe contentDocument (this is the same as iframe.contentWindow.document)
-      // if we cannot access the iframe content, we cannot scroll to the target
-      // this can happen if the iframe is not on the same domain, or the page is not being served, due to CORS
-      // https://developer.mozilla.org/en-US/docs/Web/API/HTMLIFrameElement/contentDocument
-      try {
-        var contentDocument = iframe.contentDocument;
-      } catch (e) {
-        console.warn(
-          `Sphinx Peek: Cannot access iframe contentDocument for '${target}': ${e}`,
-        );
-        return;
-      }
-      if (contentDocument === null) {
-        console.warn(
-          `Sphinx Peek: Cannot access iframe contentDocument for '${target}'`,
-        );
-        return;
-      }
+function onIframeLoad(iframe) {
+  setTimeout(function () {
+    // try to get iframe contentDocument (this is the same as iframe.contentWindow.document)
+    // if we cannot access the iframe content, we cannot scroll to the target
+    // this can happen if the iframe is not on the same domain, or the page is not being served, due to CORS
+    // https://developer.mozilla.org/en-US/docs/Web/API/HTMLIFrameElement/contentDocument
+    try {
+      var contentDocument = iframe.contentDocument;
+    } catch (e) {
+      console.info(
+        `Sphinx Peek: Cannot access iframe contentDocument: ${e}`,
+        iframe,
+      );
+      return;
+    }
+    if (contentDocument === null) {
+      console.info("Sphinx Peek: Cannot access iframe contentDocument", iframe);
+      return;
+    }
 
-      // try to get the target element by id
-      var element = contentDocument.getElementById(targetId);
-      if (element === null) {
-        console.warn(
-          `Sphinx Peek: Anchor does not exist in iframe contentDocument: ${target}`,
-        );
-        return;
-      }
+    // add a class to the iframe document, so we can add CSS depending on it
+    contentDocument.documentElement.classList.add("sp-iframe-document");
 
-      // https://developer.mozilla.org/en-US/docs/Web/API/Element/scrollIntoView#behavior
-      // Note this seems to have some differing behavior between browsers:
-      // - Firefox (OSX arm64, 121.0): works as expected
-      // - Chrome (OSX arm64, 120.0.6099.216):
-      //   - does not appear to respect the behavior "instant", i.e. the scrolling is visible
-      // - Safari (OSX arm64, 17.2.1):
-      //   - it can sometimes scroll the parent page as well to bring the element to the top of parent page
-      let scrollTop = window.document.documentElement.scrollTop;
-      element.scrollIntoView({ behavior: "instant" });
-      if (window.document.documentElement.scrollTop !== scrollTop) {
-        // "fix" the Safari behavior by restoring the original scroll position
-        // TODO this should also be done for all window parents, i.e. when opening nested iframes
-        window.document.documentElement.scrollTo({
-          top: scrollTop,
-          behavior: "instant",
-        });
+    let src = iframe.getAttribute("src");
+    if (src === null) {
+      console.warn("Sphinx Peek: Cannot get iframe 'src' attribute", iframe);
+    } else {
+      let anchorIndex = src.indexOf("#");
+      let anchorId = src.substring(anchorIndex + 1);
+      if (anchorIndex !== -1 && anchorId !== "") {
+        // try to get the anchor element by id
+        let anchor = contentDocument.getElementById(anchorId);
+        if (anchor === null) {
+          console.warn(
+            `Sphinx Peek: Anchor ${anchorId} does not exist in iframe contentDocument`,
+            iframe,
+          );
+          return;
+        }
+        // https://developer.mozilla.org/en-US/docs/Web/API/Element/scrollIntoView#behavior
+        // Note this seems to have some differing behavior between browsers:
+        // - Firefox (OSX arm64, 121.0): works as expected
+        // - Chrome (OSX arm64, 120.0.6099.216):
+        //   - does not appear to respect the behavior "instant", i.e. the scrolling is visible
+        // - Safari (OSX arm64, 17.2.1):
+        //   - it can sometimes scroll the parent page as well to bring the element to the top of parent page
+        let scrollTop = window.document.documentElement.scrollTop;
+        anchor.scrollIntoView({ behavior: "instant" });
+        if (window.document.documentElement.scrollTop !== scrollTop) {
+          // "fix" the Safari behavior by restoring the original scroll position
+          // TODO this should also be done for all window parents, i.e. when opening nested iframes
+          window.document.documentElement.scrollTo({
+            top: scrollTop,
+            behavior: "instant",
+          });
+        }
+        // Note this was another solution proposed, but it does not seem to work
+        // https://stackoverflow.com/questions/20956663/scrollintoview-to-apply-to-iframe-only/20958953#20958953
+        // contentDocument.documentElement.scrollTop = element.offsetTop;
       }
-
-      // Note this was another solution proposed, but it does not seem to work
-      // https://stackoverflow.com/questions/20956663/scrollintoview-to-apply-to-iframe-only/20958953#20958953
-      // contentDocument.documentElement.scrollTop = element.offsetTop;
-    }, 500);
-  }
+    }
+  }, 200);
 }