asciidocsy 0.3.0.pre.rc1

data/_docs/topics/toolchain.adoc

@@ -0,0 +1,79 @@
+:page-permalink: /docs/theme/toolchain
+= AsciiDocsy Toolchain
+include::{path_to_readme}[tags="globals"]
+
+Like any theme, AsciiDocsy can be modified to accommodate an assortment of components.
+In fact, AsciiDocsy mainly _is_ an assortment of components.
+Here are the ones I have chosen, after building numerous Jekyll/AsciiDoc sites across more than five years.
+
+[NOTE]
+Neither AcsiiDocsy nor its author have any financial stake in these tooling choices.
+They are all free and open-source of freemium and OS-friendly.
+They can all be replaced by competent alternatives, but these are my sincere favorites.
+
+== Asciidoctor and Jekyll-AsciiDoc
+
+If you're working in AsciiDoc, which is _the_ choice for serious technical documentation projects (including books), you're working with Asciidoctor.
+link:https://www.asciidoctor.org[Asciidoctor] has a terrific, growing community.
+The organization provides all kinds of converters and related tools for numerous environments, and Ascsiidoctor maintains the link:https://github.com/asciidoctor/jekyll-asciidoc[jekyll-asciidoc] plugin as a top-notch Ruby gem.
+
+== Bootstrap
+
+Every good website has an HTML/CSS/JS framework, and like millions of others, for AsciiDocsy that framework is Twitter's link:https://getbootstrap.com[Bootstrap library].
+Sure, some components wind up looking commonplace, but the convenience and consistency of Bootstrap makes it easy to resist -- especially because it's so easy to modify, extend, and disguise.
+
+At this time, AsciiDocsy uses link:https://getbootstrap.com/docs/4.3/getting-started/introduction/[Bootstrap version 4.3], but we will probably upgrade to link:https://getbootstrap.com/docs/5.0/getting-started/introduction/[version 5] before long.
+
+== Highlight.js
+
+For code-block syntax hiding, there are several options.
+Asciidoctor does a good job of laying out the link:https://docs.asciidoctor.org/asciidoctor/latest/syntax-highlighting/[four highlighters] it comes ready to handle.
+
+AsciiDocsy enables both Rouge and Highlight.js.
+Highlight.js is not available for PDFs, so Rouge is a better fit there.
+
+Highlight.js is the choice for the AsciiDocsy site itself largely because Hjs provides syntax highlighting for AsciiDoc source itself, and Rouge as of yet does not.
+
+== Navgoco Menu
+
+I have tried a lot of collapsing/multi-tiered menu components, but I always come back to link:https://github.com/tefra/navgoco[Navgoco].
+It is simple and applies elegantly to a conventional HTML structure (normal unordered lists).
+It collapses and nests, if you want it to, and it's easy to style.
+
+I would not mind extending this menu system a bit, but I need more concrete direction.
+Something to discuss in the link:{theme_source_www}/issues[Issues], perhaps?
+
+== Bootstrap TOC
+
+There are several ways to implement scrollspy-capable tables of contents, but this is my new favorite.
+The nested levels make it perfect for long documents, where other such TOCs often force you to scroll the TOC itself.
+I just love this little component.
+
+== Netlify CI/CD/Hosting
+
+link:https://www.netlify.com[Netlify] makes continuous integration and deployment a relative breeze.
+It's free to tinker with, and even for modestly sized production sites.
+They also accommodate enterprise-scale needs.
+
+Niche turnkey CI/CD platforms (in this case, for publishing) have great potential to save hundreds and hundreds of IT/DevOps hours every year.
+Others prefer to handle this aspect in-house, if they have the resources.
+
+== Algolia Search
+
+link:https://www.algolia.com[Algolia] provides the cloud platform that the AsciiDocsy indexes to and queries from.
+It also provides a widget framework for building great search apps.
+
+Unlike hosting, this is almost certainly a nut no organization wants to crack in-house, as search algorithms are proprietary.
+You are going to pay for good search -- my clients get good results and a good value from Algolia.
+
+I believe all of the clients I have put on Algolia have kept it as their needs have grown.
+
+.Goodbye Lunr Search
+****
+Although I have never used it in production, I have always been rather fond of Lunr, the JavaScript-only search engine that comes set up by default on most Jekyll and other SSG themes.
+It's a work of wonder, but alas, good search is not a client-side production, and Lunr has some bugs that are nearly inherent, and therefore unsolvable, to my understanding.
+
+I decided to rip it out of the Docsy Jekyll code I started out with.
+It's probably sufficient for blog searches, but I cannot fathom a serious product documentation site using it.
+If people would strongly prefer Lunr, I will add it back in as an option so search works out of the box.
+****

