RubyGems - j1_template_mde - Versions diffs - 2018.4.10 - Mend

j1_template_mde 2018.4.10

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (852) hide show

data/lib/starter_web/pages/start/kickstarter/web_in_a_day/000_includes/documents/manage_pages.adoc ADDED Viewed

@@ -0,0 +1,365 @@
+---
+layout:                 page
+description:            Manage and Write Content with Jekyll
+title:                  Manage Pages
+tagline:                Manage and Write Content with Jekyll
+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]
+====
+In addition to writing posts, another thing you may want to do with your
+Jekyll site is create static pages. By taking advantage of the way Jekyll
+copies files and directories, this is easy to do.
+====
+== The Front Matter
+The front matter is where Jekyll starts to get really cool. Any file that
+contains a `YAML front matter block` will be processed by Jekyll as a special
+file. The front matter must be the first thing in the file and must take the
+form of valid YAML set between triple-dashed lines.
+Here is a very basic example:
+[source, yaml]
+--------------
+---
+layout: post
+title: Blogging Like a Hacker
+---
+--------------
+Between these triple-dashed lines, you can set predefined variables (see below
+for a reference) or even create custom ones of your own. These variables will
+then be available to you to access using Liquid tags both further down in the
+file and also in any layouts or includes that the page or post in question
+relies on.
+[WARNING]
+====
+If you use UTF-8 encoding, make sure that no `BOM header` characters exist
+in your files or very, very bad things will happen to Jekyll. This is
+especially relevant if you’re running`Jekyll on Windows`.
+====
+[NOTE]
+====
+If you want to use `Liquid tags and variables` but don’t need anything in
+your front matter, just leave it empty! The set of triple-dashed lines with
+nothing in between will still get Jekyll to  process your file. (This is
+useful for things like CSS and RSS feeds!)
+====
+== Predefined Global Variables
+There are a number of predefined global variables that you can set in the
+front matter of a page or post.
+[width="100%", cols="4,8",options="header", role="table-responsive mt-3"]
+|=======================================================================
+|Variable     |Description
+|`layout`     |If set, this specifies the layout file to use. Use the layout
+file name without the file extension. Layout files must be placed in the
+`&#x5F;layouts` directory.
+|`permalink`  |If you need your processed blog post URLs to be something
+other than the site-wide style (default `/year/month/day/title.html`),
+then you can set this variable and it will be used as the final URL.
+|`published`  |Set to false if you donÔÇÖt want a specific post to show up
+when the site is generated.
+|=======================================================================
+== Custom Variables
+Any variables in the front matter that are not predefined are mixed into the
+data that is sent to the Liquid templating engine during the conversion. For
+instance, if you set a title, you can use that in your layout to set the page
+title:
+[source, html]
+--------------
+<!DOCTYPE HTML>
+<html>
+  <head>
+    <title>{% raw %}{{ page.title }}{% endraw %}</title>
+  </head>
+  <body>
+    ...
+--------------
+== Predefined Variables for Posts
+These are available out-of-the-box to be used in the front matter for a post.
+[width="100%", cols="4,8",options="header", role="table-responsive mt-3"]
+|=======================================================================
+|Variable     |Description
+|`date`       |A date here overrides the date from the name of the post. This
+can be used to ensure correct sorting of posts. A date is specified in
+the format `YYYY-MM-DD HH:MM:SS +/-TTTT`; hours, minutes, seconds, and
+timezone offset are optional.
+a|
+`category`
+`categories`
+      |Instead of placing posts inside of folders, you can specify one or
+more categories that the post belongs to. When the site is generated the
+post will act as though it had been set with these categories normally.
+Categories (plural key) can be specified as a
+https://en.wikipedia.org/wiki/YAML#Lists[YAML list] or a comma-separated
+string.
+|`tags`     |Similar to categories, one or multiple tags can be added to a
+post. Also like categories, tags can be specified as a YAML list or a
+comma-separated string.
+|=======================================================================
+[NOTE]
+====
+*Don't repeat yourself!*
+If you don't want to repeat your frequently used front matter variables
+over and over, just define `Front Matter defaults` for them and only
+override them where necessary (or not at all). This works both for predefined
+and custom variables.
+====
+== Working with drafts
+Drafts are posts without a date. They're posts you're still working on and
+don't want to publish yet. To get up and running with drafts, create a
+`&#x5F;drafts` folder in your site's root (as described in the `docs structure`
+ section) and create your first draft:
+[source, text]
+--------------
+|-- _drafts/
+|   |-- a-draft-post.md
+--------------
+To preview your site with drafts, simply run `jekyll serve` or `jekyll build`
+with the `--drafts` switch. Each will be assigned the value modification time
+of the draft file for its date, and thus you will see currently edited drafts
+as the latest posts.
+== Creating pages
+In addition to [writing posts](../posts/), another thing you may want to do
+with your Jekyll site is create static pages. By taking advantage of the way
+Jekyll copies files and directories, this is easy to do.
+=== Homepage
+Just about every web server configuration you come across will look for an HTML
+file called `index.html` (by convention) in the site's root folder and display
+that as the homepage. Unless the web server you’re using is configured to look
+for some different filename as the default, this file will turn into the
+homepage of your Jekyll-generated site.
+[NOTE]
+====
+*Use layouts on your homepage!*
+Any HTML file on your site can use layouts and/or includes, even the
+homepage. Common content, like headers and footers, make excellent
+candidates for extraction into a layout.
+====
+=== Where additional pages live
+Where you put HTML or Markdown files for pages depends on how you want the
+pages to work. There are two main ways of creating pages:
+- Place named HTML or Markdown files for each page in your site's root folder.
+- Create a folder in the site's root for each page, and place an index.html
+or index.md file in each page folder.
+Both methods work fine (and can be used in conjunction with each other),
+with the only real difference being the resulting URLs.
+=== Named HTML files
+The simplest way of adding a page is just to add an HTML file in the root
+directory with a suitable name for the page you want to create. For a site with
+a homepage, an about page, and a contact page, here’s what the root directory
+and associated URLs might look like:
+[source, text]
+--------------
+.
+|-- _config.yml
+|-- _includes/
+|-- _layouts/
+|-- _posts/
+|-- _site/
+|-- about.html    # => http://example.com/about.html
+|-- index.html    # => http://example.com/
+|-- other.md      # => http://example.com/other.html
+└── contact.html  # => http://example.com/contact.html
+--------------
+=== Named folders containing index HTML files
+There is nothing wrong with the above method. However, some people like to keep
+their URLs free from things like filename extensions. To achieve clean URLs for
+pages using Jekyll, you simply need to create a folder for each top-level page
+you want, and then place an `index.html` file in each page’s folder. This way
+the page URL ends up being the folder name, and the web server will serve up
+the respective `index.html` file. Here's an example of what this structure
+might look like:
+[source, text]
+--------------
+.
+├── _config.yml
+├── _includes/
+├── _layouts/
+├── _posts/
+├── _site/
+├── about/
+|   └── index.html  # => http://example.com/about/
+├── contact/
+|   └── index.html  # => http://example.com/contact/
+|── other/
+|   └── index.md    # => http://example.com/other/
+└── index.html      # => http://example.com/
+--------------
+This approach may not suit everyone, but for people who like clean URLs it’s
+simple and it works. In the end, the decision is yours!
+[NOTE]
+====
+*Use permalink Front Matter Variable!*
+Clean URLs can also be achieved using the `permalink` front
+matter variable. In the example above, using the first method, you can
+get URL `http://example.com/other` for the file `other.md` by setting this
+at the top of the file: `permalink: /other`
+====
+== Static Files
+In addition to renderable and convertible content, we also have `static files`.
+A static file is a file that does not contain any YAML front matter. These
+include images, PDFs, and other un-rendered content.
+They're accessible in Liquid via `site.static&#x5F;files` and contain the
+following metadata:
+[width="100%", cols="4,8",options="header", role="table-responsive mt-3"]
+|=======================================================================
+|Variable |Description
+|`file.path` |The relative path to the file.
+|`file.modified&#x5F;time` |The `Time` the file was last modified.
+|`file.extname` |The extension name for the file, e.g. `.jpg` for
+`image.jpg`
+|=======================================================================
+== Assets
+Jekyll provides built-in support for Sass and can work with CoffeeScript via
+a Ruby gem. In order to use them, you must first create a file with the
+proper extension name (one of `.sass`, `.scss`, or `.coffee`) and ***start the
+file with two lines of triple dashes***, like this:
+[source, sass]
+--------------
+---
+---
+// start content
+.my-definition
+  font-size: 1.2em
+--------------
+Jekyll treats these files the same as a regular page, in that the output file
+will be placed in the same directory that it came from. For instance, if you
+have a file named `css/styles.scss` in your site's source folder, Jekyll
+will process it and put it in your site's destination folder under
+`css/styles.css`.
+[NOTE]
+====
+Jekyll processes all Liquid filters and tags in asset files
+If you are using `Mustache` or another `JavaScript templating language` that
+conflicts with the `Liquid template syntax`, you will need to place `{% raw %}`
+ and `{% endraw %}` tags around this code.
+====
+== Sass/SCSS
+Jekyll allows you to customize your Sass conversion in certain ways.
+Place all your partials in your `sass&#x5F;dir`, which defaults to
+`<source>/&#x5F;sass`. Place your main SCSS or Sass files in the place you want
+them to be in the output file, such as `<source>/css`. For an example, take
+a look at [this example site using Sass support in Jekyll][example-sass].
+If you are using Sass `@import` statements, you'll need to ensure that your
+`sass&#x5F;dir` is set to the base directory that contains your Sass files. You
+can do that thusly:
+[source, yaml]
+--------------
+sass:
+    sass_dir: _sass
+--------------
+The Sass converter will default the `sass&#x5F;dir` configuration option to
+`&#x5F;sass`.
+[example-sass]: https://github.com/jekyll/jekyll-sass-converter/tree/master/example
+[NOTE]
+====
+*sass&#x5F;dir is only used by Sass.*
+Note that the `sass&#x5F;dir` becomes the load path for Sass imports,
+nothing more. This means that Jekyll does not know about these files
+directly, so any files here should not contain the YAML Front Matter as
+described above nor will they be transformed as described above. This
+folder should only contain imports.
+====
+You may also specify the output style with the `style` option in your
+`&#x5F;config.yml` file:
+[source, yaml]
+--------------
+sass:
+    style: compressed
+--------------
+These are passed to Sass, so any output style options Sass supports are valid
+here, too.
+== Coffeescript
+To enable Coffeescript in Jekyll 3.0 and up you must
+* Install the `jekyll-coffeescript` gem
+* Ensure that your `&#x5F;config.yml` is up-to-date and includes the following:
+[source, yaml]
+--------------
+gems:
+ - jekyll-coffeescript
+--------------

