j1-template 2023.2.7 → 2023.3.1

data/lib/starter_web/pages/public/learn/core_web_vitals/_includes/attributes.asciidoc

@@ -0,0 +1,59 @@
+// ~/document_base_folder/000_includes
+//  Asciidoc attribute includes:                 attributes.asciidoc
+// -----------------------------------------------------------------------------
+
+// URLs - Internal references and/or sources on the Internet
+// -----------------------------------------------------------------------------
+tag::urls[]
+
+:url-j1--home:                                    https://jekyll.one/
+
+end::urls[]
+
+
+// FOOTNOTES, global asciidoc attributes (variables)
+// -----------------------------------------------------------------------------
+tag::footnotes[]
+end::footnotes[]
+
+
+// Tags - Asciidoc attributes used internally
+// -----------------------------------------------------------------------------
+tag::tags[]
+end::tags[]
+
+
+// Data - Data elements for Asciidoctor extensions
+// -----------------------------------------------------------------------------
+tag::data[]
+
+:data-image--core_web_vitals_best:               "assets/images/pages/core_web_vitals/core_web_vitals_best.jpg, Excellent performance values (Lighthouse)"
+:data-image--core_web_vitals_best_full:          "assets/images/pages/core_web_vitals/core_web_vitals_best_full.jpg, Excellent performance values (Lighthouse)"
+
+end::data[]
+
+
+// Images - Images from local include/images folder
+// -----------------------------------------------------------------------------
+tag::images[]
+end::images[]
+
+
+// PRODUCTS, local product information (e.g. release)
+// -----------------------------------------------------------------------------
+tag::products
+
+:license:                                         e.g. Apache License, Version 2.0
+:revdate:                                         e.g. 2018
+:revnumber:                                       e.g. 1.2.3
+
+end::products[]
+
+
+// AUTHORS, local author information (e.g. article)
+// -----------------------------------------------------------------------------
+tag::authors[]
+
+:uri-author-xxx:                                  https://xxx
+
+end::authors[]

data/lib/starter_web/pages/public/learn/core_web_vitals/_includes/documents/100_chapter.asciidoc

@@ -0,0 +1,541 @@
+== Configuration
+
+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.
+
+include::../tables/global_configuration_options.asciidoc[]
+
+[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
+
+include::../tables/build_command_options.asciidoc[]
+
+=== 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.
+
+include::../tables/serve_command_options.asciidoc[]
+
+[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
+----
+
+=== Files and Folders
+
+An overview of what each of these does:
+
+include::../tables/files_and_folders.asciidoc[]
+
+=== 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.

data/lib/starter_web/pages/public/learn/core_web_vitals/_includes/documents/200_chapter.asciidoc

@@ -0,0 +1,33 @@
+== Jekyll Variables
+
+Jekyll traverses your site looking for files to process. Any files with `YAML
+front matter` are subject to processing. For each of these files, Jekyll makes
+a variety of data available via the `Liquid templating system`.
+
+The following is a reference of the available data.
+
+=== Global Variables
+
+include::../tables/global_variables.asciidoc[]
+
+=== Site Variables
+
+include::../tables/site_variables.asciidoc[]
+
+=== Page Variables
+
+include::../tables/page_variables.asciidoc[]
+
+[TIP]
+====
+Use Custom Front Matter
+
+Any custom front matter that you specify will be available under `page`.
+For example, if you specify `custom_css: true` in a pages front matter,
+that value will be available as `page.custom_css`.
+
+If you specify front matter in a layout, access that via `layout`. For
+example, if you specify `class: full_page` in a pages front matter,
+that value will be available as `layout.class` in the layout and its
+parents.
+====

data/lib/starter_web/pages/public/learn/core_web_vitals/_includes/tables/build_command_options.asciidoc

@@ -0,0 +1,72 @@
+
+.Build Command Options
+[cols="2a,2a,2a,6a", width="100%", options="header", role="rtable mt-4"]
+|===
+|Setting |Option |Flag |Description
+
+|*Regeneration*
+|`na`
+|`-w, --[no-]watch`
+|Enable auto-regeneration of the site when files are modified.
+
+|*Configuration*
+|`na`
+|`--config FILE1 [,FILE2, ..]`
+|Specify config files instead of using `_config.yml` automatically.
+Settings in later files override settings in earlier files.
+
+|*Drafts*
+|`show_drafts: BOOL`
+|`--drafts`
+|Process and render draft posts.
+
+|*Environment*
+|`na`
+|`na`
+|Use a specific environment value `JEKYLL_ENV=production` in the build.
+
+|*Future*
+|`future: BOOL`
+|`--future`
+|Publish posts or collection documents with a future date.
+
+|*LSI*
+|`lsi: BOOL`
+|`--lsi`
+|Produce an index for related posts.
+
+|*Limit Posts*
+|`limit_posts: NUM`
+|`--limit_posts NUM`
+|Limit the number of posts to parse and publish.
+
+|*Force polling*
+|`na`
+|`--force_polling`
+|Force watch to use polling.
+
+|*Verbose output*
+|`na`
+|`-V, --verbose`
+|Print verbose output.
+
+|*Silence Output*
+|`na`
+|`-q, --quiet`
+|Silence the normal output from Jekyll during a build
+
+|*Incremental build*
+|`incremental: BOOL`
+|`-I, --incremental`
+|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.
+
+|*Liquid profiler*
+|`profile: BOOL`
+|`--profile`
+|Generate a Liquid rendering profile to help you identify performance
+bottlenecks.
+
+|===