data/_docs/topics/upgrade-0-3-0.adoc

@@ -0,0 +1,49 @@
+:page-permalink: /docs/theme/setup/upgrade-0-3-0
+include::{path_to_readme}[tags="globals"]
+= Upgrading to AsciiDocsy v0.3.0
+
+As of AsciiDocsy v0.3.0, the whole theme ships as a proper Ruby gem.
+Jekyll handles gemified themes differently than collocated themes.
+
+The latter type, as with AsciiDocsy prior to 0.3.0, means storing all core theme files locally.
+With a gemified theme, you only store alternate files locally, for overwriting core theme files.
+
+In order to release AsciiDocsy as a conventionally structured Jekyll theme plugin, I made changes that may necessitate some reorganizing if you wish to upgrade from a prior release.
+
+With a few small adjustments, you should be able to serve exactly the same site using the new gem-based theme.
+
+[NOTE]
+No significant front-end or back-end feature changes were made for the 0.3.0 release, other than the major repackaging alterations.
+It should generate HTML in an identical fashion, and the newly organized styles should match up 1:1.
+
+== Alterations
+
+Here are the major changes:
+
+. Assets moved to `assets/` directory.
+* `css/`, `images/`, `js/`, and `fonts/` all moved.
+* `_includes/` and `_layouts/` stayed in root path.
+
+. Bootstrap and AsciiDocsy styles are now sourced as Sass.
+* New `_sass/` directory contains dynamic CSS source.
+* New files `assets/css/bootstrap.scss` and `assets/css/asciidocsy.scss` define compiling of Sass source.
+
+. AsciiDocsy's own docs content has moved around a bit.
+* The strings `theme_` and `style_` prepended to filenames in `_docs/topics/` have been removed.
+* Files from `_docs/topics/` that were labeled with `style_` and displayed under the Style Guides domain have been moved to the new link:{theme_docs_repo_www}[AsciiDocsy Docs repo].
+
+. Dependency definitions are included in gem specification.
++
+--
+* Theme-specific dependencies like jekyll-liquify, jekyll-asciidoc will be imported automatically.
+--
++
+[NOTE]
+We still advise including `jekyll` gem explicitly in your application's Gemfile.
+
+== Using AsciiDocsy 0.3.0
+
+It's easier than ever to add AsciiDocsy to your theme!
+Use any of the link:https://jekyllrb.com/docs/themes/#installing-a-theme[methods Jekyll provides].
+
+See the link:{theme_docs_repo_www}/blob/main/Gemfile[Gemfile in the AsciiDocsy Docs repo] for exemplary usage.

data/_includes/_settings.liquid

@@ -0,0 +1,2 @@
+{% capture images_url %}{% unless site.baseurl == "" %}/{{ site.baseurl }}{% endunless %}/{{ site.assets_url }}/images{% endcapture %}
+{% capture styles_url %}{% unless site.baseurl == "" %}/{{ site.baseurl }}{% endunless %}/{{ site.assets_url }}/css{% endcapture %}

data/_includes/_variables.sass

@@ -0,0 +1,12 @@
+// customize Sass variables here
+$primary:         {{ site.data.theme.styles.color.theme-primary }};
+// $secondary:       {{ site.data.theme.styles.color.theme-secondary }};
+// $success:    ;
+// $info:       ;
+// $warning:    ;
+// $danger:     ;
+// $light:      ;
+// $dark:       ;
+$example-block-bg: #e6f0f5;
+$font-size-base: 1rem;
+$font-size-para: $font-size-base;

