j1_template_mde 2018.4.10

data/lib/starter_web/pages/start/downloads/quickstarter/quickstart.adoc

@@ -0,0 +1,104 @@
+---
+title:                                  Quickstarter
+tagline:                                Starter Bundles available for J1 Template
+description:                            Starter Bundles available for J1 Template
+author:                                 J1 Team
+
+tags:                                   [ Template, Download, Quickstart, Bundle]
+index:                                  [ Windows, Linux, MacOS, OSX]
+
+resources:                              [ lightbox ]
+permalink:                              /pages/start/downloads/quickstart/
+regenerate:                             false 
+---
+
+// NOTE:  General Asciidoc page attributes settings
+//
+:page-liquid:
+
+{% comment %} Liquid procedures
+--------------------------------------------------------------- {% endcomment %}
+{% capture set_env_entry_document %}themes/{{site.template.name}}/procedures/global/set_env_entry_document.proc{%endcapture%}
+
+
+// NOTE: Initialize entry document paths
+//
+{% include {{set_env_entry_document}} init_folders=all %}
+
+// Load tags and urls
+//
+include::{includedir}/attributes.asciidoc[tag=tags]
+include::{includedir}/attributes.asciidoc[tag=urls]
+
+// Additional Asciidoc page attributes goes here
+//
+
+
+Quickstarter are bundles, available for Windows, Linux and MacOS. Those
+bundles contain all software as a installable package needed to run Jekyll,
+to develop a Web using J1 Template. All what is needed in an all-in-one
+application compilation.
+
+== Available Bundles
+
+Creating a fully equipped Jekyll developing enviroment may take a while
+anyway. If you don't want to mixup already installed applications like
+Python, Ruby or NodeJS on your existing OS, you can go for J1 Quickstart.
+
+All the tools and their environments are localized and isolated to the
+application folder of the Quickstarter package and should *not* interfere
+with any already of the installed programs and their resources. Simply by
+setting some environment variables, the system you've prepared already for
+your (Jekyll) Development Environment will be left untouched.
+
+And you're done in 15 minutes.
+
+=== Download a Quickstarter
+
+Find your platform and version for the J1 Quickstarter package you need
+with the following table:
+
+include::{includedir}/tables/100_quickstart_installation_packages.asciidoc[]
+
+Installation instructions can be found for your plattform with the sections
+below.
+
+
+=== J1 Starter for Windows
+
+The J1 team prepared a full development suite for Jekyll on *Windows* that
+can be easily setup. All packages needed for a full featued development
+environment are bundled together; being installed by an Windows installer as
+usual.
+
+pass:[<i class="mdi mdi-windows mdi-2x mdi-md-indigo"></i>]
+Go for link:{j1-starter-windows}[installation instructions here].
+
+
+=== J1 Starter for Linux
+
+If you don't want to mixup already installed applications like Python, Ruby
+or NodeJS on your existing *Linux* OS, you can go for a Quickstart package.
+All the tools and their environments are localized and isolated to the
+application folder of J1 Quickstart and should *not* interfere with any
+already installed programs and their ressources. Simply by setting some
+environment variables, the system you've prepared already for Jekyll will be
+left untouched.
+
+pass:[<i class="mdi mdi-linux mdi-2x mdi-md-indigo"></i>]
+Go for link:{j1-starter-linux}[installation instructions here].
+
+
+=== J1 Starter for MacOS
+
+The availability of Open Source tools and applications are not the strenght
+of Apple products. Yes, Perl, Ruby, Python etc. are available out of the box
+but they are pre-installed in unusable old versions. Upgrading these packages?
+No choice.
+
+You can go for *HomeBrew* to _brew_ what you need - what many people do.
+The same to us - if we're on *MacOS*. But as always: installing an bunch of
+software will take a while. No fun.
+
+pass:[<i class="mdi mdi-apple mdi-2x mdi-md-indigo"></i>]
+Go for link:{j1-starter-macos}[installation instructions here].

