jekyll-theme-amethyst 0.2.1 → 0.4.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 38574e61b505ed9369e00635883fa96c647777477a4948f2014cddc262294347
-  data.tar.gz: 3615fc09dd924333280fe835755d20bee3b6b961c8e212faab0a14f03f3c1b58
+  metadata.gz: d478567d792fb9752288273d79106286df6ef6ef3031d87fdcf16d63020c0d7d
+  data.tar.gz: 938cf6b1fe0b22eecb926cc6dc4315e27949e644c3682df2312fc3e90749f409
 SHA512:
-  metadata.gz: c0c56a50b0bcd33d9a638d4c9fe933a63c404a5c9fef7b0172056516cd2072cfd9f703bebd0bd05eab33f6467de7e58cf1480529edf08685028f961e585c2128
-  data.tar.gz: a7da06f4ff9453c14cdf8d1c9d61f62c5cf27be9d9e1aa81f06400c8f935bd016f828e8bc328701ab3921e17421afe4a59ebbecc9fe2a666024882489257c45a
+  metadata.gz: 581e0dd5940ff83d59bddaa0ffa0ccd2e03de9c3359cf2e2b89a101d50d54e2d1613ec3af8ae197588a8e77c30812066c5e1fc1c0bb15537914ba0f1533e6ab1
+  data.tar.gz: 404fe3d0b4e3abe29168e9a8e644d6e5f482e821c4b05eec34d30e3c976bacbb73f78ed1b0d2e639f8a05438ab9d234ee7dedc63de19e7c21fa26b00392581df

data/_data/sidebar_api.yml

@@ -1,13 +1,13 @@
 - group: foo
-  expand: true
+  expand: initial
+  initial: /api/
 
 - group: lorem
 
-- type: list
-  title: Other
-  expand: true
-  list:
-    - url: /api/deprecated/
-      title: Deprecated
-    - url: /api/removed/
-      title: Removed
+- type: link
+  url: /api/deprecated/
+  title: Deprecated
+
+- type: link
+  url: /api/removed/
+  title: Removed

data/_includes/sidebar.html

@@ -2,15 +2,19 @@
 
 Parameters:
 
-* blocks:
+* blocks: [Default: nil]
   Key in `site.data` corresponding to a `_data/*.yml` file.
 
+* toc: [Default: false]
+  Enable table of contents.
+
 Block data:
 
 * type: [Default: "group"]
   What type of block to add to the sidebar.
   - "group" to query a list of pages from a page group.
   - "list" to specify your own custom list.
+  - "link" to specify a single link.
   - "archive" to query a list of chronological pages based on their layout.
   - "tags" to query a list of alphabetical pages based on their layout.
 
@@ -29,23 +33,28 @@ Block data:
   When using a "list" block, an array of objects with "title"
   and "url" properties.
 
-* expand: [Default: active]
+* expand: [Default: "active"]
   Whether a block should be expanded.
   - true: Always expanded.
   - false: Never expanded.
   - active: Expand when the current page is in the list.
+  - initial: Expand on the home page, and when the current page is in the list.
+
+* initial: [Default: "/"]
+  Override which address the "initial" expand mode will compare to.
 
 {%- endcomment -%}
-<section class="sidebar">
+<aside class="sidebar" role="complementary">
 {%- for block in site.data[include.blocks] -%}
 	{%- assign block_type = block.type | default: "group" -%}
 	{%- assign block_title = block.title -%}
 	{%- assign block_url = block.url -%}
 	{%- assign block_contents = block.list -%}
 	{%- assign block_expand = block.expand -%}
-	{%- if block_expand != true and block_expand != false -%}
+	{%- if block_expand != true and block_expand != false and block_expand != "initial" -%}
 		{%- assign block_expand = "active" -%}
 	{%- endif -%}
+	{%- assign block_initial = block.initial | default: "/" -%}
 
 	{%- if block_type == "group" -%}
 		{%- assign group_page = site.pages | where: "layout", "group" | where: "group", block.group | first -%}
@@ -58,6 +67,18 @@ Block data:
 		{%- assign block_contents = site.pages | where: "layout", "posts-year" | sort_natural: 'date' | reverse  -%}
 	{%- elsif block_type == "tags" -%}
 		{%- assign block_contents = site.pages | where: "layout", "posts-tag" | sort_natural: 'title'  -%}
