Just the Docs build packaging cleanup

Improve presentation of Description Lists

README.md

@@ -2,7 +2,8 @@
 
 A nice looking, high customizable, responsive Jekyll theme for documention with built-in search. Easily hosted on GitHub pages.
 
-![screenshot 2018-10-22 11 36 56](https://user-images.githubusercontent.com/896475/47302203-e4a8ca80-d5ee-11e8-916a-9bd30e95a40d.png)
+![jtd](https://user-images.githubusercontent.com/896475/47384541-89053c80-d6d5-11e8-98dc-dba16e192de9.gif)
+
 
 ## Installation
 

_config.yml

@@ -15,7 +15,7 @@
 # in the templates via {{ site.myvariable }}.
 title: Just the Docs
 description: A Jekyll theme for documentation
-# baseurl: "" # the subpath of your site, e.g. /blog
+baseurl: "/just-the-docs/" # the subpath of your site, e.g. /blog
 # url: "" # the base hostname & protocol for your site, e.g. http://example.com
 
 sass:

_layouts/about.html

@@ -0,0 +1,5 @@
+---
+layout: default
+---
+
+{{ content }}

_layouts/default.html

@@ -5,7 +5,7 @@
 
   <div class="page-wrap">
     <div class="side-bar">
-      <a href="{{ site.url }}" class="site-title fs-6 text-grey-dk-300 lh-tight">{{ site.title }}</a>
+      <a href="{{ site.url }}{{ site.baseurl }}" class="site-title fs-6 text-grey-dk-300 lh-tight">{{ site.title }}</a>
       <span class="fs-3"><button class="js-main-nav-trigger navigation-list-toggle btn btn-outline" type="button" data-text-toggle="Hide">Menu</button></span>
       <div class="navigation main-nav js-main-nav">
         {% include nav.html %}
@@ -19,7 +19,7 @@
         <div class="main-content pb-0">
           <div class="search js-search">
             <div class="search-input-wrap">
-              <input type="text" class="js-search-input search-input fs-2" placeholder="Search {{ site.title }}" aria-label="Search {{ site.title }}" autocomplete="off">
+              <input type="text" class="js-search-input search-input" placeholder="Search {{ site.title }}" aria-label="Search {{ site.title }}" autocomplete="off">
               <svg width="14" height="14" viewBox="0 0 28 28" xmlns="http://www.w3.org/2000/svg" class="search-icon"><title>Search</title><g fill-rule="nonzero"><path d="M17.332 20.735c-5.537 0-10-4.6-10-10.247 0-5.646 4.463-10.247 10-10.247 5.536 0 10 4.601 10 10.247s-4.464 10.247-10 10.247zm0-4c3.3 0 6-2.783 6-6.247 0-3.463-2.7-6.247-6-6.247s-6 2.784-6 6.247c0 3.464 2.7 6.247 6 6.247z"/><path d="M11.672 13.791L.192 25.271 3.02 28.1 14.5 16.62z"/></g></svg>
             </div>
             <div class="js-search-results search-results-wrap"></div>
@@ -38,7 +38,7 @@
           {% if page.parent != nil and page.parent != page.title %}
             <nav class="breadcrumb-nav">
               <ol class="breadcrumb-nav-list">
-                <li class="breadcrumb-nav-list-item"><a href="{{ site.url }}/{{ page.parent | slugify }}">{{ page.parent }}</a></li>
+                <li class="breadcrumb-nav-list-item"><a href="{{ site.url }}{{ site.baseurl }}/{{ page.parent | slugify }}">{{ page.parent }}</a></li>
                 <li class="breadcrumb-nav-list-item"><span>{{ page.title }}</span></li>
               </ol>
             </nav>

_layouts/home.html

@@ -0,0 +1,5 @@
+---
+layout: default
+---
+
+{{ content }}

_sass/content.scss

@@ -5,8 +5,7 @@
 
 .page-content {
   ul,
-  ol,
+  ol {
-  dl {
     padding-left: 1.5em;
   }
 
@@ -64,4 +63,27 @@
   h1:first-of-type {
     margin-top: 0.5em;
   }
+
+  dl {
+    display: grid;
+    grid-template-columns: max-content 1fr;
+  }
+
+  dt,
+  dd {
+    margin: 0.25em 0;
+  }
+
+  dt {
+    text-align: right;
+
+    &::after {
+      content: ":";
+    }
+  }
+
+  dd {
+    margin-left: 1em;
+    font-weight: 500;
+  }
 }

_sass/layout.scss

@@ -17,13 +17,15 @@
 
 .side-bar {
   z-index: 100;
+  display: flex;
+  flex-wrap: wrap;
   padding-top: $gutter-spacing-sm;
   padding-bottom: $gutter-spacing-sm;
   background-color: $grey-lt-000;
 
   @include mq(md) {
+    flex-wrap: nowrap;
     position: absolute;
-    display: flex;
     width: $nav-width + 16px;
     height: 100%;
     padding-top: $gutter-spacing * 2;
@@ -107,11 +109,9 @@
 
 .navigation {
   @include mq(md) {
-    position: absolute;
-    top: 0;
-    right: 0;
-    height: 100%;
     padding-top: $sp-8;
+    overflow-y: auto;
+    flex: 1 1 auto;
   }
 }
 
@@ -127,9 +127,14 @@ body {
 
 .site-footer {
   position: absolute;
-  bottom: $sp-3;
+  bottom: 0;
+  padding-top: $sp-4;
+  padding-bottom: $sp-4;
 
   @include mq(md) {
-    right: 0;
+    position: static;
+    align-self: flex-end;
+    justify-self: end;
+    background-color: $grey-lt-000;
   }
 }

_sass/navigation.scss

@@ -4,16 +4,17 @@
 
 .site-title {
   display: block;
-  flex-grow: 1;
+  flex: 1 1 auto;
-  flex-shrink: 1;
-  flex-basis: auto;
   background-color: $grey-lt-000;
 
   @include mq(md) {
     position: absolute;
-    top: $gutter-spacing;
+    top: 0;
     right: 0;
+    height: 60px;
+    padding-top: $sp-4;
     z-index: 101;
+    box-shadow: inset 0 -1px 0 $border-color;
   }
 }
 
@@ -24,7 +25,7 @@
   list-style: none;
 
   @include mq(md) {
-    margin-top: $sp-10;
+    margin-top: 0;
   }
 }
 
@@ -88,15 +89,6 @@
   }
 }
 
-.side-bar {
-  display: flex;
-  flex-wrap: wrap;
-
-  @include mq(md) {
-    display: block;
-    overflow-y: auto;
-  }
-}
 
 .navigation-list-toggle {
   position: absolute;

_sass/search.scss

@@ -7,10 +7,11 @@
   z-index: 99;
   display: none;
   flex-grow: 1;
-  padding-bottom: $gutter-spacing / 2;
-  background-color: $white;
   padding: $sp-2;
   margin-bottom: $sp-3;
+  background-color: $white;
+  border-radius: 3px;
+  box-shadow: 0 1px 2px rgba(0, 0, 0, 0.07), 0 3px 10px rgba(0, 0, 0, 0.05);
 
   @include mq(md) {
     display: block;
@@ -20,6 +21,7 @@
     padding-left: 0;
     margin-bottom: 0;
     background-color: transparent;
+    box-shadow: none;
   }
 
   &.nav-open {
@@ -65,6 +67,16 @@
       fill: $purple-000;
     }
   }
+
+  @include fs-5;
+
+  @include mq(sm) {
+    @include fs-3;
+  }
+
+  @include mq(md) {
+    @include fs-2;
+  }
 }
 
 .search-icon {

_sass/support/mixins/_buttons.scss

@@ -2,12 +2,14 @@
 
 @mixin btn-color($fg, $bg) {
   color: $fg;
+  background-color: darken($bg, 2%);
   background-image: linear-gradient(lighten($bg, 5%), darken($bg, 2%));
   box-shadow: 0 1px 3px rgba(0, 0, 0, 0.25), 0 4px 10px rgba(0, 0, 0, 0.12);
 
   &:hover,
   &.zeroclipboard-is-hover {
     color: $fg;
+    background-color: darken($bg, 4%);
     background-image: linear-gradient((lighten($bg, 2%), darken($bg, 4%)));
   }
 

assets/js/just-the-docs.js

@@ -35,14 +35,29 @@ function initSearch() {
   var index = lunr(function () {
     this.ref('id');
     this.field('title', { boost: 20 });
-    this.field('content');
+    this.field('content', { boost: 10 });
     this.field('url');
   });
 
   // Get the generated search_data.json file so lunr.js can search it locally.
 
+  sc = document.getElementsByTagName("script");
+  source = '';
+
+  for(idx = 0; idx < sc.length; idx++)
+  {
+    s = sc.item(idx);
+
+    if(s.src && s.src.match(/just-the-docs\.js$/))
+    { source = s.src; }
+  }
+
+  jsPath = source.replace('just-the-docs.js', '');
+
+  jsonPath = jsPath + '/search-data.json';
+
   var request = new XMLHttpRequest();
-  request.open('GET', '/search-data.json', true);
+  request.open('GET', jsonPath, true);
 
   request.onload = function() {
     if (request.status >= 200 && request.status < 400) {
@@ -103,11 +118,12 @@ function initSearch() {
             var resultsLink = document.createElement('a');
             var resultsUrlDesc = document.createElement('span');
             var resultsUrl = store[results[i].ref].url;
+            var resultsRelUrl = store[results[i].ref].relUrl;
             var resultsTitle = store[results[i].ref].title;
 
-            resultsLink.setAttribute('href', store[results[i].ref].url);
+            resultsLink.setAttribute('href', resultsUrl);
             resultsLink.innerText = resultsTitle;
-            resultsUrlDesc.innerText = resultsUrl;
+            resultsUrlDesc.innerText = resultsRelUrl;
 
             resultsList.classList.add('search-results-list');
             resultsListItem.classList.add('search-results-list-item');

assets/js/search-data.json

@@ -4,8 +4,9 @@
   {% for page in site.html_pages %}"{{ forloop.index0 }}": {
     "id": "{{ forloop.index0 }}",
     "title": "{{ page.title | xml_escape }}",
-    "content": "{{ page.content | markdownify | strip_html | xml_escape | remove: 'Table of contents' | remove: page.title | strip_newlines | replace: '\', ' '}}",
+    "content": "{{ page.content | markdownify | strip_html | xml_escape | remove: 'Table of contents' | strip_newlines | replace: '\', ' ' }}",
-    "url": "{{ page.url | xml_escape }}"
+    "url": "{{ page.url | absolute_url | xml_escape }}",
+    "relUrl": "{{ page.url | xml_escape }}"
   }{% if forloop.last %}{% else %},
   {% endif %}{% endfor %}
 }

docs/search.md

@@ -23,7 +23,7 @@ $ bundle exec just-the-docs rake search:init
 
 This command creates the `search-data.json` file that Jekyll uses to create
 your search index. Alternatively, you can create the file manually in the
-root of your Jekyll site with this content:
+`assets/js/` of your Jekyll site with this content:
 
 ```{% raw %}
 ---
@@ -39,4 +39,4 @@ root of your Jekyll site with this content:
 }{% endraw %}
 ```
 
-You can modify this by modifying the forloop in `search-data.json` and the javascript in `just-the-docs.js` on line 30.
+_Note: If you don't run this rake command or create this file manually, search will not work (or it will use the search index data from this docs site, not your site's content)._

docs/ui-components/typography.md

@@ -111,4 +111,4 @@ Text can be **bold**, _italic_, or ~~strikethrough~~.
 
 There are a number of specific typographic CSS classes that allow you to do override default styling for font size, font-weight, line height, and capitalization.
 
-[View typography utilities]({{ site.base_url }}{% link docs/utilities/utilities.md %}#typography){: .btn .btn-outline }
+[View typography utilities]({{ site.baseurl }}{% link docs/utilities/utilities.md %}#typography){: .btn .btn-outline }

index.md

@@ -2,6 +2,7 @@
 layout: default
 title: Home
 nav_order: 1
+permalink: /
 ---
 
 
@@ -16,7 +17,7 @@ Just the Docs gives your documentation a jumpstart with a responsive Jekyll them
 ---
 
 ## Getting started
-### Dependancies
+### Dependencies
 Just the Docs is built for [Jekyll](https://jekyllrb.com), a static site generator. View the [quick start guide](https://jekyllrb.com/docs/quickstart/) for more information. Just the Docs requires no special Jekyll plugins and can run on GitHub Pages standard Jekyll compiler.
 
 ### Installation
@@ -59,9 +60,8 @@ Just the Docs is distributed by an [MIT license](https://github.com/pmarsceill/j
 ### Contributing
 
 When contributing to this repository, please first discuss the change you wish to make via issue,
-email, or any other method with the owners of this repository before making a change. Read more about becoming a contributor in [our GitHub repo][954661c7].
+email, or any other method with the owners of this repository before making a change. Read more about becoming a contributor in [our GitHub repo](https://github.com/pmarsceill/just-the-docs#contributing).
 
-  [954661c7]: https://github.com/pmarsceill/just-the-docs/tree/master/CONTRIBUTING.md "Contributing.md on Just the Docs GitHub repository"
 
 ### Code of Conduct
 

just-the-docs.gemspec

@@ -2,7 +2,7 @@
 
 Gem::Specification.new do |spec|
   spec.name          = "just-the-docs"
-  spec.version       = "0.1.1"
+  spec.version       = "0.1.4"
   spec.authors       = ["Patrick Marsceill"]
   spec.email         = ["patrick.marsceill@gmail.com"]
 
@@ -14,7 +14,7 @@ Gem::Specification.new do |spec|
   spec.executables   << 'just-the-docs'
 
   spec.add_runtime_dependency "jekyll", "~> 3.3"
+  spec.add_runtime_dependency "rake", "~> 10.0"
 
   spec.add_development_dependency "bundler", "~> 1.12"
-  spec.add_development_dependency "rake", "~> 10.0"
 end

lib/tasks/search.rake

@@ -2,10 +2,12 @@ namespace :search do
   desc 'Generate the files needed for search functionality'
   task :init do
     puts 'Creating search data json file...'
-    touch 'search-data.json'
+    touch 'assets/js/search-data.json'
     content = %Q[{{ page.content | markdownify | strip_html | xml_escape | remove: 'Table of contents' | strip_newlines | replace: '\\', ' ' }}]
+    puts 'Done.'
+    puts 'Generating content...'
 
-    File.open('search-data.json', 'w') do |f|
+    File.open('assets/js/search-data.json', 'w') do |f|
       f.puts '---
 ---
 {
@@ -18,5 +20,6 @@ namespace :search do
   {% endif %}{% endfor %}
 }'
     end
+    puts 'Done.'
   end
 end