data/lib/starter_web/pages/start/kickstarter/web_in_a_day/000_includes/attributes.asciidoc

@@ -0,0 +1,24 @@
+////
+Asciidoc includes
+////
+
+tag::urls[]
+
+:quickstart-download:                             /pages/download
+
+end::urls[]
+
+tag::tags[]
+
+:theme-minima-data:                               "pages/kickstarter/web_in_a_day/jekyll-minima-theme.png, Web site based on Jekyll's Theme minima"
+:theme-uno-data:                                  "pages/kickstarter/web_in_a_day/j1-template-theme.png, J1 Theme Uno"
+:quickstart-windows-data:                         "pages/kickstarter/web_in_a_day/j1-quickstart-windows.png, J1 Quickstart for Windows"
+:j1-page-layout-data:                             "pages/kickstarter/web_in_a_day/j1_layout.png, J1 Page Layout"
+:layout-inheritance-data:                         "pages/kickstarter/web_in_a_day/layout_inheritance.png, Layout Inheritance"
+:content-inheritance-data:                        "pages/kickstarter/web_in_a_day/content_inheritance.png, Content Inheritance"
+:lane-inheritance-data:                           "pages/kickstarter/web_in_a_day/lane_inheritance.png, J1 Lane Inheritance"
+
+
+:figure-caption:                                  Figure
+
+end::tags[]

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

