Merge pull request #90 from GeoscienceAustralia/feature/copyable-anch…

…or-links

Copyable headings and tabs

docs/_layout/layout.html

@@ -5,6 +5,7 @@
 
 <script type="text/javascript" src="/_static/scripts/content-root.js"></script>
 <script type="text/javascript" src="/_static/scripts/links-behaviour.js"></script>
+<script type="text/javascript" src="/_static/scripts/headings-behaviour.js"></script>
 
 <!-- Google tag (gtag.js) -->
 <script async src="https://www.googletagmanager.com/gtag/js?id={{ google_analytics_ga4_tag }}"></script>

docs/_static/scripts/headings-behaviour.js

@@ -0,0 +1,114 @@
+// Standardises the headings and their anchor IDs. Adds behaviour to headings and tabs that adds their IDs to the URL.
+// The sections of this script are in order of precedence. Each time a 'data-anchor-id' property is added to a heading, it will override any existing 'data-anchor-id' that was set previously.
+
+document.addEventListener("DOMContentLoaded", function (event) {
+    // Convert the '.rubric.h2' elements to H2 headings.
+
+    (function() {
+        let h2Rubrics = document.querySelectorAll("p.rubric.h2");
+
+        for (let i = 0; i < h2Rubrics.length; i++) {
+            let rubric = h2Rubrics[i];
+            let h2 = document.createElement("h2");
+            h2.id = rubric.id;
+            h2.class = rubric.class;
+            h2.innerHTML = rubric.innerHTML;
+            rubric.parentNode.replaceChild(h2, rubric);
+        }
+    })();
+
+    // Add the section ID to the heading's 'data-anchor-id' property.
+
+    (function() {
+        let sections = document.querySelectorAll("section[id]");
+
+        for (let i = 0; i < sections.length; i++) {
+            let section = sections[i];
+            let id = section.id;
+            let maybeHeading = section.querySelector("* > h2, * > h3");
+
+            if (maybeHeading) {
+                maybeHeading.dataset.anchorId = id;
+            }
+        }
+    })();
+
+    // Add heading's own ID to the heading's 'data-anchor-id' property.
+
+    (function() {
+        let headings = document.querySelectorAll("h2, h3");
+
+        for (var i = 0; i < headings.length; i++) {
+            let heading = headings[i];
+            let id = heading.id;
+
+            if (id) {
+                heading.dataset.anchorId = id;
+            }
+        }
+    })();
+
+    // Add the custom ID element above the heading to the heading's 'data-anchor-id' property
+
+    (function() {
+        let headings = document.querySelectorAll("h2, h3");
+
+        for (var i = 0; i < headings.length; i++) {
+            let heading = headings[i];
+            let maybeCustomIdElement = heading.previousSibling;
+
+            if (maybeCustomIdElement && maybeCustomIdElement.nodeName === "SPAN" && maybeCustomIdElement.hasAttribute("id")) {
+                let conflictingIdPattern = /id\d+/g;
+                let customId = maybeCustomIdElement.id;
+
+                // Checks that the ID is not 'id1', 'id2', 'id3', or etc. These IDs occur to prevent a naming conflict between IDs.
+                // E.g. if a heading 'Introduction' has a '(introduction)=' custom ID above it, this naming conflict will occur.
+                if (!conflictingIdPattern.test(customId)) {
+                    heading.dataset.anchorId = customId;
+                }
+            }
+        }
+    })();
+
+    // Clicking on a heading will add its anchor ID to the URL. E.g. /example/#introduction
+
+    (function() {
+        let headings = document.querySelectorAll("h2[data-anchor-id], h3[data-anchor-id]");
+
+        for (var i = 0; i < headings.length; i++) {
+            let heading = headings[i];
+            let anchorId = heading.dataset.anchorId;
+
+            heading.addEventListener("click", function() {
+                console.log(anchorId);
+                window.location.hash = `#${anchorId}`
+            });
+        }
+    })();
+
+    // Clicking on a product tab will add its tab ID to the URL. E.g. /example/?tab=overview
+
+    (function() {
+        let tabs = document.querySelectorAll(".product-page .sd-tab-label");
+        let tabUrlParam = new URLSearchParams(window.location.search).get("tab");
+        let overviewTabId = tabs[0].id;
+
+        if(!tabUrlParam) {
+            window.history.pushState("", "", `?tab=${overviewTabId}${window.location.hash}`);
+        } else {
+            document.querySelector(`.sd-tab-set > #${tabUrlParam}`).click();
+        }
+
+        for (let i = 0; i < tabs.length; i++) {
+            let tab = tabs[i];
+            let tabId = tab.id;
+
+            if (tabId) {
+                tab.addEventListener("click", function() {
+                    window.history.pushState("", "", `?tab=${tabId}`);
+                });
+            }
+        }
+    })();
+});
+