data/_includes/breadcrumbs.html

@@ -0,0 +1,20 @@
+<!-- {% comment %}
+Generates a "breadcrumb trail" of parent categories.
+Defined by:
+  `breadcrumbs` object of `site.data.manifest.breadcrumbs`
+  `breadcrumbs` object in the Jekyll configuration path
+{% endcomment %} -->
+{% assign crumbs = page.url | remove:'/index.html' | split: '/' %}
+{% assign delim = site.data.navs.breadcrumbs.show.opts.delim | default: "/" %}
+<div id="breadcrumbs">
+<a href="/">{{ site.data.navs.breadcrumbs.show.home | default: "Home" }}</a>
+{% for crumb in crumbs offset: 1 %}
+  {% if forloop.last %}
+    {{delim}} {{ page.title }}
+  {% else %}
+    {% assign crumb_default = crumb | replace:'-',' ' | remove:'.html' | capitalize %}
+    {% assign crumb_qry = site.data.manifest.breadcrumbs | where: "slug",crumb %}
+    {{delim}} <a href="{% assign crumb_limit = forloop.index | plus: 1 %}{% for crumb in crumbs limit: crumb_limit %}{{ crumb | append: '/' }}{% endfor %}">{{ crumb_qry[0]['text'] | default: crumb_default }}</a>
+  {% endif %}
+{% endfor %}
+</div>

data/_includes/breadcrumbs_alt.html

@@ -0,0 +1,6 @@
+<!-- {% comment %}
+Experimental file for testing novel extension/hook method.
+{% endcomment %} -->
+<div id="breadcrumbs">
+BREADCRUMBS ALT HOOK
+</div>

data/_includes/config-api-objects.asciidoc

@@ -0,0 +1,23 @@
+{% include string-eval.liquid string=include.key_str %}
+{% for obj in data_obj %}
+  {% capture obj_str %}{{ include.key_str }}.{{ obj[0] }}{% endcapture %}
+  {% unless obj[1]['$doc'] == 'none' %}
+  {% if obj[1] and obj[0] != '$doc' %}
+    {% assign docs = obj[1]['$doc'] %}
+    {% assign name_def = obj[0] | capitalize %}
+    {% assign obj_name = docs.name | default: name_def %}
+
+=== {{ obj_name }}
+
+[big]`{{ obj_str }}`
+    {% if docs %}
+      {% if docs.desc %}
+{{ docs.desc }}
+      {% endif %}
+      {% if docs.args.size > 0 %}
+{% include config-api-properties.asciidoc base=obj_str args=docs.args %}
+      {% endif %}
+    {% endif %}
+  {% endif %}
+  {% endunless %}
+{% endfor %}

data/_includes/config-api-properties.asciidoc

@@ -0,0 +1,29 @@
+{% if include.args.size > 0 %}
+[discrete]
+==== Properties
+
+[.api-object-properties]
+--
+  {% for arg in include.args %}
+    {% assign arg_key = arg[0] | replace: "_","." %}
+    {% capture prop_key %}{{ include.base }}.{{ arg_key }}{% endcapture %}
+
+[discrete]
+===== `{{ prop_key }}`
+
+[horizontal]
+    {%- if arg[1].desc %}
+usage:: {{ arg[1].desc }}
+    {%- endif %}
+    {%- if arg[1].type %}
+type:: {{ arg[1].type }}
+    {%- endif %}
+{%- include string-eval.liquid string=prop_key %}
+    {%- if data_obj %}
+default:: `{{ data_obj }}`
+    {% endif %}
+  {% endfor %}
+--
+{% else %}
+No properties found.
+{% endif %}

data/_includes/config-api.asciidoc

