diff --git a/_config.yml b/_config.yml index f29548e3..e843765d 100644 --- a/_config.yml +++ b/_config.yml @@ -12,6 +12,8 @@ plugins: - jekyll-remote-theme includes_dir: docs/_includes +data_dir: docs/_data +layouts_dir: docs/_layouts sass: sass_dir: docs/assets/_sass diff --git a/docs/_includes/head-custom.html b/docs/_includes/head-custom.html index 79e110a5..4a2e9169 100644 --- a/docs/_includes/head-custom.html +++ b/docs/_includes/head-custom.html @@ -1 +1,4 @@ - \ No newline at end of file + + + + \ No newline at end of file diff --git a/docs/_includes/toc.html b/docs/_includes/toc.html new file mode 100644 index 00000000..bc90d08a --- /dev/null +++ b/docs/_includes/toc.html @@ -0,0 +1,189 @@ +{% 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 %} + + {% capture deprecation_warnings %}{% endcapture %} + + {% if include.baseurl %} + {% capture deprecation_warnings %}{{ deprecation_warnings }}{{ newline }}{% endcapture %} + {% endif %} + + {% if include.skipNoIDs %} + {% capture deprecation_warnings %}{{ deprecation_warnings }}{{ newline }}{% endcapture %} + {% endif %} + + {% capture jekyll_toc %}{% endcapture %} + {% assign orderedList = include.ordered | default: false %} + {% assign flatToc = include.flat_toc | default: false %} + {% assign baseURL = include.base_url | default: include.baseurl | default: '' %} + {% assign skipNoIDs = include.skip_no_ids | default: include.skipNoIDs | default: false %} + {% assign minHeader = include.h_min | default: 1 %} + {% assign maxHeader = include.h_max | default: 6 %} + {% assign nodes = include.html | strip | split: ' maxHeader %} + {% continue %} + {% endif %} + + {% assign _workspace = node | 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 %} + + {% if include.submenu_class and include.submenu_class != blank %} + {% assign subMenuLevel = currLevel | minus: 1 %} + {% capture subMenuClass %} class="{{ include.submenu_class | replace: '%level%', subMenuLevel | 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 %}{{ anchorBody }}{% endcapture %} + {% elsif skipNoIDs == true %} + {% continue %} + {% else %} + {% capture listItem %}{{ anchorBody }}{% endcapture %} + {% endif %} + + {% if currLevel > lastLevel and flatToc == false %} + {% capture jekyll_toc %}{{ jekyll_toc }}<{{ listModifier }}{{ subMenuClass }}>{% endcapture %} + {% elsif currLevel < lastLevel and flatToc == false %} + {% assign repeatCount = lastLevel | minus: currLevel %} + + {% for i in (1..repeatCount) %} + {% capture jekyll_toc %}{{ jekyll_toc }}{% endcapture %} + {% endfor %} + + {% capture jekyll_toc %}{{ jekyll_toc }}{% endcapture %} + {% else %} + {% capture jekyll_toc %}{{ jekyll_toc }}{% endcapture %} + {% endif %} + + {% capture jekyll_toc %}{{ jekyll_toc }}{{ listItem }}{% endcapture %} + + {% assign lastLevel = currLevel %} + {% assign firstHeader = false %} + {% endfor %} + + {% if flatToc == true %} + {% assign repeatCount = 1 %} + {% else %} + {% assign repeatCount = minHeader | minus: 1 %} + {% assign repeatCount = lastLevel | minus: repeatCount %} + {% endif %} + + {% for i in (1..repeatCount) %} + {% capture jekyll_toc %}{{ jekyll_toc }}{% endcapture %} + {% endfor %} + + {% if jekyll_toc != '' %} + {% assign rootAttributes = '' %} + {% if include.class and include.class != blank %} + {% capture rootAttributes %} class="{{ include.class | split: '.' | join: ' ' }}"{% endcapture %} + {% endif %} + + {% if include.id and include.id != blank %} + {% capture rootAttributes %}{{ rootAttributes }} id="{{ include.id }}"{% endcapture %} + {% endif %} + + {% if rootAttributes %} + {% assign nodes = jekyll_toc | split: '>' %} + {% capture jekyll_toc %}<{{ listModifier }}{{ rootAttributes }}>{{ nodes | shift | join: '>' }}>{% endcapture %} + {% endif %} + {% endif %} +{% endcapture %}{% assign tocWorkspace = '' %}{{ deprecation_warnings }}{{ jekyll_toc -}} diff --git a/docs/_layouts/default.html b/docs/_layouts/default.html new file mode 100644 index 00000000..f0cad786 --- /dev/null +++ b/docs/_layouts/default.html @@ -0,0 +1,55 @@ + + + + + +{% seo %} + + + + + + + {% include head-custom.html %} + + + + + + +
+
+ {{ content }} + + +
+ +
+ + diff --git a/docs/assets/_sass/toc.scss b/docs/assets/_sass/toc.scss new file mode 100644 index 00000000..0eb87b26 --- /dev/null +++ b/docs/assets/_sass/toc.scss @@ -0,0 +1,68 @@ +// Enable smooth scrolling +html { + scroll-behavior: smooth; +} + +// Hide navbar on small/medium screens +#page-container>nav { + display: none; +} + +@include large { + + // Style table of content + /** page layout **/ + #page-container { + display: grid; + grid-template-columns: 1fr 15em; + max-width: 100em; + width: 90%; + margin: 0 auto; + } + + // Make nav sticky + #page-container>nav { + display: block; + position: sticky; + top: 2rem; + margin-top: 2rem; + align-self: start; + + + ul, + ol { + list-style: none; + margin: 0; + padding: 0; + } + + li { + margin-left: 1rem; + } + } + + // ScrollSpy active styles (see toc.js tab for activation) + .section-nav li.active>a { + color: #333; + font-weight: 500; + } + + .section-nav { + padding-left: 0; + border-left: 1px solid #efefef; + } + + .section-nav a { + text-decoration: none; + display: block; + padding: .125rem 0; + color: #ccc; + transition: all 50ms ease-in-out; + /* 💡 This small transition makes setting of the active state smooth */ + } + + .section-nav a:hover, + .section-nav a:focus { + color: #666; + } +} \ No newline at end of file diff --git a/docs/assets/css/style.scss b/docs/assets/css/style.scss index f49910dc..56f05937 100644 --- a/docs/assets/css/style.scss +++ b/docs/assets/css/style.scss @@ -9,4 +9,7 @@ // Change fonts and syntax highlighting @import 'fonts'; -@import 'rouge-monokai'; \ No newline at end of file +@import 'rouge-monokai'; + +// Add table of contents navbar +@import 'toc'; diff --git a/docs/assets/js/toc.js b/docs/assets/js/toc.js new file mode 100644 index 00000000..448acb7c --- /dev/null +++ b/docs/assets/js/toc.js @@ -0,0 +1,19 @@ +window.addEventListener('DOMContentLoaded', () => { + + const observer = new IntersectionObserver(entries => { + entries.forEach(entry => { + const id = entry.target.getAttribute('id'); + if (entry.intersectionRatio > 0) { + document.querySelector(`nav li a[href="#${id}"]`).parentElement.classList.add('active'); + } else { + document.querySelector(`nav li a[href="#${id}"]`).parentElement.classList.remove('active'); + } + }); + }); + + // Track all headings + document.querySelectorAll('h2, h3, h4, h5, h6').forEach((section) => { + observer.observe(section); + }); + +}); \ No newline at end of file