j1_template_mde 2018.4.10

data/lib/starter_web/pages/start/kickstarter/web_in_a_day/000_includes/documents/directory_structure.adoc

@@ -0,0 +1,106 @@
+---
+title:                  Directory structure of Jekyll
+tagline:                Manage and Create Web sites with Jekyll
+description:            Manage and Create Web sites with Jekyll
+---
+
+:website:               https://jekyllrb.com/
+:revnumber:             3.2.1
+
+== Folder structure
+
+Jekyll is, at its core, a text transformation engine. The concept behind the
+system is this: you give it text written in your favorite markup language, be
+that Markdown, Textile, or just plain HTML, and it churns that through a layout
+or a series of layout files. Throughout that process you can tweak how you want
+the site URLs to look, what data gets displayed in the layout, and more. This
+is all done through editing text files; the static web site is the final
+product.
+
+A basic Jekyll site usually looks something like this:
+
+[source, sh]
+----
+.
+├── _config.yml
+├── _drafts
+|   ├── begin-with-the-crazy-ideas.textile
+|   └── on-simplicity-in-technology.markdown
+├── _includes
+|   ├── footer.html
+|   └── header.html
+├── _layouts
+|   ├── default.html
+|   └── post.html
+├── _posts
+|   ├── 2007-10-29-why-every-programmer-should-play-nethack.textile
+|   └── 2009-04-26-barcamp-boston-4-roundup.textile
+├── _data
+|   └── members.yml
+├── _site
+├── .jekyll-metadata
+└── index.html
+----
+
+== Dirs and Files
+
+An overview of what each of these does:
+
+[width="100%", cols="4,8",options="header", role="table-responsive mt-3"]
+|=======================================================================
+|File / Directory |Description
+|`_config.yml` |Stores link:../configuration/[configuration] data. Many
+of these options can be specified from the command line executable but
+it's easier to specify them here so you don't have to remember them.
+
+|`_drafts` |Drafts are unpublished posts. The format of these files is
+without a date: `title.MARKUP`. Learn how to link:../drafts/[work with
+drafts].
+
+|`_includes` |These are the partials that can be mixed and matched by
+your layouts and posts to facilitate reuse. The liquid tag
+`{% include file.ext %}` can be used to include the
+partial in `_includes/file.ext`.
+
+|`_layouts` |These are the templates that wrap posts. Layouts are chosen
+on a post-by-post basis in the link:../frontmatter/[YAML Front Matter],
+which is described in the next section. The liquid tag
+`{{ content }}` is used to inject content into the
+web page.
+
+|`_posts` |Your dynamic content, so to speak. The naming convention of
+these files is important, and must follow the format:
+`YEAR-MONTH-DAY-title.MARKUP`. The link:../permalinks/[permalinks] can
+be customized for each post, but the date and markup language are
+determined solely by the file name.
+
+|`_data` |Well-formatted site data should be placed here. The Jekyll
+engine will autoload all YAML files in this directory (using either the
+`.yml`, `.yaml`, `.json` or `.csv` formats and extensions) and they will
+be accessible via `site.data`. If there's a file `members.yml` under the
+directory, then you can access contents of the file through
+`site.data.members`.
+
+|`_site` |This is where the generated site will be placed (by default)
+once Jekyll is done transforming it. It's probably a good idea to add
+this to your `.gitignore` file.
+
+|`.jekyll-metadata` |This helps Jekyll keep track of which files have
+not been modified since the site was last built, and which files will
+need to be regenerated on the next build. This file will not be included
+in the generated site. It's probably a good idea to add this to your
+`.gitignore` file.
+
+|`index.html` and other HTML, Markdown, Textile files |Provided that the
+file has a link:../frontmatter/[YAML Front Matter] section, it will be
+transformed by Jekyll. The same will happen for any `.html`,
+`.markdown`, `.md`, or `.textile` file in your site's root directory or
+directories not listed above.
+
+|Other Files/Folders |Every other directory and file except for those
+listed aboveÔÇösuch as `css` and `images` folders, `favicon.ico` files,
+and so forthÔÇöwill be copied verbatim to the generated site. There are
+plenty of link:../sites/[sites already using Jekyll] if you're curious
+to see how they're laid out.
+|=======================================================================
+