@@ -0,0 +1,29 @@
+[.api-reference]
+{% for cat in site.data.theme %}
+  {% assign catkey = cat[0] %}
+  {% capture catkey_str %}site.data.theme.{{ catkey }}{% endcapture %}
+  {% if cat[1]['$doc'] %}
+    {% assign doc = cat[1]['$doc'] %}
+    {% unless doc.skip %}
+== {{catkey | replace: "-"," " | upcase}}
+
+[big]`{{ catkey_str }}`
+      {% if doc.desc %}
+{{ doc.desc }}
+      {% endif %}
+{% include config-api-objects.asciidoc key_str=catkey_str %}
+    {% else %}
+      {% for subcat in site.data.theme[catkey] %}
+        {% unless subcat[0] == "$doc" %}
+          {% assign subkey = subcat[0] %}
+          {% capture subkey_str %}{{ catkey_str }}.{{ subkey }}{% endcapture %}
+== {{catkey | replace: "-"," " | upcase}}: {{ subkey | upcase }}
+
+[big]`{{ subkey_str }}`
+
+{% include config-api-objects.asciidoc key_str=subkey_str %}
+        {% endunless %}
+      {% endfor %}
+    {% endunless %}
+  {% endif %}
+{% endfor %}

data/_includes/feedback.html

@@ -0,0 +1,59 @@
+<!-- feedback form {% comment %}
+Generates feedback form.
+{% endcomment %} -->
+{% if site.data.theme.forms.feedback-form %}
+{% assign fform = site.data.theme.forms.feedback-form %}
+<style>
+  .feedback--answer {
+    display: inline-block;
+  }
+  .feedback--response {
+    display: none;
+    margin-top: 1em;
+  }
+  .feedback--response__visible {
+    display: block;
+  }
+</style>
+<div class="jumbotron col-sm-4">
+<i class="icon {{ fform.show.icon }} fa-4x float-right" style="margin-top: .5em;"></i>
+<div class="h5">{{ fform.show.name }}</div>
+<p class="feedback--question">{{ fform.show.text }}</p>
+<form name="feedback" method="POST" data-netlify="true">
+{% for opt in fform.send.opts %}
+  <button type="button" class="btn btn-sm btn-{{opt.color | default:'secondary'}} feedback--answer feedback--answer-{{ opt.slug }}">{{ opt.text }}</button>
+{% endfor %}
+</form>
+</div>
+<div class="feedback--response feedback--response-{{ opt.slug }}"></div>
+<script>
+  {% for opt in fform.send.opts %}
+  const {{opt.slug}}Button = document.querySelector('.feedback--answer-{{opt.slug}}');
+  const {{opt.slug}}Response = document.querySelector('.feedback--response-{{opt.slug}}');
+  {% endfor %}
+  const disableButtons = () => {
+    {% for opt in fform.send.opts %}
+    {{opt.slug}}Button.disabled = true;
+    {% endfor %}
+  };
+  const sendFeedback = (value) => {
+    if (typeof ga !== 'function') return;
+    const args = {
+      command: 'send',
+      hitType: 'event',
+      category: 'Helpful',
+      action: 'click',
+      label: window.location.pathname,
+      value: value
+    };
+    ga(args.command, args.hitType, args.category, args.action, args.label, args.value);
+  };
+  {% for opt in fform.send.opts %}
+  {{opt.slug}}Button.addEventListener('click', () => {
+    {{opt.slug}}Response.classList.add('feedback--response__visible');
+    disableButtons();
+    sendFeedback(1);
+  });
+  {% endfor %}
+</script>
+{% endif %}

data/_includes/footer-links_sup.html

@@ -0,0 +1,5 @@
+{% comment %}
+Experimental extension method.
+Established in _data/extensions.yml
+{% endcomment %}
+{% assign alt_links = site.data.stack %}

data/_includes/footer.html

