j1-template 2020.0.16 → 2020.0.21

data/lib/starter_web/index.html

@@ -26,7 +26,7 @@ robots:
 #permalink:                             /
 scrollbar:                              false
 
-resources:                              [ animate ]
+resources:                              [ back2top, animate ]
 resource_options:
   - attic:
       padding_top:                      400

data/lib/starter_web/package.json

@@ -1,8 +1,8 @@
 {
   "private": true,
   "name": "j1_starter",
-  "version": "2020.0.16",
-  "description": "J1 Template starter Web",
+  "version": "2020.0.21",
+  "description": "J1 Template Starter Web",
   "homepage": "https://your.site",
   "author": {
     "name": "Your Name",

data/lib/starter_web/pages/protected/site_search.adoc

@@ -24,32 +24,21 @@ resource_options:
           alt:                          featured-1920x800
 ---
 
+// Page Initializer
+// =============================================================================
 // Enable the Liquid Preprocessor
-// -----------------------------------------------------------------------------
 :page-liquid:
 
-// Set other global page attributes here
-// -----------------------------------------------------------------------------
-
-// Liquid procedures
-// -----------------------------------------------------------------------------
-//{% capture set_env_entry_document %}themes/{{site.template.name}}/procedures/global/set_env_entry_document.proc{%endcapture%}
-
-// Initialize entry document paths
-// -----------------------------------------------------------------------------
-//{% include {{set_env_entry_document}} init_folders=all %}
-
-// Load tags and urls
+//  Load Liquid procedures
 // -----------------------------------------------------------------------------
-//include::{includedir}/attributes.asciidoc[tag=tags]
-//include::{includedir}/attributes.asciidoc[tag=urls]
-//include::{includedir}/attributes.asciidoc[tag=data]
+{% capture load_attributes %}themes/{{site.template.name}}/procedures/global/attributes_loader.proc{%endcapture%}
 
-// Additional Asciidoc page attributes goes here
+// Load page attributes (all)
 // -----------------------------------------------------------------------------
+{% include {{load_attributes}} %}
 
-// Include sub-documents
-// -----------------------------------------------------------------------------
+// Page content
+// =============================================================================
 
 == Site Search
 

data/lib/starter_web/pages/public/blog/navigator/archive.html

@@ -72,26 +72,20 @@ resource_options:
 
   <!-- ul class="list-unstyled link-news" -->
   {% for post in site.posts %}
-    {% assign excerpt = post.excerpt | truncatewords: 50 | strip_html | strip_newlines | strip %}
-    <div class="card card-flat" style="background-color: #fafafa">
-      <div class="card-body">
-        <!-- <span class="post-meta">{{post.date|date: "%B %d, %Y"}}</span> -->
-        <h3 id="{{100000 | rand}}" class="card-title">{{post.title}}</h3>
-        <h5 class="notoc card-subtitle text-muted mb-2">{{post.tagline}}</h5>
-        <div class="card-text"><p>{{excerpt}}</p></div>
-        <span class="d-block text-muted text-uppercase g-font-weight-600 g-font-size-12">
-          <i class="mdi mdi-calendar-blank"></i>
-          {{post.date|date:'%Y %B, %e'}}
-        </span>
+    {% assign excerpt = post.excerpt|truncatewords:50|replace:'...',' ...'|strip_html|strip_newlines|strip %}
+    <article class="card raised-z5 mb-5">
+      <h3 id="{{100000|rand}}" class="card-header bg-primary">{{post.title}}</h3>
+      <!-- h5 class="notoc card-subtitle text-muted mb-2">{{post.tagline}}</h5 -->
+      <div class="card-body r-text-300">{{excerpt}}</div>
+      <div class="card-body text-muted r-text-200">
+        <i class="mdi mdi-calendar-blank"></i> {{post.date|date:"%Y %B, %e"}}
       </div>
-      <div class="card-footer" style="background-color: #fafafa">
-        <!-- <a class="card-link" href="{{post.url}}#readmore" target="_blank">Read more ..</a> -->
-        <a class="btn btn-secondary btn-raised btn-flex" href="{{post.url}}#readmore">
-          <i class="fa fa-eye fa-lg mr-2" style="color:#FFFFFF;"></i>
-          Read · {{post.tagline}}
+      <div class="card-footer r-text-200">
+        <a class="card-link md-blue font-weight-bold g-font-size-12 text-uppercase"
+           href="{{post.url}}#readmore">Read · {{post.tagline}}
         </a>
       </div>
-    </div>
+    </article>
   {% endfor %}
 </div>
 

data/lib/starter_web/pages/public/blog/navigator/archive/categoryview.html

@@ -33,7 +33,6 @@ resource_options:
 -------------------------------------------------------------------------------- {% endcomment %}
 {% comment %} site_category_word_list:  {{site_category_word_list|debug}} {% endcomment %}
 
-
 {% comment %} Liquid procedures
 -------------------------------------------------------------------------------- {% endcomment %}
 {% capture get_page_path %}themes/{{site.template.name}}/procedures/global/get_page_path.proc{% endcapture %}
@@ -103,7 +102,7 @@ resource_options:
   {% for tag in tags %}
     {% assign category = tag|first %}
     {% unless category_list contains category %} {% continue %} {% endunless %}
-    <h3 id="{{tag|first}}" class="toc-link"><i class="mdi mdi-pin mr-1"></i>{{tag|first|capitalize}}</h3>
+    <h3 id="{{tag|first}}" class="mb-4"><i class="mdi mdi-pin mr-1"></i>{{tag|first|capitalize}}</h3>
 
       {% for post in sorted_posts %}
         {%if post.categories contains tag[0]%}
@@ -111,26 +110,21 @@ resource_options:
           {% include {{get_category_item}} category=category %}
           {% include {{select_icon_size}} family=icon_family size=icon_size %}
           {% assign icon_size = size %}
-          {% assign excerpt = post.excerpt|truncatewords: 50|strip_html|strip_newlines|strip %}
-
-          <div class="card card-flat" style="background-color: #fafafa">
-            <div class="card-body">
-              <!-- <span class="post-meta">{{post.date|date: "%B %d, %Y"}}</span> -->
-              <h4 id="{{100000|rand}}" class="card-title">{{post.title}}</h4>
-              <h5 class="notoc card-subtitle text-muted mb-2">{{post.tagline}}</h5>
-              <div class="card-text"><p>{{excerpt}}</p></div>
-              <span class="d-block text-muted text-uppercase g-font-weight-600 g-font-size-12">
-                <i class="mdi mdi-calendar-blank"></i>
-                {{post.date|date:"%Y %B, %e"}}
-              </span>
+          {% assign excerpt = post.excerpt|truncatewords:50|replace:'...',' ...'|strip_html|strip_newlines|strip %}
+
+          <article class="card raised-z5 mb-5">
+            <h3 id="{{100000|rand}}" class="card-header bg-primary notoc">{{post.title}}</h3>
+            <!-- h5 class="notoc card-subtitle text-muted mb-2">{{post.tagline}}</h5 -->
+            <div class="card-body r-text-300">{{excerpt}}</div>
+            <div class="card-body text-muted r-text-200">
+              <i class="mdi mdi-calendar-blank"></i> {{post.date|date:"%Y %B, %e"}}
             </div>
-            <div class="card-footer" style="background-color: #fafafa">
-              <a class="btn btn-secondary btn-raised btn-flex" href="{{post.url}}#readmore">
-                <i class="mdi mdi-eye mdi-lg mr-2" style="color:#FFFFFF;"></i>
-                Read · {{post.tagline}}
+            <div class="card-footer r-text-200">
+              <a class="card-link md-blue font-weight-bold g-font-size-12 text-uppercase"
+                 href="{{post.url}}#readmore">Read · {{post.tagline}}
               </a>
             </div>
-          </div>
+          </article>
         {% endif %}
       {% endfor %}
   {% endfor %}

data/lib/starter_web/pages/public/blog/navigator/archive/dateview.html

@@ -78,9 +78,9 @@ resource_options:
     {% capture nmonth %}{{post.next.date|date:'%m%Y'}}{% endcapture %}
     {% capture monthHead %}
       {% if month != nmonth %}
-      {% if  forloop.index != 1  %}{{closeList}}{%endif %}
+      {% if forloop.index != 1  %}{{closeList}}{%endif %}
       <h3 id="{{100000|rand}}"
-        class="toc-link mt-5 mb-2">
+        class="toc-link mt-5 mb-3">
         {% if year != nyear %}
         <a id="{{post.date|date:'%Y'}}"></a>
         {% endif %}<a id="{{post.date|date:'%Y-%m' }}">
@@ -93,27 +93,21 @@ resource_options:
     {% endcapture %}
 
     {% capture link %}
-      {% assign excerpt = post.excerpt|truncatewords:50|strip_html|strip_newlines|strip %}
+      {% assign excerpt = post.excerpt|truncatewords:50|replace:'...',' ...'|strip_html|strip_newlines|strip %}
       <li>
-        <div class="card card-flat mb-4" style="background-color: #fafafa">
-          <div class="card-body">
-            <!-- <span class="post-meta">{{post.date|date:'%B %d, %Y'}}</span> -->
-            <h4 id="{{100000|rand}}" class="card-title">{{post.title}}</h4>
-            <h5 class="notoc card-subtitle text-muted mb-2">{{post.tagline}}</h5>
-            <div class="card-text"><p>{{excerpt}}</p></div>
-            <span class="d-block text-muted text-uppercase g-font-weight-600 g-font-size-12">
-              <i class="mdi mdi-calendar-blank"></i>
-              {{post.date|date:'%Y %B, %e'}}
-            </span>
+        <article class="card raised-z5 mb-5">
+          <h3 id="{{100000|rand}}" class="card-header bg-primary notoc">{{post.title}}</h3>
+          <!-- h5 class="notoc card-subtitle text-muted mb-2">{{post.tagline}}</h5 -->
+          <div class="card-body r-text-300">{{excerpt}}</div>
+          <div class="card-body text-muted r-text-200">
+            <i class="mdi mdi-calendar-blank"></i> {{post.date|date:"%Y %B, %e"}}
           </div>
-          <div class="card-footer" style="background-color: #fafafa">
-            <!-- <a class="card-link" href="{{post.url}}#readmore" target="_blank">Read more ..</a> -->
-            <a class="btn btn-secondary btn-raised btn-flex" href="{{post.url}}#readmore">
-              <i class="mdi mdi-eye mdi-lg mr-2" style="color:#FFFFFF;"></i>
-              Read · {{post.tagline}}
+          <div class="card-footer r-text-200">
+            <a class="card-link md-blue font-weight-bold g-font-size-12 text-uppercase"
+               href="{{post.url}}#readmore">Read · {{post.tagline}}
             </a>
           </div>
-        </div>
+        </article>
       </li>
     {% endcapture %}
 

data/lib/starter_web/pages/public/blog/navigator/archive/tagview.html

@@ -146,23 +146,22 @@ resource_options:
       {% include {{select_icon_size}} family=icon_family size=icon_size %}
       {% assign icon_size = size %}
 
-      {% assign excerpt = post.excerpt | truncatewords: 50 | strip_html | strip_newlines | strip %}
+      {% assign excerpt = post.excerpt|truncatewords:50|replace:'...',' ...'|strip_html|strip_newlines|strip %}
 
       <!-- place post  -->
-      <div class="card card-flat mb-4">
-        <div class="card-body">
-          <!-- <span class="post-meta">{{post.date|date: "%B %d, %Y"}}</span> -->
-          <h5 id="{{100000 | rand}}" class="card-title">{{post.title}}</h5>
-          <h6 class="notoc card-subtitle text-muted mb-2">{{post.tagline}}</h6>
-          <div class="card-text"><p>{{excerpt}}</p></div>
+      <article class="card raised-z5 mb-5">
+        <h3 id="{{100000|rand}}" class="card-header bg-primary">{{post.title}}</h3>
+        <!-- h5 class="notoc card-subtitle text-muted mb-2">{{post.tagline}}</h5 -->
+        <div class="card-body r-text-300">{{excerpt}}</div>
+        <div class="card-body text-muted r-text-200">
+          <i class="mdi mdi-calendar-blank"></i> {{post.date|date:"%Y %B, %e"}}
         </div>
-        <div class="card-footer">
-          <a class="btn btn-secondary btn-raised btn-flex" href="{{post.url}}#readmore">
-            <i class="mdi mdi-eye mdi-lg mr-2" style="color:#FFFFFF;"></i>
-            Read · {{post.tagline}}
+        <div class="card-footer r-text-200">
+          <a class="card-link md-blue font-weight-bold g-font-size-12 text-uppercase"
+             href="{{post.url}}#readmore">Read · {{post.tagline}}
           </a>
         </div>
-      </div>
+      </article>
     {% endif %}{% endfor %}
   {% endunless %}{% endfor %}
 </div>

data/lib/starter_web/pages/public/bookshelf/100_whats_up.adoc

@@ -0,0 +1,281 @@
+---
+layout:                                 page
+
+title:                                  What's up
+tagline:                                Jekyll Collections Overview
+description:                            Most powerful but least understood feature
+
+tags:                                   [ collections  ]
+index:                                  [ Jekyll, Collections, Overview]
+categories:                             [ collections ]
+
+permalink:                              /pages/public/collections/whats_up/
+regenerate:                             false
+
+tags:                                   [ Jekyll, Collections, Feature, Overview ]
+
+
+
+resource_options:
+  - attic:
+      padding_top:                      400
+      padding_bottom:                   50
+      opacity:                          0.5
+      slides:
+        - url:                          /assets/images/modules/attics/giammarco-boscaro-1920x1280.jpg
+          alt:                          giammarco-boscaro-1920x1280
+
+regenerate:                             false
+---
+
+// Enable the Liquid Preprocessor
+//
+:page-liquid:
+
+// Set other global page attributes here
+// -------------------------------------------------------------------
+
+
+Collections are Jekyll's most powerful and simultaneously least understood
+feature. Collections add another possibility, or use-case, outside of Jekyll's
+post- and page-publishing functionality. Collections have the potential to
+bring Jekyll's zen-like simplicity to all sorts of other types of content that
+aren't ordered as with posts (ordered by date), but have a set *relationship*
+with one another - hence the name: _collection_.
+
+excerpt__end
+
+Source: https://ben.balter.com/2015/02/20/jekyll-collections/[Ben Balter: Jekyll Collections]
+
+[[readmore]]
+== Traditional - Posts and pages
+
+{% if page.image.name %}
+.{{page.tagline}}
+[role="mb-5"]
+image::{{page.image.name}}[{{page.title}}]
+{% endif %}
+
+Most Jekyll sites are organized around two types of content, posts (ordered)
+and pages (un-ordered).
+
+* *http://jekyllrb.com/docs/posts/[Posts]* are organized reverse
+chronologically. You might use them for blog posts on a personal blog,
+or articles on a news site. You can recognize a post by its filename.
+Posts live in the `_posts` folder, and are always named in the form of
+`YYYY-MM-DD-post-title.md`. Because posts are dated, they're
+traditionally not updated regularly once published.
+
+* *http://jekyllrb.com/docs/pages/[Pages]* are documents that don't have
+a relationship with one another. They can live anywhere within the
+site's source directory and don't have a set naming pattern. If you have
+a personal blog, you might have an `index.html` page
+(https://ben.balter.com/[the site's main page which is used to list
+posts]), or https://ben.balter.com/about/[an about me page], to name two
+examples. Because pages aren't date specific, pages are often updated
+over time to maintain accuracy.
+
+The problem is, not everything you might want to publish using a Jekyll
+falls cleanly into the those two categories of content. As I noted in
+https://github.com/jekyll/jekyll/issues/1941[the original pitch], "If
+people are using blog posts for a non-blog post thing, Jekyll has
+already failed". That's where Jekyll's
+http://jekyllrb.com/docs/collections/[collections] come in.
+
+
+== Not a post, a page - but a collection?
+
+Collections add another possibility, or use-case, outside of Jekyll's
+post- and page-publishing functionality. Collections have the potential to
+bring Jekyll's zen-like simplicity to all sorts of other types of content that
+aren't ordered as with posts (ordered by date), but have a set _relationship_
+with one another - hence the name: _collection_. If you're familiar with
+traditional CMS's, you can think of collections like
+http://codex.wordpress.org/Post_Types[WordPress custom post types] or
+https://www.drupal.org/node/774728[Drupal custom content types], except
+you do not need to program a specific class, learn any back-end
+languages, and the syntax used to specify them is very easily readable.
+
+What then, might you use collections for? Let's say you're making a
+website for a bakery and want to list the different cupcakes varieties
+you sell. You might use a collection called *cupcakes*. You'd create a
+`_cupcakes` folder, and would add `chocolate.md` or `vanilla.md` to it.
+And just like posts or pages, your list of cupcakes would be accessible
+as `site.cupcakes`.
+
+You wouldn't want to use posts here, because cupcakes aren't
+chronological, and likely wouldn't want to just use a page here, because
+it's a notably different animal than a document that lists your location
+and hours. Each cupcake in the cupcakes collection is related to
+one-another in the sense that they're all cupcakes.
+
+[NOTE]
+====
+Collections are a very new feature to Jekyll, and according to the
+official documentation may be subject to change
+http://jekyllrb.com/docs/collections/[Jekyll Documentation on
+Collections]; but you should not let that put you off of using them,
+because Jekyll is open-source, which means you should trust the
+community to work-together for the best common-case solution.
+====
+
+
+=== Collections in practice
+
+But what if one day you decided to expand your offerings and sell
+cookies in addition to cupcakes. Simply introduce a "cookies"
+collection, adding `chocolate-chip.md` and `peanut-butter.md` to a
+`_cookies` directory, exposing the cookies as `site.cookies`. You'll
+notice the collections concept start to show its value here. Pages
+wouldn't make sense here, because you'd want to be able to list cupcakes
+and cookies separately, and besides for both being baked goods, the one
+cookie doesn't really share a relationship with a cupcake, at least not
+in the same sense that cookies share with one another.
+
+Of course you could at this stage, choose to have a more generic
+collection `products`, which you could develop liquid layouts for, so
+that you and other developers could get the basic functionality needed
+to display all products, with specific includes for `cupcakes` and
+`cookies`.
+
+Abstractly, because they're not outputted by default, you can think of
+collections somewhat like http://jekyllrb.com/docs/datafiles/[Jekyll's
+`_data` folder support], but with the potential to generate content, and
+be placed into their own specific part of your Jekyll site, so a lot
+more robust. Like `_data` files, they can support arbitrary key/values
+through frontmatter, but they also support a full content body (like
+posts and pages), and can be broken out into separate files. If I wanted
+to break out my bakery's hours, I might have a `_data/hours.yml` file
+that looked something like this:
+
+[source,yaml]
+----
+monday: 9-5
+tuesday: 9-5
+wednesday: 9-5
+thursday: 9-5
+friday: 9-3
+----
+
+That makes sense, because my bakery's hours is a relatively small
+dataset. But trying to represent all my baked goods in that format (or
+worse posts), would quickly get out of hand. That type of information is
+better represented as individual markdown files with front matter, not
+one giant YAML file that will quickly become unwieldy with complexity;
+and rather than create the data, and pages to display the data, or the
+data and a plugin to turn it into pages; using collections allows the
+site owner to focus on the content.
+
+For a more concrete example, take a look at
+https://github.com/github/choosealicense.com[the source] for
+http://choosealicense.com[choosealicense.com] a site which helps explain
+open source licenses like the MIT or GPL license. There are pages like
+"about" and "terms of service", but the actual licenses live in
+https://github.com/github/choosealicense.com/tree/gh-pages/_licenses[a
+licenses collection] and are displayed via
+https://github.com/github/choosealicense.com/blob/gh-pages/licenses.html[a
+licensed page].
+
+=== Other use-cases
+
+Of course this is not the only use-case, which is one of the benefits of
+collections. You can turn on content generation to have the collection
+contents automatically generated, or use the where syntax to get the
+contents of specific collections to add common content, or devices to
+your site.
+
+
+== Using collections
+
+The examples above were a slight simplification. There's one other step.
+Before you can use a collection, you need to tell Jekyll about it. Going
+back to our bakery example above, I might have a `_config.yml` file that
+looks something like this:
+
+[source,yaml]
+----
+collections:
+  - cupcakes
+  - cookies
+----
+
+This tells Jekyll to look in the `_cupcakes` and `_cookies` folders
+for documents, and to read them into the appropriate collection, including
+http://jekyllrb.com/docs/frontmatter/[YAML front matter], just as it
+would posts (but again, without the date, because collection documents
+aren't date specific).
+
+By default, collections are read in (and exposed as `site.[collection]`,
+an alias per-collection), but not included in the final site; at least
+not individually like you might expect posts or pages to. If you wanted
+a page for each type of cupcake, you'd have to modify the `_config.yml`
+a bit:
+
+[source,yaml]
+----
+collections:
+  cupcakes:
+    output: true
+    permalink: /cupcakes/:path/
+----
+
+That way, `_cupcakes/chocolate.md` is outputted as
+`cupcakes/chocolate/index.html` when the site is built and would be
+accessible as `example.com/cupcakes/chocolate/`. The other advantage,
+is, because the data is now structured and machine readable (rather than
+in plain text), you could also use the `jsonify` filter to output that
+same information as an API for use elsewhere.
+
+
+=== When to use a post, a page, or a collection
+
+I like to think the decision looks roughly like this:
+
+[source,console]
+----
++-------------------------------------+         +----------------+
+| Can the things be logically grouped?|---No--->|    Use pages   |
++-------------------------------------+         +----------------+
+                |
+               Yes
+                |
+                V
++-------------------------------------+         +----------------+
+|      Are they grouped by date?      |---No--->|Use a collection|
++-------------------------------------+         +----------------+
+                |
+               Yes
+                |
+                V
++-------------------------------------+
+|            Use posts                |
++-------------------------------------+
+----
+
+So if you're not about to open a bakery (if you do, please send
+cookies); what might you use collections for? In short, any discrete
+group of "things" that can be logically grouped by a common theme
+(that's not their date). Here's a few examples:
+
+* Listing employees on your company's "about" page (or a project's
+maintainers)
+* Documenting methods in an open source project (or the project's that
+use it, or the plugins available)
+* Organizing jobs on your résumé (or talks given, papers written)
+* https://github.com/blog/1939-how-github-uses-github-to-document-GitHub[Articles
+on a support site]
+* Recipes on your personal blog (or restaurant reviews, or dishes on a
+menu)
+* Students in a class (or courses being offered, or listing the faculty)
+* Cheats, tips, tricks and walkthroughs for games (by platform)
+* Creating re-usable content snippets for your site such as
+testimonials, forms, sentences, buzz-words or call-outs
+* And honestly just about anything else
+
+Collections are a powerful (and often misunderstood) Jekyll feature, but
+hopefully you've now got an idea or two for your next Jekyll project. Of
+course, if you're looking to dig in to collections, be sure to check out
+http://jekyllrb.com/docs/collections/[the formal documentation] for a
+much more in-depth explanation.
+
+Happy Jekylling!