+	{%- elsif block_type == "link" -%}
+		{%- assign block_contents = nil -%}
+		{%- assign block_expand = false -%}
+	{%- endif -%}
+
+	{%- if block_expand == "initial" -%}
+		{%- assign block_expand = false -%}
+		{%- if page.url == block_initial -%}
+			{%- assign block_expand = true -%}
+		{%- else -%}
+			{%- assign block_expand = "active" -%}
+		{%- endif -%}
 	{%- endif -%}
 
 	{%- if block_expand == "active" -%}
@@ -85,5 +106,18 @@ Block data:
 	{%- endfor -%}
 	</ul>
 	{%- endif -%}
-{%- endfor %}
-</section>
+{%- endfor -%}
+
+{%- if include.toc -%}
+	{%- capture jekyll_toc -%}
+		{%- include toc.html html=content sanitize=true h_max=3 ordered=true skip_no_ids=true class="toc" item_class="sidebar-item" -%}
+	{%- endcapture -%}
+	{%- if jekyll_toc != '' -%}
+		{%- if include.blocks -%}
+		<hr>
+		{%- endif -%}
+		<div class="toc-wrapper">
+		<h4>Table of contents</h4>{{ jekyll_toc }}</div>
+	{%- endif -%}
+{%- endif %}
+</aside>

data/_includes/toc.html

@@ -0,0 +1,182 @@
+{% 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.1.0
+          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
+
+        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 %}
+
+    {% if include.baseurl %}
+        {% capture deprecation_warnings %}{{ deprecation_warnings }}<!-- jekyll-toc :: "baseurl" has been deprecated, use "base_url" instead -->{{ newline }}{% endcapture %}
+    {% endif %}
+
+    {% if include.skipNoIDs %}
+        {% capture deprecation_warnings %}{{ deprecation_warnings }}<!-- jekyll-toc :: "skipNoIDs" has been deprecated, use "skip_no_ids" instead -->{{ newline }}{% endcapture %}
+    {% endif %}
+
+    {% capture jekyll_toc %}{% endcapture %}
+    {% assign orderedList = include.ordered | 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: '<h' %}
+
+    {% assign firstHeader = true %}
+    {% assign currLevel = 0 %}
+    {% assign lastLevel = 0 %}
+
+    {% capture listModifier %}{% if orderedList %}ol{% else %}ul{% endif %}{% 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 %}
+
+        {% 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 %}<a{{ anchorAttributes }}>{{ anchorBody }}</a>{% endcapture %}
+        {% elsif skipNoIDs == true %}
+            {% continue %}
+        {% else %}
+            {% capture listItem %}{{ anchorBody }}{% endcapture %}
+        {% endif %}
+
+        {% if currLevel > lastLevel %}
+            {% capture jekyll_toc %}{{ jekyll_toc }}<{{ listModifier }}{{ subMenuClass }}>{% 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 %}
+
+    {% 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 -}}

data/_layouts/group.html

@@ -1,5 +1,13 @@
 ---
 layout: page-api
+amethyst:
+  toc: false
+  prepend_description_heading: false
+
+# Parameters:
+#
+# - group
+#
 ---
 {{ content }}
 

data/_layouts/page-api.html

@@ -1,9 +1,31 @@
 ---
 layout: wrapper
+
+# Parameters:
+#
+# - version_added: semver string (e.g. "1.2.3"). Can be linked by setting `site.amethyst.release_base`.
+# - version_deprecated: semver string
+# - version_removed: semver string
+# - amethyst.prepend_description_heading: boolean. Default: true.
+#
 ---
 
+{%- comment -%}
+Prepend "Description" header.
+This makes sure the accessibility tree is valid since we generally want to
+use H3 within the top section before later sections like "Changelog" and
+"Examples". But, visually we merge the page title and "Description" together.
+
+Rather than require a special class to be put on every page, we instead
+do that here for convenience.
+{%- endcomment -%}
+{%- unless page.amethyst.prepend_description_heading == false or layout.amethyst.prepend_description_heading == false -%}
+{%- capture content -%}
+<h2 id="description" class="screen-reader-text h-api-desc">Description</h2>
+{{ content }}
+{%- endcapture -%}
+{%- endunless -%}
 <div class="main main--columns wrapper">