@@ -0,0 +1,59 @@
+{% assign footer_config = site.data.theme.blocks.page-footer %}
+{% assign footer_nav    = site.data.navs.footer %}
+{% assign footer_str    = site.data.theme.strings.footer %}
+{% comment %}var alt_links set by hook{% endcomment %}
+{% include hook.liquid template="footer_html" spot="head" %}
+<footer class="{{ footer_config.show.opts.class | default: 'row flex-xl-nowrap' }}"><!-- COMPANY REF/NAV -->
+  <div class="container-fluid">
+    <div class="row">
+      <div class="col-md-4">
+  {% if footer_config.show.logo %}
+        <span class="company-logo">
+          <img src="{{ footer_config.show.logo.source | liquify }}" class="logo" width="{{ footer_config.show.logo.width | default: '100px' }}">
+        </span>
+  {% endif %}
+  {% if footer_str.title %}
+        <div class="footer-title h4">{{ footer_str.title }}</div>
+  {% endif %}
+  {% if footer_str.tagline %}
+        <div class="footer-title h5">{{ footer_str.tagline }}</div>
+  {% endif %}
+  {% if site.data.theme.blocks.social.show.spot == "footer" %}
+        {% include social-links.html list-class="list-inline" %}
+  {% endif %}
+      </div>
+{% for col in footer_nav.columns %}
+  {% assign col_class = "" %}
+  {% if forloop.index == 1 %}
+    {% assign col_offset = 5 | minus: forloop.length %}
+    {% assign col_class = "offset-" | append: col_offset %}
+  {% endif %}
+  <div class="col-md-2 {{ col_class }}">
+    <ul class="list-unstyled">
+      <li class="footer-heading h5">{{ col.text }}</li>
+  {% for link in col.kids %}
+    {% assign link_ref = alt_links | where: "app",link.text | first %}
+      <li><a href="{{ link_ref.url | default: link.href | default: '#' }}" data-toggle="tooltip" title="{{ link_ref.use | default: link.text }}">{{ link.text }}</a></li>
+  {% endfor %}
+    </ul>
+  </div>
+{% endfor %}
+  </div>
+  {% if footer_str.copyright or footer_str.madewith %}
+  <div class="row justify-content-md-center">
+    <div class="footer-strings col-md-8 text-center">
+    {% if footer_str.copyright %}
+      <div class="copyright">
+        <p>{{ footer_str.copyright | asciidocify }}</p>
+      </div>
+    {% endif %}
+    {% if footer_str.madewith %}
+      <div class="madewith">
+        <p>{{ footer_str.madewith | asciidocify }}</p>
+      </div>
+    {% endif %}
+    </div>
+  </div>
+  {% endif %}
+  {% include hook.liquid template="footer_html" spot="tail" %}
+</footer>

data/_includes/gdpr-message.html

@@ -0,0 +1,41 @@
+{% assign alert = site.features.alerts.gdpr-message %}
+{% assign actions = site.features.actions.gdpr-alert %}
+<script>
+$.gdprcookie.init({
+  cookieTypes: [
+    {% for type in actions.pick.opts  %}
+    {
+      type: "{{ type.name }}",
+      value: "{{ type.slug }}",
+      description: "{{ type.desc }}"
+    }{% unless forloop.index == actions.picks.opts.size %},{% endunless %}
+    {% endfor %}
+  ],
+  title: "{{ alert.name }}",
+  subtitle: "{{ alert.show.line }}",
+  message: "{{ alert.show.text }}",
+  delay: 2000, // delay in milliseconds
+  expires: 30, // expiration <a href="https://www.jqueryscript.net/time-clock/">date</a>
+  cookieName: "cookieControlPrefs",
+  acceptReload: false,
+  acceptBtnLabel: "{{ action.sign.text }}",
+  advancedBtnLabel: "{{ action.pick.text }}",
+  customShowMessage: undefined,
+  customHideMessage: undefined,
+  customShowChecks: undefined
+});
+
+$.gdprcookie.display()
+
+$(document.body)
+.on("gdpr:show", function() {
+    console.log("Cookie dialog is shown");
+})
+.on("gdpr:accept", function() {
+    var preferences = $.gdprcookie.preference();
+    console.log("Preferences saved:", preferences);
+})
+.on("gdpr:advanced", function() {
+    console.log("Advanced button was pressed");
+});
+</script>

