j1_template_mde 2018.4.10

data/lib/starter_web/pages/blog/navigator/archive_by_tag.html

@@ -0,0 +1,168 @@
+---
+layout:                                 page
+
+title:                                  Blog Archive by Tag
+tagline:                                Check out all blog posts by tag
+
+toc:                                    true
+permalink:                              /pages/blog/navigator/archive/tagview/
+regenerate:                             false
+---
+
+{% comment %} TODO
+logic for "letter_group_written == false" to be fixed
+--------------------------------------------------------------- {% endcomment %}
+
+
+{% comment %} Liquid procedures
+--------------------------------------------------------------- {% endcomment %}
+{% capture select_icon_size %}themes/{{site.template.name}}/procedures/global/select_icon_size.proc{% endcapture %}
+{% capture get_category %}themes/{{site.template.name}}/procedures/global/get_category.proc{% endcapture %}
+{% capture get_category_item %}themes/{{site.template.name}}/procedures/global/get_category_item.proc{% endcapture %}
+{% capture create_word_cloud %}themes/{{site.template.name}}/procedures/global/create_word_cloud.proc{% endcapture %}
+
+{% comment %} Variables
+--------------------------------------------------------------- {% endcomment %}
+{% assign view_config       = site.data.builder.blog_navigator.tag_view %}
+{% assign view_description  = view_config.description %}
+
+{% if site.permalink == 'none' %}
+  {% capture browser_page_url %}{{ page.url }}.html{% endcapture %}
+{% else %}
+  {% capture browser_page_url %}{{ page.url }}{% endcapture %}
+{% endif %}
+
+{% comment %} jadams: skip_words needs to be configured by yaml data file
+--------------------------------------------------------------- {% endcomment %}
+{% assign skip_words      = "posts" %}
+{% assign skip_word_array = skip_words | split:',' | sort %}
+
+{% assign letter_groups        = "ab, cd, ef, gh, ij, kl, mn, op, qr, st, uvw, xyz" %}
+{% assign letter_groups        = letter_groups | remove: ' ' %}
+{% assign letter_group_array   = letter_groups | split:',' %}
+{% assign letter_group_counter = 0 %}
+{% assign letter_group_written = false %}
+
+{% assign navigator_base_path = "/pages/blog/navigator" %}
+{% capture archive_path %}{{navigator_base_path}}/archive{% endcapture %}
+
+{% capture navigator %}{{navigator_base_path}}/{% endcapture %}
+{% capture blog_preview %}{{archive_path}}/preview/{% endcapture %}
+{% capture date_view %}{{archive_path}}/dateview/{% endcapture %}
+{% capture category_view %}{{archive_path}}/categoryview/{% endcapture %}
+{% capture tag_view %}{{archive_path}}/tagview/{% endcapture %}
+{% capture all_view %}{{archive_path}}/{% endcapture %}
+
+{% capture site_tag_list %}{% for tag in site.tags %}{{ tag | first }}{% unless forloop.last %},{% endunless %}{% endfor %}{% endcapture %}
+
+{% assign site_tag_list_array = site_tag_list | split:',' | sort %}
+
+{% comment %} Main
+--------------------------------------------------------------- {% endcomment %}  
+  <!-- <script>
+    // TODO: Fix last_page settings and logging
+    var logger = log4javascript.getLogger('j1.BlogNavigator');
+    var cookieUserState = 'j1.user.state'
+    j1_user_state.last_page = "{{browser_page_url}}"
+    j1.setUserStateCookie( j1_user_state ); 
+    logger.info('Save the current Post Browser page to cookie: ' +cookieUserState);
+  </script> -->
+
+  <!-- [INFO   ] [ {{page.url}} ] [Generate HTML}] -->
+  {% include {{create_word_cloud}} word_list=site_tag_list source="tags" skip_words=skip_words %}
+
+  <div class="post-headline"> <h2 id="post-headline" class="mt-2">Posts By Tag</h2></div>
+  <div class="paginator">
+    <ul class="pagination raised-z0">
+      <li class="page-item"><a class="page-link" href="{{navigator | prepend: site.baseurl}}" title="Blog View">Navigator</a></li>
+      <li class="page-item"><a class="page-link" href="{{date_view | prepend: site.baseurl}}" title="View by Date">By Date</a></li>
+      <li class="page-item"><a class="page-link" href="{{category_view | prepend: site.baseurl}}" title="View by Category">By Category</a></li>
+      <li class="page-item"><a class="page-link" href="{{all_view | prepend: site.baseurl}}" title="View All">All Posts</a></li>
+    </ul>
+  </div>
+
+  <div class="post-search-results col-md-10 col-sm-10 col-xs-11">
+
+    <div class="view-description mb-5">{{view_description}}</div>
+
+  {% assign letter_group = letter_group_array[letter_group_counter] %}
+
+  {% for item in (0..site.tags.size) %}{% unless forloop.last %}
+      {% capture this_word %}{{ word_array[item] | strip_newlines }}{% endcapture %}
+
+      {% for skip_word in skip_word_array %}
+        {% if skip_word contains this_word %} {% assign skip = true %} {% else %} {% assign skip = false %} {% endif %}
+        {% if skip %} {% break %} {% endif %}
+      {% endfor %}
+
+      {% if skip %} {% continue %} {% endif %}
+
+      {% assign first_letter = this_word | slice: 0, 1  %}
+      {% assign first_letter = first_letter | downcase %}
+
+      {% if letter_group contains first_letter %}
+        {% comment %} jadams, 2018-01-17: logic seems NOT work. Disabled.
+        {% if letter_group_written == false %}
+          <h2 id="id_{{letter_group}}" class="toc-link mt-5 mb-5"><a title="Back to top" href="#"><i class="fa fa-tags mr-2"></i></a>{{ letter_group | upcase }}</h2>
+          {% assign letter_group_written = true %}
+        {% endif %}
+        ------------------------------------------------------- {% endcomment %}
+      {% else %}
+        {% assign letter_group_counter = letter_group_counter | plus:1 %}
+        {% assign letter_group = letter_group_array[letter_group_counter] %}
+        {% comment %} jadams, 2018-01-17: logic seems NOT work. Added workaround by checking if letter_group has a value {% endcomment %}
+        {% if letter_group %}
+        <h2 id="id_{{letter_group}}" class="toc-link mb-3"><a title="Back to top" href="#"><i class="fa fa-tags mr-2"></i></a>{{ letter_group | upcase }}</h2>
+        {% endif %}
+        {% assign letter_group_written = true %}
+      {% endif %}
+
+      {% comment %}
+      letter_group: {{ letter_group | debug }}
+      this_word: {{ this_word | debug }}
+      first_letter: {{ first_letter | debug }}
+      {% endcomment %}
+
+      <h3 id="{{this_word | replace: '+','_' | replace: ' ','_' | downcase }}" class="toc-link"><a title="Back to top" href="#"><i class="fa fa-tag mr-2"></i></a>{{ this_word }}</h3>
+      <ul class="list-unstyled link-news">
+          {% for post in site.tags[this_word] %}{% if post.title != null %}
+          <li>
+            {% include {{get_category}} post=post %}
+            {% assign category = _category %}
+
+            {% include {{get_category_item}} category=category %}
+            {% include {{select_icon_size}} family=icon_family size=icon_size %}
+            {% assign icon_size = size %}
+
+            <!-- span class="post-category-icon"><i class="{{icon_family}} {{icon_family}}-{{icon_name}} {{icon_size}}"></i></span -->
+            <h4 id="{{ 100000 | rand }}" class="mt-3 mb-2"><a title="Read {{post.title|escape_once}}" href="{{site.baseurl}}{{post.url}}">{{post.title}}</a></h4>
+            <small><time datetime="{{post.date|date_to_xmlschema}}"><i class="fa fa-calendar mr-2"></i>{{post.date|date: "%B %d, %Y"}}</time></small>
+
+            <h5 class="notoc mt-4"><i class="fa fa-quote-left mr-2"></i>{{post.tagline}}</h5>
+            <div class="service">
+              <div class="desc"> <p>{{ post.excerpt }}</p> </div>
+            </div>
+
+          </li>
+          {% endif %}{% endfor %}
+      </ul>
+  {% endunless %}{% endfor %}
+  </div>
+
+<!-- [INFO   ] [j1.page.{{page.title}}                   ] [Save the current page to cookieUserState cookie: {{ browser_page_url }}] -->
+<script type="text/javascript">
+  function setLastPage() {
+    var user_state_last_page = "{{browser_page_url}}";
+    j1.setUserStateCookie( {last_page:user_state_last_page} );
+  }
+  window.onload = setLastPage;
+</script>
+<!--
+<script>
+/* Manage the current page settings */
+$(document).ready(function() {
+    var user_state_last_page = "{{browser_page_url}}";
+    j1.setUserStateCookie( {last_page:user_state_last_page} );
+});
+</script>
+-->

