Merge pull request #212 from pmarsceill/v0.2.7-release

v0.2.7 release
pmarsceill · Sep 10, 2019 · 8bd2da55fe198935aa707de048ddb444418b3feb · 8bd2da5
2 parents efe5918 + 4ca741b
commit 8bd2da55fe198935aa707de048ddb444418b3feb
diff --git a/README.md b/README.md
@@ -4,7 +4,7 @@
 <br><br>
 <p align="center">
     <h1 align="center">Just the Docs</h1>
-    <p align="center">A modern, high customizable, responsive Jekyll theme for documentation with built-in search.<br>Easily hosted on GitHub Pages with few dependencies.</p>
+    <p align="center">A modern, highly customizable, and responsive Jekyll theme for documentation with built-in search.<br>Easily hosted on GitHub Pages with few dependencies.</p>
     <p align="center"><strong><a href="https://pmarsceill.github.io/just-the-docs/">See it in action!</a></strong></p>
     <br><br><br>
 </p>

diff --git a/_config.yml b/_config.yml
@@ -21,9 +21,15 @@ url: "https://pmarsceill.github.io" # the base hostname & protocol for your site
 permalink: pretty
 exclude: ["node_modules/", "*.gemspec", "*.gem", "Gemfile", "Gemfile.lock", "package.json", "package-lock.json",  "script/", "LICENSE.txt", "lib/", "bin/", "README.md", "Rakefile"]
 
+# Set a path/url to a logo that will be displayed instead of the title
+#logo: "/assets/images/just-the-docs.png"
+
 # Enable or disable the site search
 search_enabled: true
 
+# Set the search token separator for hyphenated-word search:
+search_tokenizer_separator: /[\s/]+/
+
 # Enable or disable heading anchors
 heading_anchors: true
 
@@ -50,5 +56,5 @@ compress_html:
   comments: all
   endings: all
   startings: []
-  blank_lines: false
+  blanklines: false
   profile: false
diff --git a/_includes/title.html b/_includes/title.html
@@ -1 +1,5 @@
-{{ site.title }}
+{% if site.logo %}
+  <div class="site-logo"></div>
+{% else %}
+  {{ site.title }}
+{% endif %}
diff --git a/_layouts/default.html b/_layouts/default.html
@@ -7,6 +7,12 @@
 <html lang="{{ site.lang | default: "en-US" }}">
 {% include head.html %}
 <body>
+  <svg xmlns="http://www.w3.org/2000/svg" style="display: none;">
+    <symbol id="link" viewBox="0 0 16 16">
+      <title>Link</title>
+      <path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path>
+    </symbol>
+  </svg>
 
   <div class="page-wrap">
     <div class="side-bar">
@@ -60,7 +66,7 @@
           {% endunless %}
           <div id="main-content" class="page-content" role="main">
             {% if site.heading_anchors != false %}
-              {% include vendor/anchor_headings.html html=content  beforeHeading = "true" anchorBody="<svg class=\"d-inline-block v-align-middle\" viewBox=\"0 0 16 16\" version=\"1.1\" width=\"18\" height=\"18\" aria-hidden=\"true\"><path fill-rule=\"evenodd\" d=\"M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z\"></path></svg>" anchorClass="anchor-heading" %}
+              {% include vendor/anchor_headings.html html=content beforeHeading="true" anchorBody="<svg viewBox=\"0 0 16 16\" aria-hidden=\"true\"><use xlink:href=\"#link\"></use></svg>" anchorClass="anchor-heading" %}
             {% else %}
               {{ content }}
             {% endif %}
@@ -73,7 +79,7 @@ <h2 class="text-delta">Table of contents</h2>
               {% for child in children_list %}
                 {% if child.parent == page.title and child.title != page.title %}
                 <li>
-                  <a href="{{ child.url | absolute_url }}">{{ child.title }}</a>
+                  <a href="{{ child.url | absolute_url }}">{{ child.title }}</a>{% if child.summary %} - {{ child.summary }}{% endif %}
                 </li>
                 {% endif %}
               {% endfor %}

diff --git a/_sass/content.scss b/_sass/content.scss
@@ -116,26 +116,37 @@
 
   .anchor-heading {
     position: absolute;
-    right: -$sp-3;
+    right: -$sp-4;
     width: $sp-5;
     height: 100%;
+    padding-right: $sp-1;
+    padding-left: $sp-1;
     overflow: visible;
-    fill: $link-color;
-    visibility: hidden;
 
     @include mq(md) {
       right: auto;
       left: -$sp-5;
     }
+
+    svg {
+      display: inline-block;
+      width: 100%;
+      height: 100%;
+      fill: $link-color;
+      visibility: hidden;
+    }
   }
 
+  .anchor-heading:hover,
   h1:hover > .anchor-heading,
   h2:hover > .anchor-heading,
   h3:hover > .anchor-heading,
   h4:hover > .anchor-heading,
   h5:hover > .anchor-heading,
   h6:hover > .anchor-heading {
-    visibility: visible;
+    svg {
+      visibility: visible;
+    }
   }
 
   h1,