data/_includes/google-analytics.html

@@ -0,0 +1,11 @@
+{% if site.services.analytics.google %}
+<script async src='https://www.google-analytics.com/analytics.js'></script>
+<script type="application/javascript">
+var doNotTrack = false;
+if (!doNotTrack) {
+	window.ga=window.ga||function(){(ga.q=ga.q||[]).push(arguments)};ga.l=+new Date;
+	ga('create', '{{ site.services.analytics.google }}', 'auto');
+	ga('send', 'pageview');
+}
+</script>
+{% endif %}

data/_includes/head.html

@@ -0,0 +1,74 @@
+{% include _settings.liquid %}
+<head>
+<meta charset="utf-8">
+<!-- Some HTML templates copyright 2019-2021 Vanessa Sochat | Apache 2.0 License -->
+<!-- Adapted and re-released as AsciiDocsy under Apache 2.0 and MIT licenses
+ in 2021 by Codewriting LLC -->
+ {% assign page_url = site.deploy_url | append: page.url %}
+<meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no">
+<meta name="generator" content="Jekyll+Asciidoctor" />
+{% if page.search-index %}
+  {% assign search_index = "index" %}
+{% else %}
+  {% assign search_index = "noindex" %}
+{% endif %}
+<meta name="robots" content="{{ search_index }}, follow">
+{% assign canonical_def = site.canonical_url | append: page.url %}
+<link rel="canonical" href="{{ page.canonical | default: canonical_def }}" />
+<link rel="shortcut icon" href="{{ images_url }}/favicons/favicon.ico" >
+<link rel="icon" type="image/png" href="{{ images_url }}/favicons/favicon-16x16.png" sizes="16x16">
+<link rel="icon" type="image/png" href="{{ images_url }}/favicons/favicon-32x32.png" sizes="32x32">
+<!--
+<link rel="apple-touch-icon" href="{{ images_url }}/favicons/apple-touch-icon-180x180.png" sizes="180x180">
+<link rel="icon" type="image/png" href="{{ images_url }}/favicons/android-36x36.png" sizes="36x36">
+<link rel="icon" type="image/png" href="{{ images_url }}/favicons/android-48x48.png" sizes="48x48">
+<link rel="icon" type="image/png" href="{{ images_url }}/favicons/android-72x72.png" sizes="72x72">
+<link rel="icon" type="image/png" href="{{ images_url }}/favicons/android-96x196.png" sizes="96x196">
+<link rel="icon" type="image/png" href="{{ images_url }}/favicons/android-144x144.png" sizes="144x144">
+<link rel="icon" type="image/png" href="{{ images_url }}/favicons/android-192x192.png" sizes="192x192">
+-->
+
+<title>
+  {% if page.title %}
+    {{ page.title }} |
+  {% endif %}
+  {{ site.title }}
+</title>
+
+<meta property="og:title" content="{% if page.title %}{{ page.title }}{% else %}{{ site.title }}{% endif %}" />
+<meta property="og:description" content="{% if page.description %}{{ page.description }}{% else %}{{ site.description }}{% endif %}" />
+<meta property="og:type" content="website" />
+<meta property="og:url" content="{{ site.url }}" />
+<meta property="og:site_name" content="{{ site.url }}" />
+
+<meta itemprop="name" content="{% if page.title %}{{ page.title }}{% else %}{{ site.title }}{% endif %}">
+<meta itemprop="description" content="{% if page.description %}{{ page.description | strip_html | strip_newlines | truncate: 160 }}{% else %}{{ site.description }}{% endif %}">
+
+{% include hook.liquid template="head_html" spot="css_head" %}
+<link rel="stylesheet" href="{{ styles_url }}/bootstrap.css"/>
+<link rel="stylesheet" href="{{ styles_url }}/bootstrap-toc.css"/>
+<link rel="stylesheet" href="{{ styles_url }}/jquery.navgoco.css"/>
+<link rel="stylesheet" href="{{ styles_url }}/palette.css"/>
+<link rel="stylesheet" href="{{ styles_url }}/asciidoctor.css"/>
+<link rel="stylesheet" href="{{ styles_url }}/font-awesome.css"/>
+<link rel="stylesheet" href="{{ styles_url }}/skins/foundation.css" id="theme-skin"/>
+<link rel="stylesheet" href="{{ styles_url }}/syntax/hljs/a11y-light.css" id="syntax-skin"/>
+{% if site.source-highlighter == "highlight.js" %}
+<link rel="stylesheet" href="{{ styles_url }}/highlight.pack.css"/>
+{% endif %}
+<link rel="stylesheet" type="text/css" href="https://cdn.jsdelivr.net/npm/instantsearch.js@2.10.4/dist/instantsearch-theme-algolia.min.css">
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/instantsearch.css@7.3.1/themes/reset-min.css" integrity="sha256-t2ATOGCtAIZNnzER679jwcFcKYfLlw01gli6F6oszk8=" crossorigin="anonymous"/>
+<link rel="stylesheet" href="{{ styles_url }}/asciidocsy.css"/>
+<link rel="stylesheet" href="{{ styles_url }}/custom.css"/>
+{% include hook.liquid template="head_html" spot="css_tail" %}
+
+{% assign empty_array = "" | split: "," %}
+{% assign page_scripts = page.scripts | default: layout.scripts %}
+{% assign all_scripts = site.data.theme.scripts %}
+{% include scripts.html spot="head" %}
+<script>
+// invoke highligher.js
+hljs.highlightAll();
+</script>
+{% include hook.liquid template="head_html" spot="tail" %}
+</head>