data/lib/starter_web/pages/start/kickstarter/web_in_a_day/000_includes/documents/jekyll_commandline.adoc

@@ -0,0 +1,94 @@
+---
+layout:                 page
+description:            Jekyll commandline parameters
+title:                  Jekyll Commandline
+tagline:                Available Jekyll commandline parameters
+group:                  pages
+toc:                    true
+---
+
+:website:               https://jekyllrb.com/docs/posts/
+:revnumber:             3.2.1
+
+//Ref
+:liquid-date-formats:   http://docs.shopify.com/themes/liquid-documentation/filters/additional-filters#date
+
+
+[.boxShadow]
+====
+Not everything is a post or a page. Maybe you want to document the various
+methods in your open source project, members of a team, or talks at a
+conference.
+
+Collections allow you to define a new type of document that behave like Pages
+or Posts do normally, but also have their own unique properties and namespace.
+====
+
+
+== Parameters
+
+
+
+[width="100%", cols="8,4",options="header", role="table-responsive mt-3"]
+|======================================================================
+|Setting |Options and Flags
+a|
+*Local Server Port*
+
+Listen on the given port.
+
+ a|
+`port: PORT`
+
+`--port PORT`
+
+a|
+*Local Server Hostname*
+
+Listen at the given hostname.
+
+ a|
+`host: HOSTNAME`
+
+`--host HOSTNAME`
+
+a|
+*Base URL*
+
+Serve the website from the given base URL
+
+ a|
+`baseurl: URL`
+
+`--baseurl URL`
+
+a|
+*Detach*
+
+Detach the server from the terminal
+
+ a|
+`detach: BOOL`
+
+`-B, --detach`
+
+a|
+*Skips the initial site build.*
+
+Skips the initial site build which occurs before the server is started.
+
+ |`--skip-initial-build`
+a|
+*X.509 (SSL) Private Key*
+
+SSL Private Key.
+
+ |`--ssl-key`
+a|
+*X.509 (SSL) Certificate*
+
+SSL Public certificate.
+
+ |`--ssl-cert`
+|======================================================================
+

data/lib/starter_web/pages/start/kickstarter/web_in_a_day/000_includes/documents/layout_inheritance.adoc