@@ -0,0 +1,268 @@
+---
+title:                          Jekyll
+tagline:                        An Introduction to Collections
+tags:                           [
+                                  backend
+                                ]
+
+description:                    Collections extends Jekyll's post and pages 
+                                publishing functionality, and brings Jekyll's 
+                                zen-like simplicity to all sorts of other types 
+                                of content that aren't dated, but have a relationship 
+                                with one another.
+category:                       Tutorial                                
+---
+
+:doctype:                       article
+
+// URLs
+
+:j-home:                        http://jekyllrb.com/
+:j-pages:                       http://jekyllrb.com/docs/pages/
+:j-posts:                       http://jekyllrb.com/docs/posts/
+:j-data-files:                  http://jekyllrb.com/docs/datafiles/
+:j-collections:                 http://jekyllrb.com/docs/collections
+:j-frontmatter:                 http://jekyllrb.com/docs/frontmatter/
+:j-issue-1941:                  https://github.com/jekyll/jekyll/issues/1941
+
+:gh-choose-a-license:           https://github.com/github/choosealicense.com
+:gh-blog-doc-documents:         https://github.com/blog/1939-how-github-uses-github-to-document-github
+
+:dseed-build-cms-free-websites: https://developmentseed.org/blog/2012/07/27/build-cms-free-websites/
+
+:choose-a-license:              http://choosealicense.com
+:bb-2012-10-01:                 http://ben.balter.com/2012/10/01/welcome-to-the-post-cms-world/ 
+:wp-post-types:                 http://codex.wordpress.org/Post_Types
+:drupal-custom-content:         https://www.drupal.org/node/306792
+              
+
+[.boxShadow]
+====
+Collections are Jekyll's most powerful and simultaneously least understood 
+feature. If you're not familiar with {j-home}[Jekyll, window="blank"], Jekyll
+is  a static site generator. Think of it like a content management system (CMS),
+{dseed-build-cms-free-websites}[without all the complexity] and headache. 
+
+No need to build a giant content-strangling Rube Goldberg machine to manage 
+content, if all you're doing at the end of the day is putting out HTML, 
+Javascript, and CSS, the building blocks of the internet. 
+
+As a result, Jekyll gets out of your way and allows you to concentrate on what 
+truly matters: +
+*{bb-2012-10-01}[Your content, window="blank"]*.
+====
+
+[[posts-and-pages]]
+== Posts and pages
+
+Most Jekyll sites are organized around two types of content: `posts` and `pages`.
+
+* *{j-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.
+* *{j-pages}[Pages, window="blank"]* 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, the site's main page which is used to list posts 
+  or 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 
+{j-issue-1941}[the original pitch, window="blank"], "If people are using blog 
+posts for a non-blog post thing, Jekyll has already failed". That's where 
+Jekyll's {j-collections}[collections, window="blank"] come in.
+
+NOTE: Everything that's *not* a post or a page can be represented as a collection
+
+
+== Collections
+
+Collections add another possibility, or use-case outside of Jekyll's post- and 
+page-publishing functionality; and have the potential to bring Jekyll's zen-like
+simplicity to all sorts of other types of content that aren't dated (as with 
+posts), but have a _relationship_ with each other (hence the name, _collection_). 
+
+If you're familiar with traditional CMS's, you can think of collections like
+WordPress {wp-post-types}[custom post types, window="blank"] or Drupal
+{drupal-custom-content}[custom content types, window="blank"], 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, the _collection_, 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 each other in the sense that they're all 
+cupcakes.
+
+NOTE: Collections are a quite new feature to Jekyll, and according to the 
+official documentation may be subject to change 
+{j-collections}[Jekyll Documentation on Collections, window="blank"]; 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]]
+== 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 {j-data-files}[Jekyll's data support, window="blank"], 
+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/value pairs through a _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 content files (aka .md for Mardown or .adoc for Asciidoc sources) 
+with a _front matter_, not one giant `YAML` data 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 {gh-choose-a-license}[the source, window="blank"] 
+of {choose-a-license}[choosealicense.com, window="blank"] a site which helps to
+explain what are open source licenses about like the MIT or GPL license. There 
+are  pages like _about_ and _terms of service_, but the actual licenses live in a
+{gh-choose-a-license}/tree/gh-pages/_licenses[licenses collection, window="blank"]
+and are displayed via 
+{gh-choose-a-license}/blob/gh-pages/licenses.html[a licensed page, window="blank"].
+
+[[other-use-cases]]
+=== 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]]
+== Using collections
+
+The examples above were a slight simplification. There's one other step to do 
+before a collection can be used: You need to tell Jekyll about it. Going back 
+to our  bakery example above, a `_config.yml` file exists having a section
+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
+{j-frontmatter}[YAML front matter, window="blank"], 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 (per default); at 
+least not individually like you might expect for posts or pages. 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]]
+=== When to use post, page or collection
+
+I like to think the decision looks roughly like this:
+
+------------------------------------------------------------------
+
++--------------------------------------+         +----------------+
+| 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 resume (or talks given, papers written)
+* {gh-blog-doc-documents}[Articles on a support site, window="blank"]
+* 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
+{j-collections}[the formal documentation, window="blank"] for a much more 
+in-depth explanation.
+
+Happy (organized and machine-readable) publishing!

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

