diff --git a/.devcontainer/Dockerfile b/.devcontainer/Dockerfile new file mode 100644 index 00000000..19e72747 --- /dev/null +++ b/.devcontainer/Dockerfile @@ -0,0 +1,14 @@ +# [Choice] Debian OS version (use bullseye on local arm64/Apple Silicon): bullseye, buster +ARG VARIANT=bullseye +FROM mcr.microsoft.com/vscode/devcontainers/jekyll:0-${VARIANT} + +# [Choice] Node.js version: none, lts/*, 16, 14, 12, 10 +ARG NODE_VERSION="none" +RUN if [ "${NODE_VERSION}" != "none" ]; then su vscode -c "umask 0002 && . /usr/local/share/nvm/nvm.sh && nvm install ${NODE_VERSION} 2>&1"; fi + +# [Optional] Uncomment this section to install additional OS packages. +# RUN apt-get update && export DEBIAN_FRONTEND=noninteractive \ +# && apt-get -y install --no-install-recommends + +# [Optional] Uncomment this line to install global node packages. +# RUN su vscode -c "source /usr/local/share/nvm/nvm.sh && npm install -g " 2>&1 \ No newline at end of file diff --git a/.devcontainer/base.Dockerfile b/.devcontainer/base.Dockerfile new file mode 100644 index 00000000..9e3296a6 --- /dev/null +++ b/.devcontainer/base.Dockerfile @@ -0,0 +1,26 @@ +# [Choice] Debian OS version (use 2.7-bullseye on local arm64/Apple Silicon): 2.7-bullseye, 2.7-buster +ARG VARIANT=2.7-bullseye +FROM mcr.microsoft.com/vscode/devcontainers/ruby:${VARIANT} +COPY library-scripts/meta.env /usr/local/etc/vscode-dev-containers + +# ENV Variables required by Jekyll +ENV LANG=en_US.UTF-8 \ + LANGUAGE=en_US:en \ + TZ=Etc/UTC \ + LC_ALL=en_US.UTF-8 \ + LANG=en_US.UTF-8 \ + LANGUAGE=en_US + +# Install bundler, latest jekyll, and github-pages for older jekyll +RUN gem install bundler jekyll github-pages + +# [Choice] Node.js version: none, lts/*, 16, 14, 12, 10 +ARG NODE_VERSION="none" +RUN if [ "${NODE_VERSION}" != "none" ]; then su vscode -c "umask 0002 && . /usr/local/share/nvm/nvm.sh && nvm install ${NODE_VERSION} 2>&1"; fi + +# [Optional] Uncomment this section to install additional OS packages. +# RUN apt-get update && export DEBIAN_FRONTEND=noninteractive \ +# && apt-get -y install --no-install-recommends + +# [Optional] Uncomment this line to install global node packages. +# RUN su vscode -c "source /usr/local/share/nvm/nvm.sh && npm install -g " 2>&1 diff --git a/.devcontainer/devcontainer.json b/.devcontainer/devcontainer.json new file mode 100644 index 00000000..5e561363 --- /dev/null +++ b/.devcontainer/devcontainer.json @@ -0,0 +1,35 @@ +// For format details, see https://aka.ms/devcontainer.json. For config options, see the README at: +// https://github.com/microsoft/vscode-dev-containers/tree/v0.224.2/containers/jekyll +{ + "name": "Just the docs", + "build": { + "dockerfile": "Dockerfile", + "args": { + // Update 'VARIANT' to pick a Debian OS version: bullseye, buster + // Use bullseye when on local arm64/Apple Silicon. + "VARIANT": "bullseye", + // Enable Node.js: pick the latest LTS version + "NODE_VERSION": "lts/*" + } + }, + + // Set *default* container specific settings.json values on container create. + "settings": {}, + + // Add the IDs of extensions you want installed when the container is created. + "extensions": ["GitHub.vscode-pull-request-github"], + + // Use 'forwardPorts' to make a list of ports inside the container available locally. + "forwardPorts": [ + // Jekyll server + 4000, + // Live reload server + 35729 + ], + + // Use 'postCreateCommand' to run commands after the container is created. + "postCreateCommand": "sh .devcontainer/post-create.sh", + + // Comment out to connect as root instead. More info: https://aka.ms/vscode-remote/containers/non-root. + "remoteUser": "vscode" +} diff --git a/.devcontainer/post-create.sh b/.devcontainer/post-create.sh new file mode 100644 index 00000000..8c25f3d5 --- /dev/null +++ b/.devcontainer/post-create.sh @@ -0,0 +1,12 @@ +#!/bin/sh + +# Install the version of Bundler. +if [ -f Gemfile.lock ] && grep "BUNDLED WITH" Gemfile.lock > /dev/null; then + cat Gemfile.lock | tail -n 2 | grep -C2 "BUNDLED WITH" | tail -n 1 | xargs gem install bundler -v +fi + +# If there's a Gemfile, then run `bundle install` +# It's assumed that the Gemfile will install Jekyll too +if [ -f Gemfile ]; then + bundle install +fi diff --git a/.gitignore b/.gitignore index bf811d95..9bb8d6b9 100644 --- a/.gitignore +++ b/.gitignore @@ -1,5 +1,10 @@ -# Copied from https://github.com/github/gitignore/blob/main/Jekyll.gitignore -# Ignore metadata generated by Jekyll +# Not sure what a .gitignore is? +# See: https://git-scm.com/docs/gitignore + +# The first files are directly copied from Jekyll's first-party docs on `.gitignore` files: +# https://jekyllrb.com/tutorials/using-jekyll-with-bundler/#commit-to-source-control + +# Ignore the default location of the built site, and caches and metadata generated by Jekyll _site/ .sass-cache/ .jekyll-cache/ @@ -7,12 +12,25 @@ _site/ # Ignore folders generated by Bundler .bundle/ -# vendor/ +vendor/ + +# These next files are used by Just the Docs developers. They are not necessary for end users of the theme, only developers. -# Ignore local settings -/.vscode +# We use Stylelint and Prettier, JavaScript tools, to lint and format our own code. +# We use Node.js as our runtime, so we ignore node_modules +node_modules + +# .DS_Store is a macOS-only metadata file about directories. Convention is to not commit them. +# See: https://en.wikipedia.org/wiki/.DS_Store .DS_Store +# These are legacy globs that typically target Ruby theme developers. We may change these at a later date. +*.gem +.bundle +.ruby-version + +.vscode + # Ignore locally-generated dictionary files /_archived /beta/hotfix diff --git a/Gemfile b/Gemfile index 0c4ab725..2efcd0ec 100644 --- a/Gemfile +++ b/Gemfile @@ -1,11 +1,8 @@ -source 'https://rubygems.org' +source "https://rubygems.org" +gemspec -gem "jekyll", "~> 4.3" # installed by `gem jekyll` -# gem "webrick" # required when using Ruby >= 3 and Jekyll <= 4.2.2 +gem "jekyll-github-metadata", ">= 2.15" -# gem "just-the-docs", "0.5.0" # pinned to the current release -gem "just-the-docs" # always download the latest release +gem "jekyll-include-cache", group: :jekyll_plugins -gem "webrick", "~> 1.7" - -gem "liquid", "4.0.4" +gem "html-proofer", "~> 5.0", :group => :development \ No newline at end of file diff --git a/Gemfile.lock b/Gemfile.lock index 12d44d14..02248379 100644 --- a/Gemfile.lock +++ b/Gemfile.lock @@ -1,23 +1,63 @@ +PATH + remote: . + specs: + just-the-docs (0.8.1) + jekyll (>= 3.8.5) + jekyll-include-cache + jekyll-seo-tag (>= 2.0) + rake (>= 12.3.1) + GEM remote: https://rubygems.org/ specs: + Ascii85 (1.1.0) addressable (2.8.6) public_suffix (>= 2.0.2, < 6.0) + afm (0.2.2) + async (2.9.0) + console (~> 1.10) + fiber-annotation + io-event (~> 1.5, >= 1.5.1) + timers (~> 4.1) + bigdecimal (3.1.6) colorator (1.1.0) concurrent-ruby (1.2.2) + console (1.23.5) + fiber-annotation + fiber-local + json em-websocket (0.5.3) eventmachine (>= 0.12.9) http_parser.rb (~> 0) + ethon (0.16.0) + ffi (>= 1.15.0) eventmachine (1.2.7) + faraday (2.9.0) + faraday-net_http (>= 2.0, < 3.2) + faraday-net_http (3.1.0) + net-http ffi (1.16.3) ffi (1.16.3-x64-mingw-ucrt) + fiber-annotation (0.2.0) + fiber-local (1.0.0) forwardable-extended (2.6.0) google-protobuf (3.25.1-arm64-darwin) google-protobuf (3.25.1-x64-mingw-ucrt) google-protobuf (3.25.1-x86_64-linux) + hashery (2.1.2) + html-proofer (5.0.8) + addressable (~> 2.3) + async (~> 2.1) + nokogiri (~> 1.13) + pdf-reader (~> 2.11) + rainbow (~> 3.0) + typhoeus (~> 1.3) + yell (~> 2.0) + zeitwerk (~> 2.5) http_parser.rb (0.8.0) i18n (1.14.1) concurrent-ruby (~> 1.0) + io-event (1.5.1) jekyll (4.3.3) addressable (~> 2.4) colorator (~> 1.0) @@ -34,6 +74,9 @@ GEM safe_yaml (~> 1.0) terminal-table (>= 1.8, < 4.0) webrick (~> 1.7) + jekyll-github-metadata (2.16.1) + jekyll (>= 3.4, < 5.0) + octokit (>= 4, < 7, != 4.4.0) jekyll-include-cache (0.2.1) jekyll (>= 3.7, < 5.0) jekyll-sass-converter (3.0.0) @@ -42,11 +85,7 @@ GEM jekyll (>= 3.8, < 5.0) jekyll-watch (2.2.1) listen (~> 3.0) - just-the-docs (0.8.1) - jekyll (>= 3.8.5) - jekyll-include-cache - jekyll-seo-tag (>= 2.0) - rake (>= 12.3.1) + json (2.7.1) kramdown (2.4.0) rexml kramdown-parser-gfm (1.1.0) @@ -56,15 +95,35 @@ GEM rb-fsevent (~> 0.10, >= 0.10.3) rb-inotify (~> 0.9, >= 0.9.10) mercenary (0.4.0) + net-http (0.4.1) + uri + nokogiri (1.16.2-arm64-darwin) + racc (~> 1.4) + nokogiri (1.16.2-x64-mingw-ucrt) + racc (~> 1.4) + nokogiri (1.16.2-x86_64-linux) + racc (~> 1.4) + octokit (6.1.1) + faraday (>= 1, < 3) + sawyer (~> 0.9) pathutil (0.16.2) forwardable-extended (~> 2.6) + pdf-reader (2.12.0) + Ascii85 (~> 1.0) + afm (~> 0.2.1) + hashery (~> 2.0) + ruby-rc4 + ttfunk public_suffix (5.0.4) + racc (1.7.3) + rainbow (3.1.1) rake (13.1.0) rb-fsevent (0.11.2) rb-inotify (0.10.1) ffi (~> 1.0) rexml (3.2.6) rouge (4.2.0) + ruby-rc4 (0.1.5) safe_yaml (1.0.5) sass-embedded (1.71.1-arm64-darwin) google-protobuf (~> 3.25) @@ -72,10 +131,21 @@ GEM google-protobuf (~> 3.25) sass-embedded (1.71.1-x86_64-linux) google-protobuf (~> 3.25) + sawyer (0.9.2) + addressable (>= 2.3.5) + faraday (>= 0.17.3, < 3) terminal-table (3.0.2) unicode-display_width (>= 1.1.1, < 3) + timers (4.3.5) + ttfunk (1.8.0) + bigdecimal (~> 3.1) + typhoeus (1.4.1) + ethon (>= 0.9.0) unicode-display_width (2.5.0) + uri (0.13.0) webrick (1.8.1) + yell (2.2.2) + zeitwerk (2.6.13) PLATFORMS arm64-darwin @@ -83,10 +153,11 @@ PLATFORMS x86_64-linux DEPENDENCIES - jekyll (~> 4.3) - just-the-docs - liquid (= 4.0.4) - webrick (~> 1.7) + bundler (>= 2.3.5) + html-proofer (~> 5.0) + jekyll-github-metadata (>= 2.15) + jekyll-include-cache + just-the-docs! BUNDLED WITH 2.4.13 diff --git a/_includes/components/breadcrumbs.html b/_includes/components/breadcrumbs.html index f1bc4885..8668791b 100644 --- a/_includes/components/breadcrumbs.html +++ b/_includes/components/breadcrumbs.html @@ -1,15 +1,144 @@ -{% unless page.url == "/" %} - {% if page.parent %} - - {% endif %} -{% endunless %} +{%- comment -%} + Include as: {%- include components/breadcrumbs.html -%} + Depends on: page, site. + Results in: HTML for the breadcrumbs component. + Overwrites: + node, pages_list, parent_page, grandparent_page. +{%- endcomment -%} + +{%- if page.url != "/" and page.parent -%} + +{%- capture nav_list_link -%} + +{%- endcapture -%} + +{%- capture site_nav -%} +{%- include_cached components/site_nav.html -%} +{%- endcapture -%} + +{%- if site_nav contains nav_list_link -%} + + {%- capture nav_list_simple -%} + "s requires that number + of potential ancestors to be popped from the stack. + + The number of occurrences of a string in nav_split_next is computed by removing + them all, then dividing the resulting size difference by the length of the string. + {%- endcomment %} + + {%- assign nav_breadcrumbs = "" | split: "" -%} + + {%- for nav_split in nav_anchor_splits -%} + {%- unless forloop.last -%} + + {%- assign nav_split_next = nav_anchor_splits[forloop.index] | strip -%} + + {%- assign nav_split_test = + nav_split_next | remove_first: nav_list_simple | prepend: nav_list_simple -%} + {%- if nav_split_test == nav_split_next -%} + {%- assign nav_breadcrumb_link = + nav_split | split: "" | append: "" -%} + {%- assign nav_breadcrumbs = nav_breadcrumbs | push: nav_breadcrumb_link -%} + {%- endif -%} + + {%- if nav_split_next contains "" -%} + {%- assign nav_list_end_less = nav_split_next | remove: "" -%} + {%- assign nav_list_end_count = + nav_split_next.size | minus: nav_list_end_less.size | divided_by: 5 -%} + {% for nav_end_index in (1..nav_list_end_count) %} + {%- assign nav_breadcrumbs = nav_breadcrumbs | pop -%} + {%- endfor -%} + {%- endif -%} + + {%- endunless -%} + {%- endfor -%} + + {%- assign nav_parent_link = nav_breadcrumbs[-1] -%} + {%- assign nav_grandparent_link = nav_breadcrumbs[-2] -%} + +{%- else -%} + + {%- comment -%} + Pages whose links are excluded from the main navigation may still have + breadcrumbs. Determining them appears to require inspecting the front matter + of all the pages in the same group. For sites with 100s of pages, this is too + inefficient in Jekyll 3 (also when the for-loop is replaced by where-filters). + {%- endcomment -%} + + {%- assign pages_list = site[page.collection] | default: site.html_pages -%} + + {%- assign parent_page = nil -%} + {%- assign grandparent_page = nil -%} + + {%- for node in pages_list -%} + + {%- if node.has_children and page.grand_parent -%} + + {%- if node.title == page.parent and node.parent == page.grand_parent -%} + {%- assign parent_page = node -%} + {%- endif -%} + {%- if node.title == page.grand_parent -%} + {%- assign grandparent_page = node -%} + {%- endif -%} + {%- if parent_page and grandparent_page -%} + {%- break -%} + {%- endif -%} + + {%- elsif node.has_children and node.title == page.parent and node.parent == nil -%} + + {%- assign parent_page = node -%} + {%- break -%} + + {%- endif -%} + + {%- endfor -%} + + {%- capture nav_parent_link -%} + {{ page.parent }} + {%- endcapture -%} + + {%- if page.grand_parent %} + {%- capture nav_grandparent_link -%} + {{ page.grand_parent }} + {%- endcapture -%} + {%- endif -%} + +{%- endif -%} + + + +{%- endif -%} diff --git a/_includes/components/children_nav.html b/_includes/components/children_nav.html index e76f98d1..ce2482a8 100644 --- a/_includes/components/children_nav.html +++ b/_includes/components/children_nav.html @@ -1,9 +1,33 @@ +{%- comment -%} + Include as: {%- include components/children_nav.html -%} + Depends on: page, site. + Results in: HTML for the children-navigation component. + Includes: + sorted_pages.html + toc_heading_custom.html + Overwrites: + child_pages. +{%- endcomment -%} + +{%- if page.has_children == true and page.has_toc != false -%} + {%- assign child_pages = site[page.collection] + | default: site.html_pages + | where: "parent", page.title + | where: "grand_parent", page.parent -%} + + {%- include sorted_pages.html pages = child_pages -%} + + {%- if page.child_nav_order == 'desc' or page.child_nav_order == 'reversed' -%} + {%- assign sorted_pages = sorted_pages | reverse -%} + {%- endif -%} +{%- endif -%} +
{% include toc_heading_custom.html %}
    - {% for child in include.toc_list %} -
  • - {{ child.title }}{% if child.summary %} - {{ child.summary }}{% endif %} -
    • - {% endfor %} +{% for child in sorted_pages %} +
  • + {{ child.title }}{% if child.summary %} - {{ child.summary }}{% endif %} +
    • +{% endfor %}
