options (specifed in the configuration file) and flags (specified on the command-line) that control them.
+The table below lists the available settings for Jekyll, and the various options (specifed in the configuration file) and flags (specified on the command-line) that control them.
| Setting | -Options and Flags | ++ Options and Flags + |
|---|---|---|
|
Site Source -Changes the directory where Jekyll will look to transform files +Change the directory where Jekyll will read files |
-
|
|
|
Site Destination -Changes the directory where Jekyll will write files to +Change the directory where Jekyll will write files |
-
|
|
|
Safe -Disables custom plugins. +Disable custom plugins. |
-
|
|
|
Exclude -A list of directories and files to exclude from the conversion +Exclude directories and/or files from the conversion |
-
|
|
|
Include -A list of directories and files to specifically include in the conversion.
+ Force inclusion of directories and/or files in the conversion.
+ |
-
|
Regeneration -Enables auto-regeneration of the site when files are modified. Off by default. +Enable auto-regeneration of the site when files are modified. |
-
|
|
- URL -Sets |
-
-
|
- |
|
- Markdown -Uses RDiscount or Configuration +Specify a config file. Overrides settings in |
-
|
|
|
- Pygments -Enables highlight tag with Pygments. +Drafts +Process and render draft posts. |
-
|
|
|
Future -Publishes posts with a future date +Publish posts with a future date. |
-
|
|
|
LSI -Produces an index for related posts. +Produce an index for related posts. |
-
|
|
|
- Permalink -Controls the URLs that posts are generated with. Please refer to the Permalinks page for more info. - |
-
-
|
- |
|
- Pagination -Splits your posts up over multiple subdirectories called "page2", "page3", ... "pageN" - |
-
-
|
- |
|
Limit Posts -Limits the number of posts to parse and publish +Limit the number of posts to parse and publish. |
-
|
|
|
Local Server Port -Changes the port that the Jekyll server will run on +Listen on the given port. |
-
|
|
|
Local Server Hostname -Changes the hostname that the Jekyll server will run on +Listen at the given hostname. |
-
|
|
|
Base URL -Serve website from a given base URL +Serve website with the given base URL |
-
|
- If set, this specifies the layout file to use. Use the layout file name without file extension. Layout files must be placed in the
+
+ If set, this specifies the layout file to use. Use the layout file
+ name without file extension. Layout files must be placed in the
+ |
|
- If you need your processed URLs to be something other than the default
+
+ If you need your processed blog post URLs to be something other than
+ the default |
||
|
- Set to false if you don’t want a post to show up when the site is generated. ++ Set to false if you don’t want a specific post to show up when the + site is generated. + |
||
|
- 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 YAML list or a space-separated string. ++ + 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 YAML list or a + space-separated string. + + |
||
|
- 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 space-separated string. ++ + 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 space- + separated string. + + |
|
- A date here overrides the date from the name of the post. This can be used to ensure correct sorting of posts. ++ A date here overrides the date from the name of the post. This can be + used to ensure correct sorting of posts. + |
diff --git a/site/_posts/2012-07-01-github-pages.md b/site/_posts/2012-07-01-github-pages.md
index dbe8434a..5382b4d0 100644
--- a/site/_posts/2012-07-01-github-pages.md
+++ b/site/_posts/2012-07-01-github-pages.md
@@ -5,30 +5,61 @@ prev_section: extras
next_section: deployment-methods
---
-[GitHub Pages](https://pages.github.com) are public web pages for users, organizations, and repositories, that are freely hosted on [GitHub](https://github.com/). GitHub Pages are powered by Jekyll behind the scenes, so in addition to supporting regular HTML content, they’re also a great way to host your Jekyll-powered website for free.
+[GitHub Pages](https://pages.github.com) are public web pages for users,
+organizations, and repositories, that are freely hosted on
+[GitHub](https://github.com/). GitHub Pages are powered by Jekyll behind the
+scenes, so in addition to supporting regular HTML content, they’re also a great
+way to host your Jekyll-powered website for free.
## Deploying Jekyll to GitHub Pages
-GitHub Pages work by looking at certain branches of repositories on GitHub. There are two basic types of Pages available, user/organization Pages and project Pages. The way to deploy these two types of pages are nearly identical, except for a few minor details.
+GitHub Pages work by looking at certain branches of repositories on GitHub.
+There are two basic types available: user/organization pages and project pages.
+The way to deploy these two types of sites are nearly identical, except for a
+few minor details.
### User and Organization Pages
-User and organization Pages live in a special GitHub repository dedicated to only the Pages files. This repository must be named after the account name. For example, [@mojombo’s user page repository](https://github.com/mojombo/mojombo.github.com) has the name `mojombo.github.com`.
+User and organization pages live in a special GitHub repository dedicated to
+only the GitHub Pages files. This repository must be named after the account
+name. For example, [@mojombo’s user page
+repository](https://github.com/mojombo/mojombo.github.com) has the name
+`mojombo.github.com`.
-Content from the `master` branch of your repository will be used to build and publish the GitHub Pages site, so make sure your Jekyll site is stored there.
+Content from the `master` branch of your repository will be used to build and
+publish the GitHub Pages site, so make sure your Jekyll site is stored there.
- Year from the post’s filename +Year from the Post’s filename |
|
- Month from the post’s filename - |
- |
|
-
|
-
- Day from the post’s filename - |
-
|
-
|
-
- Title from the post’s filename - |
-
|
-
|
-
- The specified categories for this post. Jekyll automatically parses out double slashes in the URLs, so if no categories are present, it basically ignores this. +Month from the Post’s filename |
|
- Month from the post’s filename without leading zeros. +Month from the Post’s filename without leading zeros. + |
+ |
|
+
|
+
+ Day from the Post’s filename |
|
- Day from the post’s filename without leading zeros. +Day from the Post’s filename without leading zeros. + |
+ |
|
+
|
+
+ Title from the Post’s filename + |
+
|
+
|
+
+ + The specified categories for this Post. Jekyll automatically parses + out double slashes in the URLs, so if no categories are present, it + will ignore this. + |
GitHub Pages are powered by Jekyll, however all Pages sites are generated using the --safe option to disable custom plugins for security reasons. Unfortunately, this means your plugins won’t work if you’re deploying to GitHub Pages.
+ GitHub Pages is powered by Jekyll,
+ however all Pages sites are generated using the --safe option
+ to disable custom plugins for security reasons. Unfortunately, this means
+ your plugins won’t work if you’re deploying to GitHub Pages.
+ You can still use GitHub Pages to publish your site, but you'll need to
+ convert the site locally and push the generated static files to your GitHub
+ repository instead of the Jekyll source files.
+
Jekyll will only convert files that have a YAML header at -the top, even for converters you add using a plugin. If there is no YAML header, Jekyll will ignore the file and not send it through the converter.
++ Jekyll will only convert files that have a YAML header at the top, even for + converters you add using a plugin. +
matches
Called to determine whether the specific converter will -run on the page.
-
+ Does the given extension match this converter's list of acceptable
+ extensions? Takes one argument: the file's extension (including the
+ dot). Must return true if it matches, false
+ otherwise.
+
output_ext
The extension of the outputted file, usually this will be .html
+ The extension to be given to the output file (including the dot).
+ Usually this will be ".html".
+
convert
Logic to do the content conversion
-+ Logic to do the content conversion. Takes one argument: the raw content + of the file (without YAML front matter). Must return a String. +
{{"{% render_time page rendered at: "}}%}
+{% raw %} +{% render_time page rendered at: %}
+{% endraw %} {% endhighlight %} And we would get something like this on the page: @@ -233,7 +255,10 @@ And we would get something like this on the page: ### Liquid filters -You can add your own filters to the Liquid template system much like you can add tags above. Filters are simply modules that export their methods to liquid. All methods will have to take at least one parameter which represents the input of the filter. The return value will be the output of the filter. +You can add your own filters to the Liquid template system much like you can add +tags above. Filters are simply modules that export their methods to liquid. All +methods will have to take at least one parameter which represents the input of +the filter. The return value will be the output of the filter. {% highlight ruby %} module Jekyll @@ -249,7 +274,12 @@ Liquid::Template.register_filter(Jekyll::AssetFilter)Jekyll lets you access the site object through the context.registers feature of liquid. For example, you can access the global configuration file _config.yml using context.registers.config.
+ Jekyll lets you access the site object through the
+ context.registers feature of Liquid. For example, you can
+ access the global configuration file _config.yml using
+ context.registers.config.
+
safe
A boolean flag that allows a plugin to be safely included in
-Jekyll core for exclusion from use with GitHub Pages. In general, set
-this to true.
+ A boolean flag that informs Jekyll whether this plugin may be safely
+ executed in an environment where arbitrary code execution is not
+ allowed. This is used by GitHub Pages to determine which core plugins
+ may be used, and which are unsafe to run. If your plugin does not
+ allow for arbitrary code, execution, set this to true.
+ GitHub Pages still won't load your plugin, but if you submit it for
+ inclusion in core, it's best for this to be correct!
+
priortiy
priority
This flag determines what order the plugin is loaded in. Valid
-values are: :lowest, :low, :normal, :high, and :highest.
+ This flag determines what order the plugin is loaded in. Valid values
+ are: :lowest, :low, :normal,
+ :high, and :highest. Highest priority
+ matches are applied first, lowest priority are applied last.
+
If you have a Jekyll plugin that you would like to see added to this list, you should read the contributing page to find out how to make that happen.
++ If you have a Jekyll plugin that you would like to see added to this list, + you should read the contributing page to find + out how to make that happen. +
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.
+ You can skip the {% raw %}{{ site.url }}{% endraw %} 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.
+
You can make code snippets include line-numbers easily, simply add the word linenos to the end of the opening highlight tag like this: {{ "{% highlight ruby linenos " }}%}.
+ You can make code snippets include line-numbers by adding the word
+ linenos to the end of the opening highlight tag like this:
+ {% raw %}{% highlight ruby linenos %}{% endraw %}.
+
_config.yml
Stores configuration data. A majority of these options can be specified from the command line executable but it’s easier to throw them in here so you don’t have to remember them.
++ + 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. + +
_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.
+
+ These are the partials that can be mixed and matched by your layouts
+ and posts to facilitate reuse. The liquid tag
+ {% raw %}{% include file.ext %}{% endraw %}
+ can be used to include the partial in
+ _includes/file.ext.
+
+
_layouts
These are the templates which posts are inserted into. 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 data onto the page.
+
+ 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
+ {% raw %}{{ content }}{% endraw %}
+ is used to inject content into the web page.
+
+
_posts
Your dynamic content, so to speak. The format of these files is important, as named as YEAR-MONTH-DAY-title.MARKUP. The permalinks can be adjusted very flexibly for each post, but the date and markup language are determined solely by the file name.
+
+ Your dynamic content, so to speak. The format 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.
+
+
_site
This is where the generated site will be placed once Jekyll is done transforming it. It's probably a good idea to add this to your .gitignore file.
+
+ 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.
+
+
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.
+
+ 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 transferred over verbatim to the generated site. There's plenty of sites already using Jekyll if you're curious as to how they're laid out.
+
+ 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.
+
+
- {{ "{{ site.time | date_to_xmlschema " }}}}
+ {% raw %}{{ site.time | date_to_xmlschema }}{% endraw %}
2008-11-17T13:07:54-08:00
@@ -38,7 +42,7 @@ Jekyll uses the [Liquid](http://www.liquidmarkup.org/) templating language to pr
- {{ "{{ site.time | date_to_string " }}}}
+ {% raw %}{{ site.time | date_to_string }}{% endraw %}
17 Nov 2008
@@ -52,7 +56,7 @@ Jekyll uses the [Liquid](http://www.liquidmarkup.org/) templating language to pr
- {{ "{{ site.time | date_to_long_string " }}}}
+ {% raw %}{{ site.time | date_to_long_string }}{% endraw %}
17 November 2008
@@ -66,18 +70,21 @@ Jekyll uses the [Liquid](http://www.liquidmarkup.org/) templating language to pr
- {{ "{{ page.content | xml_escape " }}}}
+ {% raw %}{{ page.content | xml_escape }}{% endraw %}
CGI Escape
-CGI escape a string for use in a URL. Replaces any special characters with appropriate %XX replacements.
++ CGI escape a string for use in a URL. Replaces any special characters + with appropriate %XX replacements. +
- {{ "{{ “foo,bar;baz?” | cgi_escape " }}}}
+ {% raw %}{{ “foo,bar;baz?” | cgi_escape }}{% endraw %}
foo%2Cbar%3Bbaz%3F
@@ -91,7 +98,7 @@ Jekyll uses the [Liquid](http://www.liquidmarkup.org/) templating language to pr
- {{ "{{ page.content | number_of_words " }}}}
+ {% raw %}{{ page.content | number_of_words }}{% endraw %}
1337
@@ -105,7 +112,7 @@ Jekyll uses the [Liquid](http://www.liquidmarkup.org/) templating language to pr
- {{ "{{ page.tags | array_to_sentence_string " }}}}
+ {% raw %}{{ page.tags | array_to_sentence_string }}{% endraw %}
foo, bar, and baz
@@ -119,7 +126,7 @@ Jekyll uses the [Liquid](http://www.liquidmarkup.org/) templating language to pr
- {{ "{{ page.excerpt | textilize " }}}}
+ {% raw %}{{ page.excerpt | textilize }}{% endraw %}
- {{ "{{ page.excerpt | markdownify " }}}}
+ {% raw %}{{ page.excerpt | markdownify }}{% endraw %}
site
Sitewide information + Configuration settings from _config.yml
+
+ Sitewide information + configuration settings from
+ _config.yml. See below for details.
+
+
page
This is just the YAML Front Matter with 2 additions: url and content.
+ + Page specific information + the YAML Front + Matter. Custom variables set via the YAML front matter will be + available here. See below for details. + +
content
In layout files, this contains the content of the subview(s). This is the variable used to insert the rendered content into the layout. This is not used in post files or page files.
+ + In layout files, the rendered content of the Post or Page being wrapped. + Not defined in Post or Page files. + +
paginator
When the paginate configuration option is set, this variable becomes available for use.
+
+ When the paginate configuration option is set, this
+ variable becomes available for use. See Pagination for details.
+
+
site.time
The current time (when you run the jekyll command).
+
+ The current time (when you run the jekyll command).
+
+
site.posts
A reverse chronological list of all Posts.
+ + A reverse chronological list of all Posts. + +
site.related_posts
If the page being processed is a Post, this contains a list of up to ten related Posts. By default, these are low quality but fast to compute. For high quality but slow to compute results, run the jekyll command with the --lsi (latent semantic indexing) option.
+
+ If the page being processed is a Post, this contains a list of up to ten
+ related Posts. By default, these are low quality but fast to compute.
+ For high quality but slow to compute results, run the
+ jekyll command with the --lsi (latent semantic
+ indexing) option.
+
+
site.categories.CATEGORY
The list of all Posts in category CATEGORY.
+
+ The list of all Posts in category CATEGORY.
+
+
site.tags.TAG
The list of all Posts with tag TAG.
+
+ The list of all Posts with tag TAG.
+
+
site.[CONFIGURATION_DATA]
All variables set in your _config.yml are available through the site variable. For example, if you have url: http://mysite.com in your configuration file, then in your posts and pages it can be accessed using {{ "{{ site.url " }}}}. Jekyll does not parse changes to _config.yml in watch mode, you have to restart Jekyll to see changes to variables.
+
+ All the variables set via the command line and your
+ _config.yml are available through the site
+ variable. For example, if you have url: http://mysite.com
+ in your configuration file, then in your Posts and Pages it will be
+ stored in site.url. Jekyll does not parse changes to
+ _config.yml in watch mode, you must restart
+ Jekyll to see changes to variables.
+
+
page.content
The un-rendered content of the Page.
+ + The un-rendered content of the Page. + +
page.title
The title of the Post.
+ + The title of the Post. + +
page.url
The URL of the Post without the domain. e.g. /2008/12/14/my-post.html
+
+ The URL of the Post without the domain. e.g.
+ /2008/12/14/my-post.html
+
+
page.date
The Date assigned to the Post. This can be overridden in a post’s front matter by specifying a new date/time in the format YYYY-MM-DD HH:MM:SS
+
+ The Date assigned to the Post. This can be overridden in a Post’s front
+ matter by specifying a new date/time in the format
+ YYYY-MM-DD HH:MM:SS
+
+
page.id
An identifier unique to the Post (useful in RSS feeds). e.g. /2008/12/14/my-post
+
+ An identifier unique to the Post (useful in RSS feeds). e.g.
+ /2008/12/14/my-post
+
+
page.categories
The list of categories to which this post belongs. Categories are derived from the directory structure above the _posts directory. For example, a post at /work/code/_posts/2008-12-24-closures.textile would have this field set to ['work', 'code']. These can also be specified in the YAML Front Matter.
+
+ The list of categories to which this post belongs. Categories are
+ derived from the directory structure above the _posts
+ directory. For example, a post at
+ /work/code/_posts/2008-12-24-closures.md would have this
+ field set to ['work', 'code']. These can also be specified
+ in the YAML Front Matter.
+
+
page.tags
The list of tags to which this post belongs. These can be specified in the YAML Front Matter
+ + The list of tags to which this post belongs. These can be specified in + the YAML Front Matter + +
Any custom front matter that you specify will be available under page. For example, if you specify custom_css: true in a page’s front matter, that value will be available in templates as page.custom_css.
+
+ Any custom front matter that you specify will be available under
+ page. For example, if you specify custom_css: true
+ in a page’s front matter, that value will be available as
+ page.custom_css.
+
+
paginator.per_page
Number of posts per page.
Number of Posts per page.
paginator.posts
paginator.total_posts
Total number of posts.
Total number of Posts.
paginator.total_pages
Total number of pages.
Total number of Pages.
paginator.page
These are only available in index files, however they can be located in a subdirectory, such as /blog/index.html.
+
+ These are only available in index files, however they can be located in a
+ subdirectory, such as /blog/index.html.
+
+