data/lib/starter_web/pages/blog/navigator/index.html

@@ -0,0 +1,41 @@
+---
+layout:                                 blog_archive
+
+title:                                  Article Navigator
+tagline:                                Navigate all Blog Posts throughout this Site
+description:                            Page Generator
+
+tags:                                   [ Blog, Navigator ]
+resources:                              []
+toc:                                    true
+
+pagination:
+  enabled:                              true
+  permalink:                            /page:num/
+
+resource_options:
+  - toccer:
+      collapseDepth:                    2
+
+  - masthead:
+      opacity:                          0.5
+      slides:
+        - url:                          /assets/images/master_header/chuttersnap-1200.jpg
+          alt:                          chuttersnap-1200
+
+regenerate:                             false
+---
+
+<pre>
+
+  This page is created by the layout: {{ page.layout }}.
+
+  If this text is displaywd (instead of the home page expected),
+  something went  wrong with the layout definitions. Check  the
+  output of the Jekyll engine building this site.
+
+  Check the  contents   of folder _layouts. Verify  if the base
+  layout  "{{ page.layout }}" exists  and the  referring  chain
+  (inheritance) is correct.
+
+</pre>

data/lib/starter_web/pages/bookshelf/100_about_jekyll_collections.adoc

@@ -0,0 +1,264 @@
+---
+layout:                                 page
+
+title:                                  Jekyll Collections
+tagline:                                Most powerful but least understood feature
+description:                            Jekyll Collections Overview
+
+toc:                                    true
+permalink:                              /pages/bookshelf/about_collections/
+tags:                                   [ Jekyll, Collections, Feature, Overview ]
+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!