-{% include sidebar.html blocks="sidebar_api" %}
 <div class="content" role="main">
     <h1>{{ page.title }}</h1>
     {%- if page.version_added or page.version_deprecated -%}
@@ -29,4 +51,9 @@ layout: wrapper
     {%- endif %}
     {{- content }}
 </div>
+{%- assign toc = true -%}
+{%- if layout.amethyst.toc == false -%}
+    {%- assign toc = false -%}
+{%- endif %}
+{% include sidebar.html blocks="sidebar_api" toc=toc %}
 </div>

data/_layouts/page.html

@@ -1,5 +1,11 @@
 ---
 layout: wrapper
+
+# Parameters:
+#
+# - amethyst.hero: boolean. Set to false to render page title without hero. Default: true.
+# - amethyst.toc: boolean. Set to true to add sidebar with table of contents. Default: false.
+#
 ---
 
 {%- unless page.amethyst.hero == false %}
@@ -9,9 +15,23 @@ layout: wrapper
     </div>
 </section>
 {% endunless -%}
+
+{%- if page.amethyst.toc -%}
+<div class="main main--columns wrapper">
+<div class="content">
+{%- else -%}
 <div class="main wrapper content">
+{%- endif -%}
+
 {%- if page.amethyst.hero == false -%}
-    <h1>{{ page.title }}</h1>
+<h1>{{ page.title }}</h1>
 {%- endif -%}
-    {{ content }}
+{{ content }}
+
+{%- if page.amethyst.toc -%}
+</div>
+{% include sidebar.html toc=true %}
 </div>
+{%- else -%}
+</div>
+{%- endif -%}

data/_layouts/post.html

@@ -3,7 +3,6 @@ layout: wrapper
 ---
 
 <div class="main main--columns wrapper">
-{% include sidebar.html blocks="sidebar_blog" %}
 <div class="content">
 	<article class="content">
 	<header>
@@ -34,4 +33,5 @@ Docs: <https://en.gravatar.com/site/implement/images/>
 </div>
 {%- endif -%}
 </div>
+{% include sidebar.html blocks="sidebar_blog" %}
 </div>

data/_layouts/posts-archive.html

@@ -3,7 +3,6 @@ layout: wrapper
 ---
 
 <div class="main main--columns wrapper">
-{% include sidebar.html blocks="sidebar_blog" %}
 {%- assign date_format = site.amethyst.date_format | default: "%e %B %Y" -%}
 {%- assign posts = site.posts -%}
 <div class="posts content">
@@ -14,4 +13,5 @@ layout: wrapper
 	{%- endfor -%}
 	</ul>
 </div>
+{% include sidebar.html blocks="sidebar_blog" %}
 </div>

data/_layouts/posts-author.html

@@ -3,7 +3,6 @@ layout: wrapper
 ---
 
 <div class="main main--columns wrapper">
-{% include sidebar.html blocks="sidebar_blog" %}
 {%- assign date_format = site.amethyst.date_format | default: "%e %B %Y" -%}
 {%- assign posts = site.posts | where: 'author', page.author -%}
 <div class="posts content">
@@ -18,4 +17,5 @@ layout: wrapper
 	</div>
 	{%- endfor -%}
 </div>
+{% include sidebar.html blocks="sidebar_blog" %}
 </div>

data/_layouts/posts-tag.html

@@ -3,7 +3,6 @@ layout: wrapper
 ---
 
 <div class="main main--columns wrapper">
-{% include sidebar.html blocks="sidebar_blog" %}
 {%- assign date_format = site.amethyst.date_format | default: "%e %B %Y" -%}
 {%- assign posts = site.tags[page.tag] -%}
 <div class="posts content">
@@ -21,4 +20,5 @@ layout: wrapper
 	</div>
 	{%- endfor -%}
 </div>
+{% include sidebar.html blocks="sidebar_blog" %}
 </div>

data/_layouts/posts-year.html

@@ -3,7 +3,6 @@ layout: wrapper
 ---
 
 <div class="main main--columns wrapper">
-{% include sidebar.html blocks="sidebar_blog" %}
 {%- assign date_format = site.amethyst.date_format | default: "%e %B %Y" -%}
 {%- assign posts = page.posts -%}
 <div class="posts content">