diff --git a/_includes/components/nav.html b/_includes/components/nav.html new file mode 100644 index 00000000..aa5af38d --- /dev/null +++ b/_includes/components/nav.html @@ -0,0 +1,75 @@ +{%- comment -%} + Include as: {%- include components/nav.html pages=pages -%} + Depends on: include.pages. + Results in: HTML for the navigation panel. + Includes: + sorted_pages.html + Overwrites: + nav_pages, first_level_pages, second_level_pages, third_level_pages, + node, children_list, child, grand_children_list, grand_child. +{%- endcomment -%} + +{%- assign nav_pages = include.pages + | where_exp: "item", "item.title != nil" + | where_exp: "item", "item.nav_exclude != true" -%} + +{%- include sorted_pages.html pages = nav_pages -%} + +{%- comment -%} + It might be more efficient to sort the pages at each level separately. +{%- endcomment -%} + +{%- assign first_level_pages = sorted_pages + | where_exp: "item", "item.parent == nil" -%} +{%- assign second_level_pages = sorted_pages + | where_exp: "item", "item.parent != nil" + | where_exp: "item", "item.grand_parent == nil" -%} +{%- assign third_level_pages = sorted_pages + | where_exp: "item", "item.grand_parent != nil" -%} + +
    +{%- for node in first_level_pages -%} +
  • + {%- if node.has_children -%} + + {%- endif -%} + {{ node.title }} + {%- if node.has_children -%} + {%- assign children_list = second_level_pages + | where: "parent", node.title -%} + {%- if node.child_nav_order == 'desc' or node.child_nav_order == 'reversed' -%} + {%- assign children_list = children_list | reverse -%} + {%- endif -%} +
      + {%- for child in children_list -%} +
    • + {%- if child.has_children -%} + + {%- endif -%} + {{ child.title }} + {%- if child.has_children -%} + {%- assign grand_children_list = third_level_pages + | where: "parent", child.title + | where: "grand_parent", node.title -%} + {%- if child.child_nav_order == 'desc' or child.child_nav_order == 'reversed' -%} + {%- assign grand_children_list = grand_children_list | reverse -%} + {%- endif -%} + + {%- endif -%} +
      • + {%- endfor -%} +
    + {%- endif -%} +
    • +{%- endfor -%} +
diff --git a/_includes/components/search_footer.html b/_includes/components/search_footer.html index fb4fe51b..d448fdb2 100644 --- a/_includes/components/search_footer.html +++ b/_includes/components/search_footer.html @@ -1,7 +1,7 @@ {% if site.search.button %} - - - + {% endif %}
diff --git a/_includes/components/search_header.html b/_includes/components/search_header.html index 98425d5b..35621241 100644 --- a/_includes/components/search_header.html +++ b/_includes/components/search_header.html @@ -1,6 +1,6 @@ {% capture search_placeholder %}{% include search_placeholder_custom.html %}{% endcapture %} -
+