RubyGems - j1_template_mde - Versions diffs - 2018.4.10 - Mend

j1_template_mde 2018.4.10

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.
+====