@@ -0,0 +1,305 @@
+---
+layout:                       page
+description:                  Jekyll-style template inheritance
+title:                        Template Inheritance
+tagline:                      Jekyll-style template inheritance based on layouts
+group:                        pages
+toc:                          true
+---
+
+:website:                     https://www.elastic.co/
+:license:                     Apache License, Version 2.0
+:revdate:                     2015
+:revnumber:                   4.2.2
+
+//Ref
+// {% raw %} Disable from processing to preserve the liquid markup's in the document
+
+
+[.boxShadow]
+====
+The most powerful – and for sure the most complex – part of a template engine 
+is template *inheritance*. Template inheritance allows to build base *skeleton* 
+templates (for the different types of web page) that contains all the common 
+elements. These base templates defines *blocks* that *child* templates can 
+overwride.
+
+Template systems like Django's template engine (for Python) fully supports 
+template inheritance - unfortuneatly Liquid (that seems inspired from Django) 
+does *NOT*. Bad news? 
+
+No, not that bad. Read the following how to create building blocks based on 
+Jekyll's layouts and layout inheritance.
+====
+
+To create large sites, consists in complex pages, it is fundamental to *not repeat
+yourselves* in creating the *building blocks*. Therefor, the Jekyll engine 
+supports template inheritance based on the *layout* system introduces by Jekyll.
+Let call this typeof inheritance *layout* inheritance. 
+
+.base template
+[source, html]
+--------------
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <link rel="stylesheet" href="style.css" />
+    <title>{% block title %}My amazing Web site{% endblock %}</title>
+</head>
+
+<body>
+    <div id="sidebar">
+        {% block sidebar %}
+        <ul>
+            <li><a href="/">Home</a></li>
+            <li><a href="/blog/">Blog</a></li>
+        </ul>
+        {% endblock %}
+    </div>
+
+    <div id="content">
+        {% block content %}{% endblock %}
+    </div>
+</body>
+</html>
+--------------
+
+This `base` template, which we’ll call `base.html`, defines a simple HTML
+skeleton document that you might use for a simple two-column page. It’s
+the job of `child` templates to fill in the empty blocks with content.
+
+In this example, the `block` tag defines three blocks that can be *overwritten*
+by child templates:
+
+  * title
+  * sidebar
+  * content
+
+All the `block` tag does is to instruct the template engine that a `child` 
+template may override those portions of the `base` template.
+
+A `child` template might look like this:
+
+.child template
+[source, html]
+--------------
+{% extends 'base.html' %}
+
+{% block title %}My amazing Blog{% endblock %}
+
+{% block content %}
+{% for entry in blog_entries %}
+    <h2>{{ entry.title }}</h2>
+    <p>{{ entry.body }}</p>
+{% endfor %}
+{% endblock %}
+--------------
+
+The `extends` tag is the key here. It tells the template engine that this 
+template *extends* another template. When the template system evaluates the
+`child` template, first it's parent is located – in this case `base.html`.
+
+At that point, the template engine parses the three `block` tags in the 
+`base.html` template. These blocks are *replaced* by the contents of the 
+`child template`. Depending on the value of `blog entries`, the output 
+might look like:
+
+.HTML output
+[source, html]
+--------------
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <link rel="stylesheet" href="style.css" />
+    <title>My amazing Blog</title>
+</head>
+
+<body>
+    <div id="sidebar">
+        <ul>
+            <li><a href="/">Home</a></li>
+            <li><a href="/blog/">Blog</a></li>
+        </ul>
+    </div>
+
+    <div id="content">
+        <h2>Entry one</h2>
+        <p>This is my first entry.</p>
+
+        <h2>Entry two</h2>
+        <p>This is my second entry.</p>
+    </div>
+</body>
+
+</html>
+--------------
+
+Note that since the child template didn't define the `sidebar` block,
+the value from the parent template is used instead. Content within a
+`{% block %}` tag in a parent template is always used as a *fallback*.
+
+You can use as many levels of inheritance as needed. One common way of
+using inheritance is the following *three-level* approach:
+
+  * Create a `base.html` template that holds the main look-and-feel of
+    your site.
+    
+  * Create a `base_SECTIONNAME.html` template for each `section` of your
+    site. For example, `base_news.html` and `base_sports.html`. These `child`
+    templates *extends* the `base.html` template and include section-specific
+    styles/design.
+    
+  * Create individual templates for each type of page, such as a news
+    article or blog entry. These templates extend the appropriate section
+    template.
+
+This approach maximizes code reuse and makes it easy to add items to shared 
+content areas, such as section-wide navigation.
+
+[NOTE]
+====
+Note, that you can’t define multiple `block` tags with the *same name*
+in the *same template*. This limitation exists because a block tag works in
+*both* directions. That is, a block tag doesn’t just provide a hole to fill – 
+it also defines the content that fills the hole in the __parent__. If there 
+were two similarly-named `block` tags in a template, that template’s parent 
+wouldn’t know which one of the blocks’ content to use.
+====
+
+== Working with inheritance
+
+Here some tips for working with inheritance:
+
+  * If you use `{% extends %}` in a template, it must be the *first* tag in 
+    that template. Template inheritance won’t work, otherwise.
+    
+  * More `{% block %}` tags in your base templates are better. Remember, child
+    templates don’t have to define all parent blocks, so you can fill in 
+    reasonable defaults in a number of blocks, then only define the ones you 
+    need later. It’s better to have more hooks than fewer.
+
+  * If you find yourself duplicating content in a number of templates, it
+    probably means you should move that content to a `{% block %}` in a
+    parent template.
+    
+  * If you need to get the content of the block from the `parent` template,
+    the `{{ block.super }}` variable will do the trick. This is useful if
+    you want to add to the contents of a parent block instead of completely
+    overriding it. Data inserted using `{{ block.super }}` will not be
+    automatically escaped, since it was already escaped, if necessary, in 
+    the parent template.
+  
+  * For better readability, you can (optionally) give a *name* to your
+    `{% endblock %}` tag. For example:
++
+----------------------
+{% block content %}
+...
+{% endblock content %}
+----------------------
++
+In larger templates, this technique helps you see which `{% block %}`
+tags are being closed.
+
+
+== Stackoverflow
+
+See: http://stackoverflow.com/questions/13086569/jekyll-templates-using-django-like-liquid-blocks-inheritance
+
+
+I'm not sure this is ever going to work within Jekyll. I might be wrong, 
+but here's my reasoning:
+
+Each page is rendered out using do_layout in 
+https://github.com/mojombo/jekyll/blob/master/lib/jekyll/convertible.rb
+
+This works recursively - it processes the content of the page, then processes 
+the page's layout, then that layout's layout and so on and so forth, passing 
+the YAML variables up the chain (so they're always available in parent 
+templates as {{ page.whatever}}).
+
+This means that the only things which get passed up are the YAML values, and 
+whatever the value of 'content' is after it has been processed by Liquid. I 
+don't know how it is done elsewhere, but that seems incompatible with the 
+idea of blocks, as they'd require you to pass up the two blocks separately.
+
+Fundamentally, it seems to me that the issue is that Jekyll already has a 
+simple form of inheritance - via the "layout" attribute that you can give 
+to a layout. Fundamentally, I think that this is compatible with liquid-templating.
+
+All that said, I'm not sure that you've exhausted the limits of using YAML, 
+_includes, and template logic. If you're at the point of putting Django 
+style blocks into your content, why not just do something like this:
+
+.Content
+[source, html]
+--------------
+---
+title: some title
+secondary_content: |
+    Here is some *secondary* content that will be [markdownified](http://example.com).
+    It can run to multiple lines and include
+    * Lists
+    * Good things
+    * Etc
+---
+
+And here is the main content, as per usual
+--------------
+
+.Template
+[source, html]
+--------------
+<html>
+<article>
+    <h1>{{ page.title }}</h1>
+    {{ content }}
+</article>
+<aside>
+{{ page.secondary_content | markdownify}}
+</aside>
+--------------
+
+If you wanted to keep your templates clean, and have different content for 
+different types of pages, you could use various includes:
+
+._includes/sidebar_negotiation.html
+[source, bash]
+--------------
+{% if page.type = 'foo' %}
+{% include sidebar_foo.html %}
+{% else if page.type = 'bar' %}
+{% include sidebar_bar.html %}
+{% endif %}
+--------------
+
+And then put your page type specific stuff in those files. Obviously you could
+include it directly, but it is probably nice to abstract it out. Those includes
+will get all of the variables in the YAML.
+
+If none of this is a win, you could always try Hyde: http://hyde.github.com/ 
+which is written in Python, uses Jinja2 (basically Django templates++), and 
+does the same sort of thing.
+
+.comment
+----
+I just tested further, and found that although liquid-inheritance works fine 
+on layouts, it fails when you get to actual content pages - which I think 
+is where your problem arises (which. But as I said - once you get down to 
+a specific piece of content, I'm still convinced that YAML is a better way 
+to include ancillary content than putting blocks in your content area... 
+– heliotrope Oct 31 '12 at 21:11
+----
+
+.comment
+----
+YAML is definitely the best way to do it, but it becomes unnecessarily complex
+if most of your content is simply large blocks of inseparable HTML. Aside 
+from a title, there isn't a great deal of raw data that I really need to process.
+I just need to insert large chunks of HTML into specific, non-contiguous 
+regions of the page. Describing that HTML in YAML is clumsy and unmaintainable.
+– xcession Nov 1 '12 at 10:08 
+----
+
+
+// {% endraw %}