data/_includes/header.html

@@ -0,0 +1,22 @@
+<header><!-- DOCSITE REF/NAV -->
+  <nav id="nav-site" class="js-navbar-scroll navbar navbar-expand navbar-dark flex-column flex-md-row td-navbar td-navbar-{{ site.data.theme.styles.nav-site.position | default: 'fixed' }}">
+    <a class="navbar-brand" href="/{{ site.baseurl }}">
+      <span class="navbar-logo"></span>
+      <img src="{{ site.data.theme.blocks.header.show.logo.source }}" class="logo" width="{{ site.data.theme.blocks.header.show.logo.width | default: '50px' }}">
+       <span class="site-title">{{ site.name }}</span>
+	  </a>
+  	<div class="td-navbar-nav-scroll ml-md-auto align-content-end" id="navbarNavDropdown">
+      {% include nav-site.html %}
+  	</div>
+    {% if site.data.theme.search.site.show.spot == "#nav-site" %}
+      {% include search-form.html search="site" %}
+    {% endif %}
+    {% if site.source_www %}
+  	<div class="navbar-nav d-none d-lg-block">
+      <a class="nav-link" href="{{ site.source_www }}" target="_blank">
+        <i class="icon fab {{ site.source_icon | default: 'fa-code-fork' }} fa-2x"></i>
+      </a>
+    </div>
+    {% endif %}
+  </nav>
+</header>

data/_includes/hook.liquid

@@ -0,0 +1,26 @@
+{% comment %}
+Inserts the data-designated template into calling template at `spot`...
+ REPLACES WHOLE template (if spot == 'file' & calling template is conditional)
+{% endcomment %}
+{% assign hook_replace_tpl = false %}
+{% assign spot = include.spot | default: 'file' %}
+{% assign hook = site.data.theme.extend.hooks.templates[include.template][spot] %}
+{% if hook %}
+  {% if spot == "file" %}
+    {% assign tpl_ext = include.template | split: "_" | last %}
+    {% case tpl_ext %}
+      {% when "html","htm" %}
+        {% assign cmt_start = "<!-- " %}
+        {% assign cmt_end = " -->" %}
+      {% when "yaml","yml" %}
+        {% assign cmt_start = "# " %}
+        {% assign cmt_end = "" %}
+      {% when "asciidoc","adoc","ad" %}
+        {% assign cmt_start = "// " %}
+        {% assign cmt_end = "" %}
+    {% endcase %}
+    {% assign hook_replace_tpl = true %}
+{{ cmt_start }}template replaced by hook ({{hook.template}}){{ cmt_end }}
+  {% endif %}
+{% include {{ hook.template }} %}
+{% endif %}

