[rightnav] implement an right in-page navigation (#83)

* [rightnav] implement an right in-page navigation * Resolve issues with rightnav (#84) * [rightnav] fix anchor links for headings * [rightnav] add max size to body to prevent overflows * [rightnav] remove comment above tocbot.init * expand anchor heading size for interactivity * remove prettier * remove unnecessary script --------- Co-authored-by: Jonah Bedouch <[email protected]>
cs161-staff · Sep 5, 2024 · 1cd8bb6 · 1cd8bb6
1 parent 37fb0ca
commit 1cd8bb6
Show file tree

Hide file tree

Showing 47 changed files with 502 additions and 24 deletions.
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
diff --git a/_includes/footer_custom.html b/_includes/footer_custom.html
@@ -0,0 +1,45 @@
+<script>
+  (function () {
+    var navList = document.querySelector('.aux-nav-list');
+    if (!navList || !navList.firstElementChild) return;
+    var darkToggle = navList.firstElementChild;
+    darkToggle.addEventListener('click', (e) => {
+      e.preventDefault();
+      toggleDark();
+    });
+  })();
+</script>
+
+<!--<script src="{{ '/assets/js/jquery.min.js' | relative_url }}"></script>-->
+<script>
+  // adapted from https://stackoverflow.com/a/48078807/1217368
+  // Waiting for https://github.com/just-the-docs/just-the-docs/pull/945
+  $(document).ready(function () {
+    $('pre.highlight').each(function (i) {
+      // create an id for the current code section
+      var currentId = 'codeBlock' + i;
+
+      // find the code section and add the id to it
+      var codeSection = $(this).find('code');
+      codeSection.attr('id', currentId);
+    });
+  });
+</script>
+
+<script src="{{ '/assets/js/tocbot.min.js' | relative_url }}"></script>
+<script>
+  tocbot.init({
+    tocSelector: '.js-toc',
+    contentSelector: '.main-content',
+    headingSelector: 'h2, h3',
+    ignoreSelector: '.no_toc',
+    hasInnerContainers: true,
+    linkClass: 'nav-list-link',
+    activeLinkClass: 'active',
+    listClass: 'nav-list',
+    listItemClass: 'nav-list-item',
+    activeListItemClass: 'active',
+    collapseDepth: 3,
+    scrollSmooth: false,
+  });
+</script>
diff --git a/_includes/nav.html b/_includes/nav.html
@@ -0,0 +1,95 @@
+<ul class="nav-list">
+  {%- assign titled_pages = include.pages | where_exp:"item", "item.title !=
+  nil" -%} {%- comment -%} The values of `title` and `nav_order` can be numbers
+  or strings. Jekyll gives build failures when sorting on mixtures of different
+  types, so numbers and strings need to be sorted separately. Here, numbers are
+  sorted by their values, and come before all strings. An omitted `nav_order`
+  value is equivalent to the page's `title` value (except that a numerical
+  `title` value is treated as a string). The case-sensitivity of string sorting
+  is determined by `site.nav_sort`. {%- endcomment -%} {%- assign
+  string_ordered_pages = titled_pages | where_exp:"item", "item.nav_order ==
+  nil" -%} {%- assign nav_ordered_pages = titled_pages | where_exp:"item",
+  "item.nav_order != nil" -%} {%- comment -%} The nav_ordered_pages have to be
+  added to number_ordered_pages and string_ordered_pages, depending on the
+  nav_order value. The first character of the jsonify result is `"` only for
+  strings. {%- endcomment -%} {%- assign nav_ordered_groups = nav_ordered_pages
+  | group_by_exp:"item", "item.nav_order | jsonify | slice: 0" -%} {%- assign
+  number_ordered_pages = "" | split:"X" -%} {%- for group in nav_ordered_groups
+  -%} {%- if group.name == '"' -%} {%- assign string_ordered_pages =
+  string_ordered_pages | concat: group.items -%} {%- else -%} {%- assign
+  number_ordered_pages = number_ordered_pages | concat: group.items -%} {%-
+  endif -%} {%- endfor -%} {%- assign sorted_number_ordered_pages =
+  number_ordered_pages | sort:"nav_order" -%} {%- comment -%} The
+  string_ordered_pages have to be sorted by nav_order, and otherwise title
+  (where appending the empty string to a numeric title converts it to a string).
+  After grouping them by those values, the groups are sorted, then the items of
+  each group are concatenated. {%- endcomment -%} {%- assign
+  string_ordered_groups = string_ordered_pages | group_by_exp:"item",
+  "item.nav_order | default: item.title | append:''" -%} {%- if site.nav_sort ==
+  'case_insensitive' -%} {%- assign sorted_string_ordered_groups =
+  string_ordered_groups | sort_natural:"name" -%} {%- else -%} {%- assign
+  sorted_string_ordered_groups = string_ordered_groups | sort:"name" -%} {%-
+  endif -%} {%- assign sorted_string_ordered_pages = "" | split:"X" -%} {%- for
+  group in sorted_string_ordered_groups -%} {%- assign
+  sorted_string_ordered_pages = sorted_string_ordered_pages | concat:
+  group.items -%} {%- endfor -%} {%- assign pages_list =
+  sorted_number_ordered_pages | concat: sorted_string_ordered_pages -%} {%- for
+  node in pages_list -%} {%- if node.parent == nil -%} {%- unless
+  node.nav_exclude or node.released == false and jekyll.environment != "debug"
+  -%} {%- assign url_size = node.url | size -%} {%- assign prefix = page.url |
+  slice: 0, url_size -%}
+  <li
+    class="nav-list-item{% if page.collection == include.key and page.url == node.url or node.url == prefix %} active{% endif %}"
+  >
+    {%- if node.has_children -%}
+    <a href="#" class="nav-list-expander"
+      ><svg viewBox="0 0 24 24"><use xlink:href="#svg-arrow-right"></use></svg
+    ></a>
+    {%- endif -%}
+    <a
+      href="{{ node.url | relative_url }}"
+      class="nav-list-link{% if page.url == node.url %} active{% endif %}"
+      >{{ node.title }}</a
+    >
+    {%- if node.has_children -%} {%- if node.child_nav_order == 'desc' -%} {%-
+    assign children_list = pages_list | where: "parent", node.title |
+    where_exp:"item", "item.grand_parent == nil" | reverse -%} {%- else -%} {%-
+    assign children_list = pages_list | where: "parent", node.title |
+    where_exp:"item", "item.grand_parent == nil" -%} {%- endif -%}
+    <ul class="nav-list">
+      {%- for child in children_list -%} {%- include nav_list.html node=child
+      depth=1 -%} {%- comment -%} Hack to display anchors in the navbar for
+      projects. Somewhat adapted from
+      https://github.com/just-the-docs/just-the-docs/issues/325. Hopefully Just
+      the Docs adds built-in support for this soon and obsoletes this hack. {%-
+      endcomment -%} {%- endfor -%}
+    </ul>
+    {%- endif -%}
+  </li>
+  {%- endunless -%} {%- endif -%} {%- endfor -%} {%- assign nav_external_links =
+  site.nav_external_links -%} {%- for node in nav_external_links -%}
+  <li class="nav-list-item external">
+    <a href="{{ node.url | absolute_url }}" class="nav-list-link external">
+      {{ node.title }} {% unless node.hide_icon %}<svg
+        viewBox="0 0 24 24"
+        aria-labelledby="svg-external-link-title"
+      >
+        <use xlink:href="#svg-external-link"></use></svg
+      >{% endunless %}
+    </a>
+  </li>
+  {%- endfor -%}
+</ul>
+
+{%- if page.collection == include.key -%} {%- for node in pages_list -%} {%- if
+node.parent == nil -%} {%- if page.grand_parent == node.title or page.parent ==
+node.title and page.grand_parent == nil -%} {%- assign first_level_url =
+node.url | relative_url -%} {%- endif -%} {%- if node.has_children -%} {%-
+assign children_list = pages_list | where: "parent", node.title -%} {%- for
+child in children_list -%} {%- if child.has_children -%} {%- if page.url ==
+child.url or page.parent == child.title and page.grand_parent == child.parent
+-%} {%- assign second_level_url = child.url | relative_url -%} {%- endif -%} {%-
+endif -%} {%- endfor -%} {%- endif -%} {%- endif -%} {%- endfor -%} {% if
+page.has_children == true and page.has_toc != false %} {%- assign toc_list =
+pages_list | where: "parent", page.title | where: "grand_parent", page.parent
+-%} {%- endif -%} {%- endif -%}
diff --git a/_includes/nav_list.html b/_includes/nav_list.html
@@ -0,0 +1,21 @@
+{%- unless include.node.nav_exclude or include.node.released == false and
+jekyll.environment != "debug" -%} {%- assign include.node_url_size =
+include.node.url | size -%} {%- assign url_size = include.node.url | size -%}
+{%- assign prefix = page.url | slice: 0, url_size -%}
+<li class="nav-list-item {% if include.node.url == prefix %} active{% endif %}">
+  <a
+    href="{{ include.node.url | relative_url }}"
+    class="nav-list-link{% if page.url == include.node.url %} active{% endif %}"
+    >{{ include.node.title }}</a
+  >
+  {%- if include.node.has_children and include.depth <= site.max_nav_depth -%}
+  {%- if include.node.child_nav_order == 'desc' -%} {%- assign children_list =
+  pages_list | where: "parent", include.node.title | reverse -%} {%- else -%}
+  {%- assign children_list = pages_list | where: "parent", include.node.title
+  -%} {%- endif -%} {%- assign children_depth = include.depth | plus:1 -%}
+  <ul class="nav-list child">
+    {%- for child in children_list -%} {%- include nav_list.html node=child
+    depth=children_depth -%} {%- endfor -%}
+  </ul>
+  {%- endif -%} {%- endunless -%}
+</li>
diff --git a/_includes/sidebar.html b/_includes/sidebar.html
@@ -0,0 +1,42 @@
+{%- comment -%} This file is from Just the Docs v0.8.2 remote:
+https://github.com/just-the-docs/just-the-docs/blob/15a0b6e91b687bc2a8fdf8345c8e1cc3baa7b2d8/_includes/components/sidebar.html
+I've copied it into this repo and inserted some hacks to enable displaying
+anchors and scrollspy in the sidebar. ~peyrin, June 2024 {%- endcomment -%} {%-
+comment -%} Include as: {%- include components/sidebar.html -%} Depends on:
+page(?), site. Results in: HTML for the side bar. Includes: title.html,
+components/site_nav.html, nav_footer_custom.html Overwrites: nav_footer_custom.
+Should not be cached, because nav_footer_custom.html might depend on page. {%-
+endcomment -%}
+
+<div class="side-bar">
+  <div class="site-header" role="banner">
+    <a href="{{ '/' | relative_url }}" class="site-title lh-tight"
+      >{% include title.html %}</a
+    >
+    <button
+      id="menu-button"
+      class="site-button btn-reset"
+      aria-label="Toggle menu"
+      aria-pressed="false"
+    >
+      <svg viewBox="0 0 24 24" class="icon" aria-hidden="true">
+        <use xlink:href="#svg-menu"></use>
+      </svg>
+    </button>
+  </div>
+
+  {%- comment -%} The caching here is messing with nav.html being able to fetch
+  the current page. My lazy solution is to say "include" instead of
+  "include_cached", though a more robust solution for really large websites
+  would pass in the page url as a parameter. I've never noticed a performance
+  impact for Berkeley CS sized websites though (<100 pages in the navbar). {%-
+  endcomment -%} {% include components/site_nav.html %} {% capture
+  nav_footer_custom %} {%- include nav_footer_custom.html -%} {% endcapture %}
+  {% if nav_footer_custom != "" %} {{ nav_footer_custom }} {% else %}
+  <footer class="site-footer">
+    This site uses
+    <a href="https://github.com/just-the-docs/just-the-docs">Just the Docs</a>,
+    a documentation theme for Jekyll.
+  </footer>
+  {% endif %}
+</div>
diff --git a/_includes/toc.html b/_includes/toc.html
@@ -0,0 +1,156 @@
+{% capture tocWorkspace %}
+    {% comment %}
+        Copyright (c) 2017 Vladimir "allejo" Jimenez
+
+        Permission is hereby granted, free of charge, to any person
+        obtaining a copy of this software and associated documentation
+        files (the "Software"), to deal in the Software without
+        restriction, including without limitation the rights to use,
+        copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the
+        Software is furnished to do so, subject to the following
+        conditions:
+
+        The above copyright notice and this permission notice shall be
+        included in all copies or substantial portions of the Software.
+
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+        EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
+        OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+        NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
+        HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+        WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+        FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
+        OTHER DEALINGS IN THE SOFTWARE.
+    {% endcomment %}
+    {% comment %}
+        Version 1.2.1
+          https://github.com/allejo/jekyll-toc
+
+        "...like all things liquid - where there's a will, and ~36 hours to spare, there's usually a/some way" ~jaybe
+
+        Usage:
+            {% include toc.html html=content sanitize=true class="inline_toc" id="my_toc" h_min=2 h_max=3 %}
+
+        Parameters:
+            * html         (string) - the HTML of compiled markdown generated by kramdown in Jekyll
+
+        Optional Parameters:
+            * sanitize      (bool)   : false  - when set to true, the headers will be stripped of any HTML in the TOC
+            * class         (string) :   ''   - a CSS class assigned to the TOC
+            * id            (string) :   ''   - an ID to assigned to the TOC
+            * h_min         (int)    :   1    - the minimum TOC header level to use; any header lower than this value will be ignored
+            * h_max         (int)    :   6    - the maximum TOC header level to use; any header greater than this value will be ignored
+            * ordered       (bool)   : false  - when set to true, an ordered list will be outputted instead of an unordered list
+            * item_class    (string) :   ''   - add custom class(es) for each list item; has support for '%level%' placeholder, which is the current heading level
+            * submenu_class (string) :   ''   - add custom class(es) for each child group of headings; has support for '%level%' placeholder which is the current "submenu" heading level
+            * base_url      (string) :   ''   - add a base url to the TOC links for when your TOC is on another page than the actual content
+            * anchor_class  (string) :   ''   - add custom class(es) for each anchor element
+            * skip_no_ids   (bool)   : false  - skip headers that do not have an `id` attribute
+            * flat_toc      (bool)   : false  - when set to true, the TOC will be a single level list
+
+        Output:
+            An ordered or unordered list representing the table of contents of a markdown block. This snippet will only
+            generate the table of contents and will NOT output the markdown given to it
+    {% endcomment %}
+
+    {% capture newline %}
+    {% endcapture %}
+    {% assign newline = newline | rstrip %} <!-- Remove the extra spacing but preserve the newline -->
+
+    {% capture deprecation_warnings %}{% endcapture %}
+
+    {% capture jekyll_toc %}{% endcapture %}
+    {% assign baseURL = include.base_url | default: include.baseurl | default: '' %}
+    {% assign minHeader = include.h_min | default: 1 %}
+    {% assign maxHeader = include.h_max | default: 6 %}
+    {% assign nodes = include.html | strip | split: '<h' %}
+
+    {% assign firstHeader = true %}
+    {% assign currLevel = 0 %}
+    {% assign lastLevel = 0 %}
+
+    {% capture listModifier %}ul{% endcapture %}
+
+    {% for node in nodes %}
+        {% if node == "" %}
+            {% continue %}
+        {% endif %}
+
+        {% assign currLevel = node | replace: '"', '' | slice: 0, 1 | times: 1 %}
+
+        {% if currLevel < minHeader or currLevel > maxHeader %}
+            {% continue %}
+        {% endif %}
+
+        {% assign _workspace = node | split: '</h' %}
+
+        {% assign _idWorkspace = _workspace[0] | split: 'id="' %}
+        {% assign _idWorkspace = _idWorkspace[1] | split: '"' %}
+        {% assign htmlID = _idWorkspace[0] %}
+
+        {% assign _classWorkspace = _workspace[0] | split: 'class="' %}
+        {% assign _classWorkspace = _classWorkspace[1] | split: '"' %}
+        {% assign htmlClass = _classWorkspace[0] %}
+
+        {% if htmlClass contains "no_toc" %}
+            {% continue %}
+        {% endif %}
+
+        {% if firstHeader %}
+            {% assign minHeader = currLevel %}
+        {% endif %}
+
+        {% capture _hAttrToStrip %}{{ _workspace[0] | split: '>' | first }}>{% endcapture %}
+        {% assign header = _workspace[0] | replace: _hAttrToStrip, '' %}
+
+        {% if include.item_class and include.item_class != blank %}
+            {% capture listItemClass %} class="{{ include.item_class | replace: '%level%', currLevel | split: '.' | join: ' ' }}"{% endcapture %}
+        {% endif %}
+
+        {% capture anchorBody %}{% if include.sanitize %}{{ header | strip_html }}{% else %}{{ header }}{% endif %}{% endcapture %}
+
+        {% if htmlID %}
+            {% capture anchorAttributes %} href="{% if baseURL %}{{ baseURL }}{% endif %}#{{ htmlID }}"{% endcapture %}
+
+            {% if include.anchor_class %}
+                {% capture anchorAttributes %}{{ anchorAttributes }} class="{{ include.anchor_class | split: '.' | join: ' ' }}"{% endcapture %}
+            {% endif %}
+
+            {% capture listItem %}<a{{ anchorAttributes }}>{{ anchorBody }}</a>{% endcapture %}
+        {% else %}
+            {% capture listItem %}{{ anchorBody }}{% endcapture %}
+        {% endif %}
+
+        {% if currLevel > lastLevel %}
+            {% capture jekyll_toc %}{{ jekyll_toc }}<{{ listModifier }}>{% endcapture %}
+        {% elsif currLevel < lastLevel %}
+            {% assign repeatCount = lastLevel | minus: currLevel %}
+
+            {% for i in (1..repeatCount) %}
+                {% capture jekyll_toc %}{{ jekyll_toc }}</li></{{ listModifier }}>{% endcapture %}
+            {% endfor %}
+
+            {% capture jekyll_toc %}{{ jekyll_toc }}</li>{% endcapture %}
+        {% else %}
+            {% capture jekyll_toc %}{{ jekyll_toc }}</li>{% endcapture %}
+        {% endif %}
+
+        {% capture jekyll_toc %}{{ jekyll_toc }}<li{{ listItemClass }}>{{ listItem }}{% endcapture %}
+
+        {% assign lastLevel = currLevel %}
+        {% assign firstHeader = false %}
+    {% endfor %}
+
+    {% assign repeatCount = minHeader | minus: 1 %}
+    {% assign repeatCount = lastLevel | minus: repeatCount %}
+
+    {% for i in (1..repeatCount) %}
+        {% capture jekyll_toc %}{{ jekyll_toc }}</li></{{ listModifier }}>{% endcapture %}
+    {% endfor %}
+
+    {% capture modified_toc %}
+    {{ jekyll_toc | replace: '<ol class="nav-list', '<ul class="nav-list' | replace: '</ol>', '</ul>' }}
+    {% endcapture %}
+
+{% endcapture %}{% assign tocWorkspace = '' %}{{ deprecation_warnings }}{{ modified_toc -}}