diff --git a/_sass/layout.scss b/_sass/layout.scss
@@ -125,12 +125,12 @@
 
 .site-header {
   display: flex;
+  min-height: $header-height;
   align-items: center;
 
   @include mq(md) {
     z-index: 101;
     height: $header-height;
-    min-height: $header-height;
     max-height: $header-height;
     border-bottom: $border $border-color;
   }
@@ -142,10 +142,26 @@
   display: flex;
   height: 100%;
   align-items: center;
-  padding-top: $gutter-spacing-sm;
-  padding-bottom: $gutter-spacing-sm;
+  padding-top: $sp-3;
+  padding-bottom: $sp-3;
   color: $body-heading-color;
   @include fs-6;
+
+  @include mq(md) {
+    padding-top: $sp-2;
+    padding-bottom: $sp-2;
+  }
+}
+
+@if variable-exists(logo) {
+  .site-logo {
+    width: 100%;
+    height: 100%;
+    background-image: url($logo);
+    background-repeat: no-repeat;
+    background-position: left center;
+    background-size: contain;
+  }
 }
 
 .menu-button {

diff --git a/_sass/overrides.scss b/_sass/overrides.scss
@@ -0,0 +1,3 @@
+//
+// Custom overrides from a user.
+//
diff --git a/_sass/utilities/_lists.scss b/_sass/utilities/_lists.scss
@@ -2,10 +2,16 @@
 // Utility classes for lists
 //
 
-// stylelint-disable primer/selector-no-utility, primer/no-override
+// stylelint-disable primer/selector-no-utility, primer/no-override, selector-max-type
 
 .list-style-none {
   padding: 0 !important;
   margin: 0 !important;
   list-style: none !important;
+
+  li {
+    &::before {
+      display: none !important;
+    }
+  }
 }
diff --git a/assets/css/dark-mode-preview.scss b/assets/css/dark-mode-preview.scss
@@ -3,6 +3,10 @@
 # only Main files contain this front matter, not partials.
 ---
 
+{% if site.logo %}
+$logo: "{{ site.logo | absolute_url }}";
+{% endif %}
+
 //
 // Import external dependencies
 //

diff --git a/assets/css/just-the-docs.scss b/assets/css/just-the-docs.scss
@@ -3,6 +3,10 @@
 # only Main files contain this front matter, not partials.
 ---
 
+{% if site.logo %}
+$logo: "{{ site.logo | absolute_url }}";
+{% endif %}
+
 //
 // Import external dependencies
 //
@@ -42,3 +46,4 @@
 @import "./tables";
 @import "./code";
 @import "./utilities/utilities";
+@import "./overrides";
diff --git a/assets/js/dark-mode-preview.js b/assets/js/dark-mode-preview.js
@@ -0,0 +1,23 @@
+document.addEventListener("DOMContentLoaded", function(){
+
+  const toggleDarkMode = document.querySelector('.js-toggle-dark-mode')
+  const cssFile = document.querySelector('[rel="stylesheet"]')
+  const originalCssRef = cssFile.getAttribute('href')
+  const darkModeCssRef = originalCssRef.replace('just-the-docs.css', 'dark-mode-preview.css')
+  const buttonCopy = ['Return to the light side', 'Preview dark color scheme']
+  const updateButtonText = function(toggleDarkMode) {
+    toggleDarkMode.textContent === buttonCopy[0] ?
+      toggleDarkMode.textContent = buttonCopy[1] :
+      toggleDarkMode.textContent = buttonCopy[0]
+  }
+
+  jtd.addEvent(toggleDarkMode, 'click', function(){
+    if (cssFile.getAttribute('href') === originalCssRef) {
+      cssFile.setAttribute('href', darkModeCssRef)
+      updateButtonText(toggleDarkMode)
+    } else {
+      cssFile.setAttribute('href', originalCssRef)
+      updateButtonText(toggleDarkMode)
+    }
+  })
+})
diff --git a/assets/js/just-the-docs.js b/assets/js/just-the-docs.js
@@ -52,8 +52,13 @@ function initSearch() {
     if (request.status >= 200 && request.status < 400) {
       // Success!
       var data = JSON.parse(request.responseText);
-
+
+      {% if site.search_tokenizer_separator != nil %}
+      lunr.tokenizer.separator = {{ site.search_tokenizer_separator }}
+      {% else %}
       lunr.tokenizer.separator = /[\s\-/]+/
+      {% endif %}
+
       var index = lunr(function () {
         this.ref('id');
         this.field('title', { boost: 200 });

diff --git a/assets/js/search-data.json b/assets/js/search-data.json
@@ -1,11 +1,12 @@
 ---
 ---
 {
-  {% for page in site.html_pages %}{% if page.search_exclude != true %}"{{ forloop.index0 }}": {
+  {% assign comma = false %}
+  {% for page in site.html_pages %}{% if page.search_exclude != true %}{% if comma == true%},{% endif %}"{{ forloop.index0 }}": {
     "title": "{{ page.title | replace: '&amp;', '&' }}",
     "content": "{{ page.content | markdownify | replace: '</h', ' . </h' | replace: '<hr', ' . <hr' | replace: '</p', ' . </p' | replace: '</ul', ' . </ul' | replace: '</tr', ' . </tr' | replace: '</li', ' | </li' | replace: '</td', ' | </td' | strip_html | escape_once | remove: 'Table of contents' | remove: '```'  | remove: '---' | replace: '\', ' ' | replace: ' .  .  . ', ' . ' | replace: ' .  . ', ' . ' | normalize_whitespace }}",
     "url": "{{ page.url | absolute_url }}",
     "relUrl": "{{ page.url }}"
-  }{% unless forloop.last %},{% endunless %}
+  }{% assign comma = true %}
   {% endif %}{% endfor %}
-}
+}
diff --git a/docs/configuration.md b/docs/configuration.md
@@ -22,31 +22,41 @@ Just the Docs has some specific configuration parameters that can be defined in
 
 View this site's [_config.yml](https://github.com/pmarsceill/just-the-docs/tree/master/_config.yml) file as an example.
 
-## Search enabled
+## Site logo
+
+```yaml
+# Set a path/url to a logo that will be displayed instead of the title
+logo: "/assets/images/just-the-docs.png"
+```
+
+## Search
 
 ```yaml
 # Enable or disable the site search
-# Support true (default) or false
+# Supports true (default) or false
 search_enabled: true
+
+# Enable support for hyphenated search words:
+search_tokenizer_separator: /[\s/]+/
+
 ```
 
 ## Aux links
 
 ```yaml
 # Aux links for the upper right navigation
 aux_links:
-    "Just the Docs on GitHub":
-      - "//github.com/pmarsceill/just-the-docs"
+  "Just the Docs on GitHub":
+    - "//github.com/pmarsceill/just-the-docs"
 ```
 
 ## Heading anchor links
 
 ```yaml
-# Heading anchor links appear on hover over h1-h6 tags
-# in page content allowing users to deep link to a particular
-# heading on a page.
+# Heading anchor links appear on hover over h1-h6 tags in page content
+# allowing users to deep link to a particular heading on a page.
 #
-# Supprts true (default) or false/nil
+# Supports true (default) or false/nil
 heading_anchors: true
 ```
 
@@ -65,20 +75,7 @@ color_scheme: "dark"
 ```
 <button class="btn js-toggle-dark-mode">Preview dark color scheme</button>
 
-<script>
-const toggleDarkMode = document.querySelector('.js-toggle-dark-mode');
-const cssFile = document.querySelector('[rel="stylesheet"]');
-const originalCssRef = cssFile.getAttribute('href');
-const darkModeCssRef = originalCssRef.replace('just-the-docs.css', 'dark-mode-preview.css');
-
-jtd.addEvent(toggleDarkMode, 'click', function(){
-  if (cssFile.getAttribute('href') === originalCssRef) {
-    cssFile.setAttribute('href', darkModeCssRef);
-  } else {
-    cssFile.setAttribute('href', originalCssRef);
-  }
-})
-</script>
+<script type="text/javascript" src="{{ "/assets/js/dark-mode-preview.js" | absolute_url }}"></script>
 
 See [Customization]({{ site.baseurl }}{% link docs/customization.md %}) for more information.
 

diff --git a/docs/customization.md b/docs/customization.md
@@ -34,20 +34,7 @@ color_scheme: "dark"
 ```
 <button class="btn js-toggle-dark-mode">Preview dark color scheme</button>
 
-<script>
-const toggleDarkMode = document.querySelector('.js-toggle-dark-mode');
-const cssFile = document.querySelector('[rel="stylesheet"]');
-const originalCssRef = cssFile.getAttribute('href');
-const darkModeCssRef = originalCssRef.replace('just-the-docs.css', 'dark-mode-preview.css');
-
-jtd.addEvent(toggleDarkMode, 'click', function(){
-  if (cssFile.getAttribute('href') === originalCssRef) {
-    cssFile.setAttribute('href', darkModeCssRef);
-  } else {
-    cssFile.setAttribute('href', originalCssRef);
-  }
-})
-</script>
+<script type="text/javascript" src="{{ "/assets/js/dark-mode-preview.js" | absolute_url }}"></script>
 
 ## Specific visual customization
 
@@ -69,3 +56,20 @@ $link-color: $blue-000;
 ```
 
 _Note:_ Editing the variables directly in `_sass/support/variables.scss` is not recommended and can cause other dependencies to fail.
+
+## Override styles
+
+For styles that aren't defined as a variables, you may want to modify specific CSS classes. To add your own CSS overrides at the end of the cascade, edit `_sass/overrides.scss`. This will allow for all overrides to be kept in a single file, and for any upstream changes to still be applied.
+
+For example, if you'd like to add your own styles for printing a page, you could add the following styles.
+
+#### Example
+{: .no_toc }
+
+```scss
+// Print-only styles.
+@media print {
+  .side-bar, .page-header { display: none; }
+  .main-content { max-width: auto; margin: 1em;}
+}
+```