data/_includes/nav-site.html

@@ -0,0 +1,30 @@
+<!-- nav menu {% comment %}
+Generates header navigation menu.
+{% endcomment %} -->
+<ul class="navbar-nav mt-2 mt-lg-0">
+{% for link in site.data.navs.header.links %}
+  {% assign link_match = link.href | append: "/" | replace: "//","/" %}
+  {% assign page_path = page.url | truncate: link_match.size, "" | append: "/" | replace: "//","/" %}
+  {% if link_match == page_path %}
+    {% assign active = "active" %}
+  {% endif %}
+  {% if link.kids %}
+  <li class="nav-item mr-4 mb-2 mb-lg-0 dropdown">
+    <a class="nav-link dropdown-toggle {{active}}" href="{{ link.href | default: '#' }}" id="navbarDropdownMenuLink" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false">
+      {{ link.text }}</a>
+    <div class="dropdown-menu" aria-labelledby="navbarDropdownMenuLink">
+    {% for kid in link.kids %}
+      <a class="dropdown-item" href="{{ kid.href }}">
+        {{ kid.text }}
+      </a>
+    {% endfor %}
+    </div>
+  </li>
+  {% else %}
+  <li class="nav-item mr-4 mb-2 mb-lg-0">
+    <a class="nav-link {{active}}" href="{{ link.href }}">{{ link.text}}</a>
+  </li>
+  {% endif %}
+  {% assign active = "" %}
+{% endfor %}
+</ul>

data/_includes/nav-subject-menu.html

@@ -0,0 +1,49 @@
+<!-- {% comment %}
+Generates #sidebar-left navigation for subject/product
+{% endcomment %} NAVGOCO menu component -->
+<ul id="subject-menu" class="nav flex-column">
+  {% for item in include.manifest['menu'] %}
+		{% include path-active.liquid href=item.href  kids=item.kids %}
+    <li class="nav-item open card tier-1 {{parent}} {{active}}">
+    {% if item.href %}<a href="{{ item.href }}" class="{{active}} {{open}}">{% endif %}
+    {{ item.text }}
+    {% if item.href %}</a>{% endif %}
+		<!-- tag::sample-nesting[] -->
+    {% if item.kids %}
+      <ul>
+      {% for topic in item.kids %}
+			  {% include path-active.liquid href=topic.href kids=topic.kids %}
+        <li class="nav-item tier-2 {{open}} {{parent}} {{active}}">
+          <a href="{{ topic.href }}" class="nav-link {{active}} {{open}}">
+						{{ topic.text }}
+					</a>
+          {% if topic.kids %}
+          <ul>
+            {% for subtopic in topic.kids %}
+						  {% include path-active.liquid href=subtopic.href kids=subtopic.kids %}
+            <li class="nav-item tier-3 {{open}} {{parent}} {{active}}">
+              <a href="{{ subtopic.href }}" class="nav-link {{active}}">{{ subtopic.text }}</a>
+              {% if subtopic.kids %}
+                <ul>
+                  {% for sst in subtopic.kids %}
+                    {% include path-active.liquid href=sst.href kids=sst.kids %}
+                  <li class="nav-item tier-4 {{open}} {{parent}} {{active}}">
+                    <a href="{{ sst.href }}" class="nav-link {{active}}">{{ sst.text }}</a>
+                  </li>
+                  {% endfor %}
+                </ul>
+              {% endif %}
+            </li>
+            {% endfor %}
+          </ul>
+          {% endif %}
+        </li>
+      {% endfor %}
+      </ul>
+    {% endif %}
+		<!-- end::sample-nesting[] -->
+    </li>
+    {% assign active = "" %}
+    {% assign open = "" %}
+  {% endfor %}
+</ul>