docs/_static/scripts/product-table-of-contents.js

@@ -1,51 +1,15 @@
 // Enable tables of content on the data product pages using tocbot.
 
 document.addEventListener("DOMContentLoaded", function (event) {
-    // Move the section IDs to the H2 headings
-
-    let sections = document.querySelectorAll(
-        ".product-page .sd-tab-content > section[id]"
-    );
-
-    for (let i = 0; i < sections.length; i++) {
-        let section = sections[i];
-        let id = section.id;
-        section.removeAttribute("id");
-        section.querySelector("* > h2").id = id;
-    }
-
-    // Convert the 'rubrics' to H2 headings
-
-    let rubrics = document.querySelectorAll(
-        ".product-page .sd-tab-content > p.rubric"
-    );
-
-    for (let i = 0; i < rubrics.length; i++) {
-        let rubric = rubrics[i];
-        let h2 = document.createElement("h2");
-        h2.id = rubric.id;
-        h2.class = rubric.class;
-        h2.innerHTML = rubric.innerHTML;
-        rubric.parentNode.replaceChild(h2, rubric);
-    }
-
-    // Initialise the table of contents for each tab
-
-    let tabs = [
-        "overview",
-        "access",
-        "details",
-        "quality",
-        "history",
-        "faqs",
-        "credits"
-    ];
+    let tabs = document.querySelectorAll(".product-page .sd-tab-label");
 
     for (let i = 0; i < tabs.length; i++) {
         let tab = tabs[i];
+        let id = tab.id;
+
         tocbot.init({
-            contentSelector: `.product-page #${tab} + .sd-tab-content`,
-            tocSelector: `.product-page #${tab}-table-of-contents`,
+            contentSelector: `.product-page #${id} + .sd-tab-content`,
+            tocSelector: `.product-page #${id} + .sd-tab-content > .tocbot-selector`,
             headingSelector: "h2"
         });
     }

docs/_static/styles/components/_anchor_heading.scss

@@ -0,0 +1,6 @@
+[data-anchor-id] {
+    &:hover {
+        cursor: pointer;
+        text-decoration: underline dashed;
+    }
+}

docs/_static/styles/components/_product_table_of_contents.scss

@@ -1,4 +1,4 @@
-.table-of-contents {
+.tocbot-selector {
     $font-size: 0.85rem;
 
     @media only screen and (max-width: $breakpoint-md) {

docs/_static/styles/components/_rubric.scss

@@ -0,0 +1,3 @@
+p.rubric {
+    &.h2 {}
+}

docs/_static/styles/components/_showcase_panel.scss

@@ -38,6 +38,9 @@
     & > div > .rubric {
         font-size: 1.65rem;
         font-weight: bold;
+        margin: 0;
+        color: white;
+        line-height: 1.65;
     }
 
     &.reverse {

docs/_static/styles/index.scss

@@ -25,3 +25,5 @@
 @import "components/processing_steps";
 @import "components/links";
 @import "components/tags_list";
+@import "components/anchor_heading";
+@import "components/rubric";

docs/_templates/product-v1.rst

@@ -103,19 +103,17 @@
     .. tab-item:: Overview
        :name: overview
 
-       .. container:: table-of-contents
+       .. raw:: html
 
-          .. container::
-             :name: overview-table-of-contents
-
-             |nbsp|
+          <div class="tocbot-selector"></div>
 
        .. include:: _overview_1.md
           :parser: myst_parser.sphinx_
 
        {% if has_access_data %}
        .. rubric:: Access the data
           :name: access-the-data
+          :class: h2
 
        For help accessing the data, see the 'Access' tab.
 
@@ -178,6 +176,7 @@
        {% if has_key_details %}
        .. rubric:: Key details
           :name: key-details
+          :class: h2
 
        .. list-table::
           :name: key-details-table
@@ -221,12 +220,9 @@
     .. tab-item:: Details
        :name: details
 
-       .. container:: table-of-contents
-
-          .. container::
-             :name: details-table-of-contents
+       .. raw:: html
 
-             |nbsp|
+          <div class="tocbot-selector"></div>
 
        .. include:: _details.md
           :parser: myst_parser.sphinx_
@@ -236,12 +232,9 @@
     .. tab-item:: Quality
        :name: quality
 
-       .. container:: table-of-contents
+       .. raw:: html
 
-          .. container::
-             :name: quality-table-of-contents
-
-             |nbsp|
+          <div class="tocbot-selector"></div>
 
        .. include:: _quality.md
           :parser: myst_parser.sphinx_
@@ -251,15 +244,13 @@
     .. tab-item:: Access
        :name: access
 
-       .. container:: table-of-contents
-
-          .. container::
-             :name: access-table-of-contents
+       .. raw:: html
 
-             |nbsp|
+          <div class="tocbot-selector"></div>
 
        .. rubric:: Access the data
           :name: access-the-data-2
+          :class: h2
 
        {% if has_access_data %}
        .. list-table::
@@ -318,6 +309,7 @@
 
        .. rubric:: Additional files
           :name: additional-files
+          :class: h2
 
        .. list-table::
           :name: additional-files-table
@@ -336,21 +328,20 @@
     .. tab-item:: History
        :name: history
 
-       .. container:: table-of-contents
+       .. raw:: html
 
-          .. container::
-             :name: history-table-of-contents
-
-             |nbsp|
+          <div class="tocbot-selector"></div>
 
        {% if not is_latest_version %}
        .. rubric:: Other versions
           :name: other-versions
+          :class: h2
 
        You can find the history in the `latest version of the product <{{ data.latest_version_link }}>`_.
        {% else %}
        .. rubric:: Old versions
           :name: old-versions
+          :class: h2
 
        {% if valid_old_versions %}
 
@@ -374,12 +365,9 @@
     .. tab-item:: FAQs
        :name: faqs
 
-       .. container:: table-of-contents
-
-          .. container::
-             :name: faqs-table-of-contents
+       .. raw:: html
 
-             |nbsp|
+          <div class="tocbot-selector"></div>
 
        .. include:: _faqs.md
           :parser: myst_parser.sphinx_
@@ -389,12 +377,9 @@
     .. tab-item:: Credits
        :name: credits
 
-       .. container:: table-of-contents
-
-          .. container::
-             :name: credits-table-of-contents
+       .. raw:: html
 
-             |nbsp|
+          <div class="tocbot-selector"></div>
 
        .. include:: _credits.md
           :parser: myst_parser.sphinx_
@@ -404,5 +389,4 @@
 
    <script type="text/javascript" src="/_static/scripts/vendors/tocbot.min.js"></script>
    <script type="text/javascript" src="/_static/scripts/product-table-of-contents.js" /></script>
-   <script type="text/javascript" src="/_static/scripts/product-tab-deep-links.js" /></script>
    <script type="text/javascript" src="/_static/scripts/access-cards-tooltips.js" /></script>