@@ -0,0 +1,780 @@
+---
+layout:                 page
+description:            Manage the Site configuration for Jekyll
+title:                  Configuration
+tagline:                Manage the Site Configuration for Jekyll
+group:                  pages
+toc:                    true
+---
+
+:website:               https://jekyllrb.com/
+:revnumber:             3.2.1
+
+
+[.boxShadow]
+====
+Jekyll allows you to configure your sites in any way you can dream up, and it’s
+thanks to the powerful and flexible configuration options that this is possible.
+
+These options can either be specified in a `_config.yml` file placed in your
+site’s root directory, or can be specified as flags for the `jekyll` executable
+on command-line.
+====
+
+== Global Configuration
+
+The table below lists the available settings for Jekyll, and the various
+`options` (specified in the configuration file) and `flags` (specified on the
+command-line) that control them.
+
+[width="100%", cols="8,4",options="header", role="table-responsive mt-3"]
+|=======================================================================
+|Setting |Options and Flags
+a|
+*Site Source*
+
+Change the directory where Jekyll will read files
+
+ a|
+`source: DIR`
+
+`-s, --source DIR`
+
+a|
+*Site Destination*
+
+Change the directory where Jekyll will write files
+
+ a|
+`destination: DIR`
+
+`-d, --destination DIR`
+
+a|
+*Safe*
+
+Disable link:../plugins/[custom plugins, and ignore symbolic links].
+
+ a|
+`safe: BOOL`
+
+`--safe`
+
+a|
+*Exclude*
+
+Exclude directories and/or files from the conversion. These exclusions
+are relative to the site's source directory and cannot be outside the
+source directory.
+
+ |`exclude: [DIR, FILE, ...]`
+
+a|
+*Include*
+
+Force inclusion of directories and/or files in the conversion.
+`.htaccess` is a good example since dotfiles are excluded by default.
+
+ |`include: [DIR, FILE, ...]`
+
+a|
+*Keep files*
+
+When clobbering the site destination, keep the selected files. Useful
+for files that are not generated by jekyll; e.g. files or assets that
+are generated by your build tool. The paths are relative to the
+`destination`.
+
+ |`keep_files: [DIR, FILE, ...]`
+
+a|
+*Time Zone*
+
+Set the time zone for site generation. This sets the `TZ` environment
+variable, which Ruby uses to handle time and date creation and
+manipulation. Any entry from the
+https://en.wikipedia.org/wiki/Tz_database[IANA Time Zone Database] is
+valid, e.g. `America/New_York`. A list of all available values can be
+found
+https://en.wikipedia.org/wiki/List_of_tz_database_time_zones[here]. The
+default is the local time zone, as set by your operating system.
+
+ |`timezone: TIMEZONE`
+
+a|
+*Encoding*
+
+Set the encoding of files by name (only available for Ruby 1.9 or
+later). The default value is `utf-8` starting in 2.0.0, and `nil` before
+2.0.0, which will yield the Ruby default of `ASCII-8BIT`. Available
+encodings can be shown by the command
+`ruby -e 'puts Encoding::list.join("\n")'`.
+
+ |`encoding: ENCODING`
+
+a|
+*Defaults*
+
+Set defaults for link:../frontmatter/[YAML Front Matter] variables.
+
+ |see link:#front-matter-defaults[below]
+|=======================================================================
+
+
+[WARNING]
+====
+Destination folders are cleaned on site builds.
+
+The contents of `<destination>` are automatically cleaned, by default, when
+the site is built. Files or folders that are not created by your site will
+be removed. Some files could be retained by specifying them within the
+`<keep_files>` configuration directive.
+
+Do not use an important location for `<destination>` instead, use it as a
+staging area and copy files from there to your web server.
+====
+
+[[build_command_options]]
+== Build Command Options
+
+[width="100%", cols="8,4",options="header", role="table-responsive mt-3"]
+|=======================================================================
+|Setting |Options and Flags
+a|
+*Regeneration*
+
+Enable auto-regeneration of the site when files are modified.
+
+ |`-w, --[no-]watch`
+
+a|
+*Configuration*
+
+Specify config files instead of using `&#x5F;config.yml` automatically.
+Settings in later files override settings in earlier files.
+
+ |`--config FILE1[,FILE2,...]`
+
+a|
+*Drafts*
+
+Process and render draft posts.
+
+ a|
+`show&#x5F;drafts: BOOL`
+
+`--drafts`
+
+a|
+*Environment*
+
+Use a specific environment value in the build.
+
+ |`JEKYLL&#x5F;ENV=production`
+
+a|
+*Future*
+
+Publish posts or collection documents with a future date.
+
+ a|
+`future: BOOL`
+
+`--future`
+
+a|
+*LSI*
+
+Produce an index for related posts.
+
+ a|
+`lsi: BOOL`
+
+`--lsi`
+
+a|
+*Limit Posts*
+
+Limit the number of posts to parse and publish.
+
+ a|
+`limit&#x5F;posts: NUM`
+
+`--limit&#x5F;posts NUM`
+
+a|
+*Force polling*
+
+Force watch to use polling.
+
+ |`--force&#x5F;polling`
+
+a|
+*Verbose output*
+
+Print verbose output.
+
+ |`-V, --verbose`
+
+a|
+*Silence Output*
+
+Silence the normal output from Jekyll during a build
+
+ |`-q, --quiet`
+
+a|
+*Incremental build*
+
+Enable the experimental incremental build feature. Incremental build
+only re-builds posts and pages that have changed, resulting in
+significant performance improvements for large sites, but may also break
+site generation in certain cases.
+
+ a|
+`incremental: BOOL`
+
+`-I, --incremental`
+
+a|
+*Liquid profiler*
+
+Generate a Liquid rendering profile to help you identify performance
+bottlenecks.
+
+ a|
+`profile: BOOL`
+
+`--profile`
+
+|=======================================================================
+
+
+== Serve Command Options
+
+In addition to the options below, the `serve` sub-command can accept any of
+the options for the `build` sub-command, which are then applied to the site
+build which occurs right before your site is served.
+
+[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`
+|======================================================================
+
+[WARNING]
+====
+Do not use tabs in configuration files.
+
+This will either lead to parsing errors, or Jekyll will revert to the
+default settings. Use spaces instead.
+====
+
+== Custom WEBrick Headers
+
+The Jekyll `serve` command enables an internal Web server - `WEBrick` - to 
+serve your site without the need of an external Webserver (like Apache or Nginx).
+To control the internal server, you can provide custom headers for your site
+by adding them to `&#x5F;config.yml`
+
+[source, yaml]
+--------------
+  # File: _config.yml
+  webrick:
+    headers:
+      My-Header: My-Value
+      My-Other-Header: My-Other-Value
+--------------
+
+=== Defaults
+
+We provide by default `Content-Type` and `Cache-Control` response headers: one
+dynamic in order to specify the nature of the data being served, the other
+static in order to disable caching so that you don't have to fight with
+Chrome's aggressive caching when you are in development mode.
+
+== Set a Jekyll environment
+
+You can specify a Jekyll environment at build time. In the build (or serve)
+arguments, you can specify a Jekyll environment and value. The build will then
+apply this value in any conditional statements in your content.
+
+For example, suppose you set this conditional statement in your code:
+
+[source, liquid]
+--------------
+  {% raw %}
+  {% if jekyll.environment == "production" %}
+     {% include disqus.html %}
+  {% endif %}
+  {% endraw %}
+--------------
+
+When you build your Jekyll site, the content inside the `if` statement won't
+be run unless you also specify a `production` environment in the build
+command, like this:
+
+[source, sh]
+--------------
+  JEKYLL_ENV=production jekyll build
+--------------
+
+Specifying an environment value allows you to make certain content available
+only within specific environments.
+
+The default value for `JEKYLL&#x5F;ENV` is `development`. Therefore if you
+omit `JEKYLL&#x5F;ENV` from the build arguments, the default value will be
+`JEKYLL&#x5F;ENV=development`. Any content inside
+
+[source, liquid]
+--------------
+  {% if jekyll.environment == "development" %}
+--------------
+
+tags will automatically appear in the build.
+
+Your environment values can be anything you want (not just `development` or
+`production`). Some elements you might want to hide in development environments
+include Disqus comment forms or Google Analytics. Conversely, you might want
+to expose an "Edit me in GitHub" button in a development environment but not
+include it in production environments.
+
+By specifying the option in the build command, you avoid having to change
+values in your configuration files when moving from one environment to another.
+
+== Front Matter defaults
+
+Using YAML Front Matter is one way that you can specify configuration in the
+pages and posts for your site. Setting things like a default layout, or
+customizing the title, or specifying a more precise date/time for the post
+can all be added to your page or post front matter.
+
+Often times, you will find that you are repeating a lot of configuration
+options. Setting the same layout in each file, adding the same
+category - or categories - to a post, etc. You can even add custom variables
+like author names, which might be the same for the majority of posts on
+your blog.
+
+Instead of repeating this configuration each time you create a new post or
+page, Jekyll provides a way to set these defaults in the site configuration.
+To do this, you can specify site-wide defaults using the `defaults` key in
+the `&#x5F;config.yml` file in your project's root directory.
+
+The `defaults` key holds an array of scope/values pairs that define what
+defaults should be set for a particular file path, and optionally, a file
+type in that path.
+
+Let's say that you want to add a default layout to all pages and posts in
+your site. You would add this to your `&#x5F;config.yml` file:
+
+[source, yaml]
+--------------
+defaults:
+  - scope:
+      path:       ""        # an empty string here means all files in the project
+    values:
+      layout:     "default"
+--------------
+
+[NOTE]
+====
+Please stop and rerun `jekyll serve` command.
+
+The `&#x5F;config.yml` master configuration file contains global
+configurations and variable definitions that are read once at execution time.
+Changes made to `&#x5F;config.yml` during automatic regeneration
+are not loaded until the next execution.
+
+Note `Data Files` are included and reloaded during automatic regeneration.
+
+====
+
+Here, we are scoping the `values` to any file that exists in the path `scope`.
+Since the path is set as an empty string, it will apply to **all files** in
+your project. You probably don't want to set a layout on every file in your
+project - like css files, for example - so you can also specify a `type` value
+under the `scope` key.
+
+[source, yaml]
+--------------
+defaults:
+  - scope:
+      path:     ""      # an empty string here means all files in the project
+      type:     "posts" # previously `post` in Jekyll 2.2.
+    values:
+      layout:   "default"
+--------------
+
+Now, this will only set the layout for files where the type is `posts`.
+The different types that are available to you are `pages`, `posts`, `drafts`
+or any collection in your site. While `type` is optional, you must specify a
+value for `path` when creating a `scope|values` pair.
+
+As mentioned earlier, you can set multiple scope/values pairs for `defaults`.
+
+[source, yaml]
+--------------
+defaults:
+  - scope:
+      path:     ""
+      type:     "posts"
+    values:
+      layout:   "my-site"
+
+  - scope:
+      path:     "projects"
+      type:     "pages" # previously `page` in Jekyll 2.2.
+    values:
+      layout:   "project" # overrides previous default layout
+      author:   "Mr. Hyde"
+--------------
+
+With these defaults, all posts would use the `my-site` layout. Any html files
+that exist in the `projects/` folder will use the `project` layout, if it
+exists. Those files will also have the `page.author` liquid variable
+set to `Mr. Hyde`.
+
+[source, yaml]
+--------------
+collections:
+  - my_collection:
+      output: true
+
+defaults:
+  - scope:
+      path:       ""
+      type:       "my_collection"   # a collection in your site, in plural form
+    values:
+      layout:     "default"
+--------------
+
+In this example, the `layout` is set to `default` inside the collection with 
+the name `my&#x5F;collection`.
+
+=== Precedence
+
+Jekyll will apply all of the configuration settings you specify in the
+`defaults` section of your `&#x5F;config.yml` file. However, you can choose
+to override settings from other scope/values pair by specifying a more specific
+path for the scope.
+
+You can see that in the second to last example above. First, we set the default
+layout to `my-site`. Then, using a more specific path, we set the default
+layout for files in the `projects/` path to `project`. This can be done with
+any value that you would set in the page or post front matter.
+
+Finally, if you set defaults in the site configuration by adding a `defaults`
+section to your `&#x5F;config.yml` file, you can override those settings in a
+post or page file. All you need to do is specify the settings in the post or
+page front matter.
+
+For example:
+
+[source, yaml]
+--------------
+# ~/_config.yml
+...
+defaults:
+  - scope:
+      path:       "projects"
+      type:       "pages"
+    values:
+      layout:     "project"
+      author:     "Mr. Hyde"
+      category:   "project"
+...
+--------------
+
+[source, yaml]
+--------------
+# ~/projects/foo_project.md
+---
+author: "John Smith"
+layout: "foobar"
+---
+The post text goes here...
+--------------
+
+The `projects/foo&#x5F;project.md` would have the `layout` set to `foobar` 
+instead of `project` and the `author` set to `John Smith` instead of `Mr. Hyde` 
+when the site is built.
+
+== Default Configuration
+
+Jekyll runs with the following configuration options by default. Alternative
+settings for these options can be explicitly specified in the configuration
+file or on the command-line.
+
+[WARNING]
+====
+There are two unsupported kramdown options.
+
+Please note that both `remove&#x5F;block&#x5F;html&#x5F;tags` and
+`remove&#x5F;span&#x5F;html&#x5F;tags` are currently *unsupported*
+in Jekyll due to the fact that they are not included within the kramdown
+HTML converter.
+====
+
+[source, yaml]
+--------------
+# Where things are
+#
+source:           .
+destination:      ./_site
+plugins_dir:      _plugins
+layouts_dir:      _layouts
+data_dir:         _data
+includes_dir:     _includes
+collections:
+  posts:
+    output:       true
+
+# Handling Reading
+#
+safe:             false
+include:          [".htaccess"]
+exclude:          []
+keep_files:       [".git", ".svn"]
+encoding:         "utf-8"
+markdown_ext:     "markdown,mkdown,mkdn,mkd,md"
+
+# Filtering Content
+#
+show_drafts:      null
+limit_posts:      0
+future:           false
+unpublished:      false
+
+# Plugins
+#
+whitelist:        []
+gems:             []
+
+# Conversion
+#
+markdown:         kramdown
+highlighter:      rouge
+lsi:              false
+excerpt_separator: "\n\n"
+incremental:      false
+
+# Serving
+#
+detach:           false
+port:             4000
+host:             127.0.0.1
+baseurl:          ""          # does not include hostname
+show_dir_listing: false
+
+# Outputting
+#
+permalink:        date
+paginate_path:    /page:num
+timezone:         null
+
+quiet:            false
+verbose:          false
+defaults:         []
+
+liquid:
+  error_mode:     warn
+
+# Markdown Processors
+#
+rdiscount:
+  extensions:     []
+
+redcarpet:
+  extensions:     []
+
+kramdown:
+  auto_ids:       true
+  footnote_nr:    1
+  entity_output:  as_char
+  toc_levels:     1..6
+  smart_quotes:   lsquo,rsquo,ldquo,rdquo
+  input:          GFM
+  hard_wrap:      false
+  footnote_nr:    1
+--------------
+
+== Liquid Options
+
+Liquid's response to errors can be configured by setting `error&#x5F;mode`.
+The options are
+
+- `lax` --- Ignore all errors.
+- `warn` --- Output a warning on the console for each error.
+- `strict` --- Output an error message and stop the build.
+
+== Markdown Options
+
+The various Markdown renderers supported by Jekyll sometimes have extra options
+available.
+
+=== Redcarpet
+
+Redcarpet can be configured by providing an `extensions` sub-setting, whose
+value should be an array of strings. Each string should be the name of one of
+the `Redcarpet::Markdown` class's extensions; if present in the array, it will
+set the corresponding extension to `true`.
+
+Jekyll handles two special Redcarpet extensions:
+
+- `no&#x5F;fenced&#x5F;code&#x5F;blocks` --- By default, Jekyll sets the
+`fenced&#x5F;code&#x5F;blocks` extension (for delimiting code blocks with
+triple tildes or triple backticks) to `true`, probably because GitHub's eager
+adoption of them is starting to make them inescapable. Redcarpet's normal
+`fenced&#x5F;code&#x5F;blocks` extension is inert when used with Jekyll;
+instead, you can use this inverted version of the extension for disabling
+fenced code.
+
+Note that you can also specify a language for highlighting after the first
+delimiter:
+
+[source, ruby]
+--------------
+  # ...ruby code
+--------------
+
+With both fenced code blocks and highlighter enabled, this will statically
+highlight the code; without any syntax highlighter, it will add a
+`class="LANGUAGE"` attribute to the `<code>` element, which can be used as a
+hint by various JavaScript code highlighting libraries.
+
+- `smart` --- This pseudo-extension turns on SmartyPants, which converts
+  straight quotes to curly quotes and runs of hyphens to em (`---`) and en (`--`) dashes.
+
+All other extensions retain their usual names from Redcarpet, and no renderer
+options aside from `smart` can be specified in Jekyll. [A list of available
+extensions can be found in the Redcarpet README file.][redcarpet&#x5F;extensions]
+Make sure you're looking at the README for the right version of
+Redcarpet: Jekyll currently uses v3.2.x. The most commonly used
+extensions are:
+
+- `tables`
+- `no&#x5F;intra&#x5F;emphasis`
+- `autolink`
+
+[redcarpet&#x5F;extensions]: https://github.com/vmg/redcarpet/blob/v3.2.2/README.markdown#and-its-like-really-simple-to-use
+
+### Custom Markdown Processors
+
+If you're interested in creating a custom markdown processor, you're in luck! Create a new class in the `Jekyll::Converters::Markdown` namespace:
+
+[source, ruby]
+--------------
+  class Jekyll::Converters::Markdown::MyCustomProcessor
+    def initialize(config)
+      require 'funky&#x5F;markdown'
+      @config = config
+    rescue LoadError
+      STDERR.puts 'You are missing a library required for Markdown. Please run:'
+      STDERR.puts '  $ [sudo] gem install funky&#x5F;markdown'
+      raise FatalException.new("Missing dependency: funky&#x5F;markdown")
+    end
+
+    def convert(content)
+      ::FunkyMarkdown.new(content).convert
+    end
+  end
+--------------
+
+Once you've created your class and have it properly set up either as a plugin
+in the `&#x5F;plugins` folder or as a gem, specify it in your `&#x5F;config.yml`:
+
+[source, yaml]
+--------------
+  markdown: MyCustomProcessor
+--------------
+
+== Incremental Regeneration
+
+Incremental regeneration helps shorten build times by only generating documents
+and pages that were updated since the previous build. It does this by keeping
+track of both file modification times and inter-document dependencies in the
+`.jekyll-metadata` file.
+
+[WARNING]
+====
+Incremental regeneration is still an experimental feature.
+
+While incremental regeneration will work for the most common cases, it will
+not work correctly in every scenario. Please be extremely cautious when
+using the feature, and report any problems not listed below by
+<a href="https://github.com/jekyll/jekyll/issues/new">opening an issue on GitHub</a>.
+====
+
+Under the current implementation, incremental regeneration will only generate a
+document or page if either it, or one of its dependencies, is modified. 
+Currently, the only types of dependencies tracked are includes (using the
+`{% include %}` tag) and layouts. This means that plain references to other 
+documents (for example, the common case of iterating over `site.posts` in a 
+post listings page) will not be detected as a dependency.
+
+To remedy some of these shortfalls, putting `regenerate: true` in the 
+front-matter of a document will force Jekyll to regenerate it regardless of 
+whether it has been modified. Note that this will generate the specified 
+document only; references to other documents' contents will not work since 
+they won't be re-rendered.
+
+Incremental regeneration can be enabled via the `--incremental` flag (`-i` for
+short) from the command-line or by setting `incremental: true` in your
+configuration file.