@@ -21,4 +20,5 @@ layout: wrapper
 	</div>
 	{%- endfor -%}
 </div>
+{% include sidebar.html blocks="sidebar_blog" %}
 </div>

data/_layouts/posts.html

@@ -3,7 +3,6 @@ layout: wrapper
 ---
 
 <div class="main main--columns wrapper">
-{% include sidebar.html blocks="sidebar_blog" %}
 {%- assign date_format = site.amethyst.date_format | default: "%e %B %Y" -%}
 {%- assign posts = site.posts | slice: 0, 10 -%}
 <div class="posts content">
@@ -25,4 +24,5 @@ layout: wrapper
 		<a href="{{ archive_page.url | relative_url }}">Older posts</a>
 	{%- endif -%}
 </div>
+{% include sidebar.html blocks="sidebar_blog" %}
 </div>

data/_sass/amethyst.scss

@@ -160,6 +160,7 @@ iframe {
         min-width: 0;
     }
     .sidebar {
+        order: -1;
         display: block;
         flex: 0 0 220px;
         margin-right: 20px;
@@ -709,6 +710,10 @@ table {
     padding-left: 4px;
 }
 
+.sidebar hr {
+    margin-bottom: $size-spacing;
+}
+
 .sidebar-list {
     margin-top: 0;
     padding: 0;
@@ -739,6 +744,31 @@ table {
     text-decoration: none;
 }
 
+.toc-wrapper {
+    position: sticky;
+    top: 0;
+}
+.toc,
+.toc ol {
+    list-style-type: none;
+    margin: 0;
+    padding: 0;
+}
+.toc .sidebar-item,
+.toc .sidebar-item a {
+    border-left: 0;
+}
+
+// .toc,
+// .toc ol {
+//   counter-reset: section;
+// }
+// .toc li:before {
+//   counter-increment: section;
+//   // Combine with any parent section(s), separated by dot
+//   // content: counters(section, ".") ". ";
+// }
+
 /* Layout: page */
 
 .hero {
@@ -775,6 +805,11 @@ table {
 
 /* Layout: page-api */
 
+.h-api-desc {
+    // Let anchor jump to page title
+    margin-top: -6rem;
+}
+
 .version-details {
     font-size: $size-sm;
     font-weight: bold;

data/amethyst.gemspec

@@ -1,6 +1,6 @@
 Gem::Specification.new do |spec|
   spec.name     = "jekyll-theme-amethyst"
-  spec.version  = "0.2.1"
+  spec.version  = "0.4.1"
   spec.summary  = "https://github.com/qunitjs/jekyll-theme-amethyst"
   spec.authors  = ["Timo Tijhof", "Trent Willis"]
   spec.files    = `git ls-files -z`.split("\x0")

data/api/foo/baz.md

@@ -16,11 +16,9 @@ Hello world. This entry has some content and an added version.
 | `label` (string) | Label for this object. |
 
 
-## Description
-
 A long long sequence of words that continues until its end eventually wraps across to the next line on your screen.
 
-### Changelog
+## Changelog
 
 | [Xample 2.4](https://github.com/qunitjs/qunit/releases/tag/2.4.0) | The `module.only()`, `module.skip()`, and `module.todo()` aliases were introduced.
 | [Xample 2.0](https://github.com/qunitjs/qunit/releases/tag/2.0.0) | The `before` and `after` options were introduced.

data/intro.md

@@ -1,6 +1,8 @@
 ---
 layout: page
 title: Getting Started
+amethyst:
+  toc: true
 ---
 
 <p class="lead" markdown="1">The following guide will get you up-and-running in just a few minutes.</p>

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: jekyll-theme-amethyst
 version: !ruby/object:Gem::Version
-  version: 0.2.1
+  version: 0.4.1
 platform: ruby
 authors:
 - Timo Tijhof
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2021-09-18 00:00:00.000000000 Z
+date: 2021-09-20 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: jekyll
@@ -138,6 +138,7 @@ files:
 - _includes/search-js.html
 - _includes/search.html
 - _includes/sidebar.html
+- _includes/toc.html
 - _includes/version.html
 - _layouts/group.html
 - _layouts/home.html