j1-template 2021.1.29 → 2021.2.0

data/lib/starter_web/pages/public/asciidoc_skeletons/multi-document/_includes/documents/100_chapter.asciidoc

@@ -1,53 +1,861 @@
-// ~/document_base_folder/_includes/documents
-// Sublevel Entry Document: 100_chapter.asciidoc
-// -----------------------------------------------------------------------------
+== Configuration
 
-== Chapter 1
+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.
 
-J1 Template support popular icons font sets out-of-the-box:
+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.
 
-* link:{url-mdi--home}[Material Design Icons, {browser-window--new}] (MDI)
-* link:{url-fontawesome--home}[FontAwesome Icons V5, {browser-window--new}] (FA)
-* link:{url-iconify--home}[Iconify Icons, {browser-window--new}] (II)
+=== Global Configuration
 
-The icon sets MDI and FA are very good in design and have a rich set of
-different icons for many categories used for the Web. See below some details
-for link:{url-roundtrip--mdi-icons}[Material Design Icons, {browser-window--new}]
-and link:{url-roundtrip--fontawesome-icons}[FontAwesome Icons, {browser-window--new}].
+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.
 
-Iconify icons is not a locally stored icon-set like MDI or FA. All icons are
-loaded over the Internet using the so-called *Unified OpenSource Icon
-Framework*. See section link:{url-roundtrip--iconify-icons}[Iconify Icons, {browser-window--new}]
-for more information.
+[width="100%", cols="6,6", options="header", role="table-responsive mt-3"]
+|=======================================================================
+|Setting |Options and Flags
+a|
+*Site Source*
 
-=== Section
+Change the directory where Jekyll will read files
 
-The primary icon-set for J1 Template is link:{url-mdi--home}[Material Design Icons, {browser-window--new}],
-because it is extremely rich set providing more than 5900+ icons for the
-current version (v5.9.55). From a design perspective, _MDI_ has an excellen
-*Material Design* support an comes with the original icon set created by
-_Google_ build-in.
+ a|
+`source: DIR`
 
-_Material Design Icons_ (MDI) is a beneficial design resource for Web Design
-that is based on _Google_'s Material Design. _MDI_ is a community-driven
-project to create an increased number of icons based on _Google_'s official repository
-and MD style specification.
+`-s, --source DIR`
 
-==== Subsection
+a|
+*Site Destination*
 
-_MDI_ is a growing collection to allow designers and developers targeting
-various platforms to download icons in the format, color and size they need
-for any project. The repo contains today 2100+ icons plus converted icons from
-the official set created by _Google_.
+Change the directory where Jekyll will write files
 
-// include::{documentdir}/tables/110_material_design_icons.asciidoc
-// include::{tabledir}/110_material_design_icons.asciidoc
-include::./tables/110_material_design_icons.asciidoc[]
+ a|
+`destination: DIR`
 
-NOTE: Using Material Design Icons with Asciidoc is quite easy as an inline
-macro `mdi:` is available to place icons where ever you want. See more about
-this in section
-link:{url-roundtrip--asciidoc-extensions}#icon-fonts[Asciidoc Extensions, {browser-window--new}]
+`-d, --destination DIR`
 
-_J1 Template_ supports the full set of _MDI_ for the Web (Webfont, WOFF). The
-icon set is fully integrated and can be used out-of-the-box.
+a|
+*Safe*
+
+Disable 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 YAML Front Matter variables.
+
+ |see 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
+
+[width="100%", cols="6,6", 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 `_config.yml` automatically.
+Settings in later files override settings in earlier files.
+
+ |`--config FILE1[,FILE2,...]`
+
+a|
+*Drafts*
+
+Process and render draft posts.
+
+ a|
+`show_drafts: BOOL`
+
+`--drafts`
+
+a|
+*Environment*
+
+Use a specific environment value in the build.
+
+ |`JEKYLL_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_posts: NUM`
+
+`--limit_posts NUM`
+
+a|
+*Force polling*
+
+Force watch to use polling.
+
+ |`--force_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="6,6", 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 `_config.yml`
+
+[source, yaml]
+--------------
+  # File: _config.yml
+  webrick:
+    headers:
+      My-Header: My-Value
+      My-Other-Header: My-Other-Value
+--------------
+
+NOTE: Jekyll 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*.
+
+== Jekyll Environment
+
+=== 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="6,6", options="header", role="table-responsive mt-3"]
+|=======================================================================
+|File / Directory |Description
+|`_config.yml`
+|Stores 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 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 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 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 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 sites already using Jekyll if you're curious
+to see how they're laid out.
+|=======================================================================
+
+=== 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_ENV` is `development`. Therefore if you
+omit `JEKYLL_ENV` from the build arguments, the default value will be
+`JEKYLL_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 `_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 `_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 `_config.yml` master configuration file contains global
+configurations and variable definitions that are read once at execution time.
+Changes made to `_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_collection`.
+
+==== Precedence
+
+Jekyll will apply all of the configuration settings you specify in the
+`defaults` section of your `_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 `_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]
+--------------
+# In _config.yml
+...
+defaults:
+  - scope:
+    path:       "projects"
+    type:       "pages"
+    values:
+      layout:   "project"
+      author:   "Mr. Hyde"
+      category: "project"
+...
+--------------
+
+[source, yaml]
+--------------
+# In projects/foo_project.md
+---
+author: "John Smith"
+layout: "foobar"
+---
+The post text goes here...
+--------------
+
+The `projects/foo_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_block_html_tags` and
+`remove_span_html_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_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_fenced_code_blocks` --- By default, Jekyll sets the
+`fenced_code_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_code_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_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_intra_emphasis`
+- `autolink`
+
+[redcarpet_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_markdown'
+      @config = config
+    rescue LoadError
+      STDERR.puts 'You are missing a library required for Markdown. Please run:'
+      STDERR.puts '  $ [sudo] gem install funky_markdown'
+      raise FatalException.new("Missing dependency: funky_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 `_plugins` folder or as a gem, specify it in your `_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
+{uri-jekyll-submit-issue}[opening an issue on GitHub].
+====
+
+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.