data/lib/starter_web/pages/start/kickstarter/web_in_a_day/000_includes/documents/manage_posts.adoc ADDED Viewed

@@ -0,0 +1,203 @@
+---
+layout:                 page
+description:            Manage and Write Blog Posts with Jekyll
+title:                  Blog Posts
+tagline:                Manage and Write Blog Posts with Jekyll
+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
+[[write-posts]]
+== Managing posts
+One of Jekyll’s best aspects is that it is `blog aware`. What does this mean,
+exactly? Well, simply put, it means that blogging is baked into Jekyll’s
+functionality. If you write articles and publish them online, you can publish
+and maintain a blog simply by managing a folder of text-files on your computer.
+Compared to the hassle of configuring and maintaining databases and web-based
+CMS systems, this will be a welcome change!
+[[posts-folder]]
+=== The Posts Folder
+As explained on the directory structure page, the `&#x5F;posts` folder is where
+your blog posts will live. These files are generally Markdown or HTML, but can
+be other formats with the proper converter installed. All posts must have YAML
+Front Matter, and they will be converted from their source format into an HTML
+page that is part of your static site.
+NOTE: The Posts Folder `&#x5F;posts` contains 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.
+[[create-posts]]
+== Creating Post Files
+To create a new post, all you need to do is create a file in the `&#x5F;posts`
+directory. How you name files in this folder is important. Jekyll requires
+blog post files to be named according to the following format:
+[source, bash]
+----
+  YEAR-MONTH-DAY-title.MARKUP
+----
+Where `YEAR` is a four-digit number, `MONTH` and `DAY` are both two-digit
+numbers, and `MARKUP` is the file extension representing the format used
+in the file. For example, the following are examples of valid post filenames:
+[source, bash]
+----
+  2015-12-31-new-years-eve-is-awesome.md
+  2016-02-12-how-to-write-a-blog.textile
+----
+=== Content Formats
+All blog post files must begin with YAML Front Matter. After that, it’s simply
+a matter of deciding which format you prefer. Jekyll supports Markdown out of
+the box, and has myriad extensions for other formats as well, including the
+popular Textile format. These formats each have their own way of marking up
+different types of content within a post, so you should familiarize yourself
+with these formats and decide which one best suits your needs.
+[NOTE]
+====
+Content processors can modify certain characters to make them look nicer.
+For example, the smart extension in Redcarpet converts standard ASCII quotation
+characters to curly, Unicode ones.
+In order for the browser to display those characters properly, define the
+charset meta value by including `<meta charset="utf-8">` in the `<head>`
+section of your HTML layout.
+====
+NOTE: Markup languages like Asciidoc use some often used characters, like the
+underscore `&#x5F;` for the posts folder `&#x5F;posts` to markup e.g. formatting.
+Typically all those markups comes in pairs like `&#x5F;italic&#x5F;` to format
+something e.g. _italic_. If you note for exammple a single underscore with
+Asciidoc, the engine will interprete the undercore as the beginning of a italic
+formatted sequence and and your following text will look very strange - this
+is because no closing underscore follows. To prevent Markup engines to
+(mis-)interprete those (single) characters (with no special meaning), write
+them as the `HTML Entity for the ASCII character` like `&#65` for an
+uppercase `A`. Don't miss to place a colon `;` at the end!
+=== Including images and resources
+Chances are, at some point, you’ll want to include images, downloads, or other
+digital assets along with your text content. While the syntax for linking to
+these resources differs between Markdown and Textile, the problem of working
+out where to store these files in your site is something everyone will face.
+Because of Jekyll’s flexibility, there are many solutions to how to do this.
+One common solution is to create a folder in the root of the project directory
+called something like assets or downloads, into which any images, downloads
+or other resources are placed. Then, from within any post, they can be linked
+to using the site’s root as the path for the asset to include. Again, this
+will depend on the way your site’s (sub)domain and path are configured, but
+here are some examples (in Markdown) of how you could do this using the
+`site.url` variable in a post.
+Including an image asset in a post:
+[source, bash]
+----
+  ... which is shown in the screenshot below:
+  ![My helpful screenshot]({{ site.url }}/assets/screenshot.jpg)
+----
+Linking to a PDF for readers to download:
+[source, bash]
+----
+  ... you can [get the PDF]({{ site.url }}/assets/mydoc.pdf) directly.
+----
+TIP: Link using just the `site root URL`.
+You can skip the `{{ site.url }}` variable if you know your site will only
+ever be displayed at the root URL of your domain. In this case you can reference
+assets directly with just `/path/file.jpg`.
+=== Displaying an index of posts
+It’s all well and good to have posts in a folder, but a blog is no use unless
+you have a list of posts somewhere. Creating an index of posts on another
+page (or in a template) is easy, thanks to the Liquid template language and
+its tags. Here’s a basic example of how to create a list of links to your
+blog posts:
+[source, html]
+----
+  <ul>
+    {% for post in site.posts %}
+      <li>
+        <a href="{{ post.url }}">{{ post.title }}</a>
+      </li>
+    {% endfor %}
+  </ul>
+----
+Of course, you have full control over how (and where) you display your posts,
+and how you structure your site. You should read more about how templates work
+with Jekyll if you want to know more.
+Note that the post variable only exists inside the for loop above. If you wish
+to access the currently-rendering page/posts’s variables (the variables of the
+post/page that has the for loop in it), use the page variable instead.
+=== Post excerpts
+Each post automatically takes the first block of text, from the beginning of
+the content to the first occurrence of `excerpt&#x5F;separator`, and sets it
+as the post.excerpt. Take the above example of an index of posts. Perhaps you
+want to include a little hint about the post’s content by adding the first
+paragraph of each of your posts:
+[source, bash]
+----
+  {{ post.excerpt | remove: '<p>' | remove: '</p>' }}
+----
+If you don’t like the automatically-generated post excerpt, it can be
+explicitly overridden by adding an excerpt value to your post’s YAML Front
+Matter. Alternatively, you can choose to define a custom `excerpt&#x5F;separator`
+in the post’s YAML front matter:
+[source, bash]
+----
+---
+excerpt_separator: <!--more-->
+---
+This is the text to excerpt
+<!--more-->
+All following is out-of-excerpt
+----
+You can also set the `excerpt&#x5F;separator` globally in your `&#x5F;config.yml`
+configuration file. Completely disable excerpts by setting your `excerpt&#x5F;separator`
+to `""`.
+[NOTE]
+====
+Also, as with any output generated by Liquid tags, you can pass the
+`| strip_html filter` to remove any html tags in the output. This is
+particularly helpful if you wish to output a post excerpt as a
+`meta="description"` tag within the post head, or anywhere else having
+html tags along with the content is not desirable.
+====