dan
/
jekyll
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Merge pull request #3567 from chrisfinazzo/grammar 

Wrap lines
This commit is contained in:
Parker Moore 2015-03-14 18:43:24 -07:00
parent f4a14b60ba 2d0d27da73
commit 29853ab46d
17 changed files with 227 additions and 149 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

64
site/_docs/collections.md
View File

@ -11,13 +11,18 @@ permalink: /docs/collections/
</p>
</div>
Not everything is a post or a page. Maybe you want to document the various methods in your open source project, members of a team, or talks at a conference. Collections allow you to define a new type of document that behave like Pages or Posts do normally, but also have their own unique properties and namespace.
Not everything is a post or a page. Maybe you want to document the various
methods in your open source project, members of a team, or talks at a
conference. Collections allow you to define a new type of document that behave
like Pages or Posts do normally, but also have their own unique properties and
namespace.
## Using Collections
### Step 1: Tell Jekyll to read in your collection
Add the following to your site's `_config.yml` file, replacing `my_collection` with the name of your collection:
Add the following to your site's `_config.yml` file, replacing `my_collection`
with the name of your collection:
{% highlight yaml %}
collections:
@ -34,14 +39,20 @@ collections:
### Step 2: Add your content
Create a corresponding folder (e.g. `<source>/_my_collection`) and add documents.
YAML Front Matter is read in as data if it exists, and everything after it is stuck in the Document's `content` attribute. If no YAML Front Matter is provided, Jekyll will not generate the file in your collection.
Create a corresponding folder (e.g. `<source>/_my_collection`) and add
documents. YAML Front Matter is read in as data if it exists, and everything
after it is stuck in the Document's `content` attribute. If no YAML Front
Matter is provided, Jekyll will not generate the file in your collection.
Note: the folder must be named identically to the collection you defined in your `_config.yml` file, with the addition of the preceding `_` character.
Note: the folder must be named identically to the collection you defined in
your `_config.yml` file, with the addition of the preceding `_` character.
### Step 3: Optionally render your collection's documents into independent files
### Step 3: Optionally render your collection's documents into independent
files
If you'd like Jekyll to create a public-facing, rendered version of each document in your collection, set the `output` key to `true` in your collection metadata in your `_config.yml`:
If you'd like Jekyll to create a public-facing, rendered version of each
document in your collection, set the `output` key to `true` in your collection
metadata in your `_config.yml`:
{% highlight yaml %}
collections:
@ -54,7 +65,8 @@ For example, if you have `_my_collection/some_subdir/some_doc.md`,
it will be rendered using Liquid and the Markdown converter of your
choice and written out to `<dest>/my_collection/some_subdir/some_doc.html`.
As for posts with [Permalinks](../permalinks/), document URL can be customized by setting a `permalink` metadata to the collection:
As for posts with [Permalinks](../permalinks/), document URL can be customized
by setting a `permalink` metadata to the collection:
{% highlight yaml %}
collections:
@ -63,7 +75,8 @@ collections:
permalink: /awesome/:path/
{% endhighlight %}
For example, if you have `_my_collection/some_subdir/some_doc.md`, it will be written out to `<dest>/awesome/some_subdir/some_doc/index.html`.
For example, if you have `_my_collection/some_subdir/some_doc.md`, it will be
written out to `<dest>/awesome/some_subdir/some_doc/index.html`.
<div class="mobile-side-scroller">
<table>
@ -95,7 +108,8 @@ For example, if you have `_my_collection/some_subdir/some_doc.md`, it will be wr
<p><code>name</code></p>
</td>
<td>
<p>The document's base filename, with every sequence of spaces and non-alphanumeric characters replaced by a hyphen.</p>
<p>The document's base filename, with every sequence of spaces
and non-alphanumeric characters replaced by a hyphen.</p>
</td>
</tr>
<tr>
@ -122,9 +136,14 @@ For example, if you have `_my_collection/some_subdir/some_doc.md`, it will be wr
### Collections
Each collection is accessible via the `site` Liquid variable. For example, if you want to access the `albums` collection found in `_albums`, you'd use `site.albums`. Each collection is itself an array of documents (e.g. `site.albums` is an array of documents, much like `site.pages` and `site.posts`). See below for how to access attributes of those documents.
Each collection is accessible via the `site` Liquid variable. For example, if
you want to access the `albums` collection found in `_albums`, you'd use
`site.albums`. Each collection is itself an array of documents
(e.g. `site.albums` is an array of documents, much like `site.pages` and
`site.posts`). See below for how to access attributes of those documents.
The collections are also available under `site.collections`, with the metadata you specified in your `_config.yml` (if present) and the following information:
The collections are also available under `site.collections`, with the metadata
you specified in your `_config.yml` (if present) and the following information:
<div class="mobile-side-scroller">
<table>
@ -161,7 +180,8 @@ The collections are also available under `site.collections`, with the metadata y
</td>
<td>
<p>
The path to the collections's source directory, relative to the site source.
The path to the collections's source directory, relative to the site
source.
</p>
</td>
</tr>
@ -181,7 +201,8 @@ The collections are also available under `site.collections`, with the metadata y
</td>
<td>
<p>
Whether the collection's documents will be output as individual files.
Whether the collection's documents will be output as individual
files.
</p>
</td>
</tr>
@ -192,7 +213,8 @@ The collections are also available under `site.collections`, with the metadata y
### Documents
In addition to any YAML Front Matter provided in the document's corresponding file, each document has the following attributes:
In addition to any YAML Front Matter provided in the document's corresponding
file, each document has the following attributes:
<div class="mobile-side-scroller">
<table>
@ -209,8 +231,10 @@ In addition to any YAML Front Matter provided in the document's corresponding fi
</td>
<td>
<p>
The (unrendered) content of the document. If no YAML Front Matter is provided, Jekyll will not generate the file in your collection. If YAML Front Matter
is used, then this is all the contents of the file after the terminating
The (unrendered) content of the document. If no YAML Front Matter is
provided, Jekyll will not generate the file in your collection. If
YAML Front Matter is used, then this is all the contents of the file
after the terminating
`---` of the front matter.
</p>
</td>
@ -221,7 +245,8 @@ In addition to any YAML Front Matter provided in the document's corresponding fi
</td>
<td>
<p>
The rendered output of the document, based on the <code>content</code>.
The rendered output of the document, based on the
<code>content</code>.
</p>
</td>
</tr>
@ -253,7 +278,8 @@ In addition to any YAML Front Matter provided in the document's corresponding fi
<p>
The URL of the rendered collection. The file is only written to the
destination when the name of the collection to which it belongs is
included in the <code>render</code> key in the site's configuration file.
included in the <code>render</code> key in the site's configuration
file.
</p>
</td>
</tr>

48
site/_docs/configuration.md
View File

@ -444,7 +444,9 @@ layout: "foobar"
The post text goes here...
{% endhighlight %}
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.
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
@ -456,8 +458,8 @@ file or on the command-line.
<h5>There are two unsupported kramdown options</h5>
<p>
Please note that both <code>remove_block_html_tags</code> and
<code>remove_span_html_tags</code> are currently unsupported in Jekyll due to the
fact that they are not included within the kramdown HTML converter.
<code>remove_span_html_tags</code> are currently unsupported in Jekyll due
to the fact that they are not included within the kramdown HTML converter.
</p>
</div>
@ -545,27 +547,47 @@ kramdown:
## Markdown Options
The various Markdown renderers supported by Jekyll sometimes have extra options available.
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`.
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.
- `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:
Note that you can also specify a language for highlighting after the first
delimiter:
```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.
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.
- `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 v2.2.x, and extensions like `footnotes` and `highlight` weren't added until after version 3.0.0. The most commonly used extensions are:
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 v2.2.x, and extensions like `footnotes` and
`highlight` weren't added until after version 3.0.0. The most commonly used
extensions are:
- `tables`
- `no_intra_emphasis`
@ -575,7 +597,8 @@ All other extensions retain their usual names from Redcarpet, and no renderer op
### Kramdown
In addition to the defaults mentioned above, you can also turn on recognition of Github Flavored Markdown by passing an `input` option with a value of "GFM".
In addition to the defaults mentioned above, you can also turn on recognition
of Github Flavored Markdown by passing an `input` option with a value of "GFM".
For example, in your `_config.yml`:
@ -603,7 +626,8 @@ class Jekyll::Converters::Markdown::MyCustomProcessor
end
{% endhighlight %}
Once you've created your class and have it properly setup either as a plugin in the `_plugins` folder or as a gem, specify it in your `_config.yml`:
Once you've created your class and have it properly setup either as a plugin in
the `_plugins` folder or as a gem, specify it in your `_config.yml`:
{% highlight yaml %}
markdown: MyCustomProcessor

9
site/_docs/contributing.md
View File

@ -115,10 +115,11 @@ Gotchas
* If you want to bump the gem version, please put that in a separate commit.
This way, the maintainers can control when the gem gets released.
* Try to keep your patch(es) based from the latest commit on jekyll/jekyll.
The easier it is to apply your work, the less work the maintainers have to do,
which is always a good thing.
* Please don't tag your GitHub issue with \[fix\], \[feature\], etc. The maintainers
actively read the issues and will label it once they come across it.
The easier it is to apply your work, the less work the maintainers have to
do, which is always a good thing.
* Please don't tag your GitHub issue with \[fix\], \[feature\], etc. The
maintainers actively read the issues and will label it once they come across
it.
<div class="note">
<h5>Let us know what could be better!</h5>

17
site/_docs/datafiles.md
View File

@ -21,13 +21,14 @@ Plugins/themes can also leverage Data Files to set configuration variables.
As explained on the [directory structure](../structure/) page, the `_data`
folder is where you can store additional data for Jekyll to use when generating
your site. These files must be YAML files (using either the `.yml`, `.yaml`, `.json`
or `csv` extension) and they will be accessible via `site.data`.
your site. These files must be YAML files
(using either the `.yml`, `.yaml`, `.json` or `csv` extension) and they will be
accessible via `site.data`.
## Example: List of members
Here is a basic example of using Data Files to avoid copy-pasting large chunks of
code in your Jekyll templates:
Here is a basic example of using Data Files to avoid copy-pasting large chunks
of code in your Jekyll templates:
In `_data/members.yml`:
@ -72,7 +73,10 @@ You can now render the list of members in a template:
## Example: Organizations
Data files can also be placed in sub-folders of the `_data` folder. Each folder level will be added to a variable's namespace. The example below shows how GitHub organizations could be defined separately in a file under the `orgs` folder:
Data files can also be placed in sub-folders of the `_data` folder. Each folder
level will be added to a variable's namespace. The example below shows how
GitHub organizations could be defined separately in a file under the `orgs`
folder:
In `_data/orgs/jekyll.yml`:
@ -97,7 +101,8 @@ members:
github: jdoe
{% endhighlight %}
The organizations can then be accessed via `site.data.orgs`, followed by the file name:
The organizations can then be accessed via `site.data.orgs`, followed by the
file name:
{% highlight html %}
{% raw %}

13
site/_docs/drafts.md
View File

@ -4,9 +4,9 @@ title: Working with drafts
permalink: /docs/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 `_drafts` folder in your site's
root (as described in the [site structure](/docs/structure/) section) and create your
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
`_drafts` folder in your site's root (as described in the [site structure](/docs/structure/) section) and create your
first draft:
{% highlight text %}
@ -14,6 +14,7 @@ first draft:
| |-- a-draft-post.md
{% endhighlight %}
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.
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.

24
site/_docs/frontmatter.md
View File

@ -36,10 +36,10 @@ relies on.
<div class="note">
<h5>ProTip™: Front Matter Variables Are Optional</h5>
<p>
If you want to use <a href="../variables/">Liquid tags and variables</a> 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!)
If you want to use <a href="../variables/">Liquid tags and variables</a>
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!)
</p>
</div>
@ -122,8 +122,8 @@ front matter of a page or post.
<p>
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.
Also like categories, tags can be specified as a YAML list or a
space-separated string.
</p>
</td>
@ -170,8 +170,8 @@ These are available out-of-the-box to be used in the front matter for a post.
<td>
<p>
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
<code>YYYY-MM-DD HH:MM:SS +/-TTTT</code>; hours, minutes, seconds, and timezone offset
used to ensure correct sorting of posts. A date is specified in the
format <code>YYYY-MM-DD HH:MM:SS +/-TTTT</code>; hours, minutes, seconds, and timezone offset
are optional.
</p>
</td>
@ -183,9 +183,9 @@ These are available out-of-the-box to be used in the front matter for a post.
<div class="note">
<h5>ProTip™: Don't repeat yourself</h5>
<p>
If you don't want to repeat your frequently used front matter variables over and over,
just define <a href="../configuration/#front-matter-defaults" title="Front Matter defaults">defaults</a>
for them and only override them where necessary (or not at all). This works both for predefined
and custom variables.
If you don't want to repeat your frequently used front matter variables
over and over, just define <a href="../configuration/#front-matter-defaults" title="Front Matter defaults">defaults</a>
for them and only override them where necessary (or not at all). This works
both for predefined and custom variables.
</p>
</div>

8
site/_docs/github-pages.md
View File

@ -103,10 +103,10 @@ whilst maintaining the ability to preview your Jekyll site locally.
3. When doing permalinks or internal links, do it like this:
`{% raw %}{{ site.baseurl }}{{ post.url }}{% endraw %}` -- note that there
is **no** slash between the two variables.
4. Finally, if you'd like to preview your site before committing/deploying using
`jekyll serve`, be sure to pass an **empty string** to the `--baseurl` option,
so that you can view everything at `localhost:4000` normally (without
`/project-name` at the beginning): `jekyll serve --baseurl ''`
4. Finally, if you'd like to preview your site before committing/deploying
using `jekyll serve`, be sure to pass an **empty string** to the `--baseurl`
option, so that you can view everything at `localhost:4000` normally
(without `/project-name` at the beginning): `jekyll serve --baseurl ''`
This way you can preview your site locally from the site root on localhost,
but when GitHub generates your pages from the gh-pages branch all the URLs

4
site/_docs/installation.md
View File

@ -11,8 +11,8 @@ describing the issue you encountered and how we might make the process easier.
### Requirements
Installing Jekyll is easy and straight-forward, but there are a few requirements
you’ll need to make sure your system has before you start.
Installing Jekyll is easy and straight-forward, but there are a few
requirements you’ll need to make sure your system has before you start.
- [Ruby](http://www.ruby-lang.org/en/downloads/) (including development
headers)

16
site/_docs/pages.md
View File

@ -4,9 +4,9 @@ title: Creating pages
permalink: /docs/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.
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
@ -31,8 +31,8 @@ Where you put HTML files for pages depends on how you want the pages to work.
There are two main ways of creating pages:
- Place named HTML 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 file
in each page folder.
- Create a folder in the site's root for each page, and place an index.html
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.
@ -62,9 +62,9 @@ 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:
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:
{% highlight bash %}
.

34
site/_docs/pagination.md
View File

@ -6,15 +6,15 @@ permalink: /docs/pagination/
With many websites—especially blogs—it’s very common to break the main listing
of posts up into smaller lists and display them over multiple pages. Jekyll has
pagination built-in, so you can automatically generate the appropriate files and
folders you need for paginated listings.
pagination built-in, so you can automatically generate the appropriate files
and folders you need for paginated listings.
<div class="note info">
<h5>Pagination only works within HTML files</h5>
<p>
Pagination does not work with Markdown or Textile files in your Jekyll site.
It will only work when used within HTML files. Since you’ll likely be using
this for the list of Posts, this shouldn’t be an issue.
Pagination does not work with Markdown or Textile files in your Jekyll
site. It will only work when used within HTML files. Since you’ll likely be
using this for the list of Posts, this shouldn’t be an issue.
</p>
</div>
@ -27,8 +27,8 @@ specifies how many items should be displayed per page:
paginate: 5
{% endhighlight %}
The number should be the maximum number of Posts you’d like to be displayed per-
page in the generated site.
The number should be the maximum number of Posts you’d like to be displayed
per-page in the generated site.
You may also specify the destination of the pagination pages:
@ -36,16 +36,18 @@ You may also specify the destination of the pagination pages:
paginate_path: "/blog/page:num/"
{% endhighlight %}
This will read in `blog/index.html`, send it each pagination page in Liquid as `paginator`
and write the output to `blog/page:num/`, where `:num` is the pagination page number,
starting with `2`. If a site has 12 posts and specifies `paginate: 5`, Jekyll will write
`blog/index.html` with the first 5 posts, `blog/page2/index.html` with the next 5 posts
and `blog/page3/index.html` with the last 2 posts into the destination directory.
This will read in `blog/index.html`, send it each pagination page in Liquid as
`paginator` and write the output to `blog/page:num/`, where `:num` is the
pagination page number, starting with `2`. If a site has 12 posts and specifies
`paginate: 5`, Jekyll will write `blog/index.html` with the first 5 posts, `blog/page2/index.html` with the next 5 posts
and `blog/page3/index.html` with the last 2 posts into the destination
directory.
<div class="note warning">
<h5>Don't set a permalink</h5>
<p>
Setting a permalink in the front matter of your blog page will cause pagination to break. Just omit the permalink.
Setting a permalink in the front matter of your blog page will cause
pagination to break. Just omit the permalink.
</p>
</div>
@ -135,9 +137,9 @@ attributes:
## Render the paginated Posts
The next thing you need to do is to actually display your posts in a list using
the `paginator` variable that will now be available to you. You’ll probably want
to do this in one of the main pages of your site. Here’s one example of a simple
way of rendering paginated Posts in a HTML file:
the `paginator` variable that will now be available to you. You’ll probably
want to do this in one of the main pages of your site. Here’s one example of a
simple way of rendering paginated Posts in a HTML file:
{% highlight html %}
{% raw %}

12
site/_docs/permalinks.md
View File

@ -5,13 +5,13 @@ permalink: /docs/permalinks/
---
Jekyll supports a flexible way to build your site’s URLs. You can specify the
permalinks for your site through the [Configuration](../configuration/) or in the
[YAML Front Matter](../frontmatter/) for each post. You’re free to choose one of
the built-in styles to create your links or craft your own. The default style is
`date`.
permalinks for your site through the [Configuration](../configuration/) or in
the [YAML Front Matter](../frontmatter/) for each post. You’re free to choose
one of the built-in styles to create your links or craft your own. The default
style is `date`.
Permalinks are constructed by creating a template URL where dynamic elements are
represented by colon-prefixed keywords. For example, the default `date`
Permalinks are constructed by creating a template URL where dynamic elements
are represented by colon-prefixed keywords. For example, the default `date`
permalink is defined as `/:categories/:year/:month/:day/:title.html`.
## Template variables

24
site/_docs/plugins.md
View File

@ -25,11 +25,11 @@ having to modify the Jekyll source itself.
You have 3 options for installing plugins:
1. In your site source root, make a `_plugins` directory. Place your plugins here.
Any file ending in `*.rb` inside this directory will be loaded before Jekyll
generates your site.
2. In your `_config.yml` file, add a new array with the key `gems` and the values
of the gem names of the plugins you'd like to use. An example:
1. In your site source root, make a `_plugins` directory. Place your plugins
here. Any file ending in `*.rb` inside this directory will be loaded before
Jekyll generates your site.
2. In your `_config.yml` file, add a new array with the key `gems` and the
values of the gem names of the plugins you'd like to use. An example:
gems: [jekyll-test-plugin, jekyll-jsonify, jekyll-assets]
# This will require each of these gems automatically.
@ -47,7 +47,8 @@ You have 3 options for installing plugins:
</h5>
<p>
You may use any of the aforementioned plugin options simultaneously in the
same site if you so choose. Use of one does not restrict the use of the others.
same site if you so choose. Use of one does not restrict the use of the
others.
</p>
</div>
@ -383,10 +384,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
@ -476,7 +477,8 @@ You can find a few useful plugins at the following locations:
#### Generators
- [ArchiveGenerator by Ilkka Laukkanen](https://gist.github.com/707909): Uses [this archive page](https://gist.github.com/707020) to generate archives.
- [LESS.js Generator by Andy Fowler](https://gist.github.com/642739): Renders LESS.js files during generation.
- [LESS.js Generator by Andy Fowler](https://gist.github.com/642739): Renders
LESS.js files during generation.
- [Version Reporter by Blake Smith](https://gist.github.com/449491): Creates a version.html file containing the Jekyll version.
- [Sitemap.xml Generator by Michael Levin](https://github.com/kinnetica/jekyll-plugins): Generates a sitemap.xml file by traversing all of the available posts and pages.
- [Full-text search by Pascal Widdershoven](https://github.com/PascalW/jekyll_indextank): Adds full-text search to your Jekyll site with a plugin and a bit of JavaScript.

62
site/_docs/posts.md
View File

@ -76,17 +76,17 @@ decide which one best suits your needs.
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.
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
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 some
examples (in Markdown) of how you could do this using the `site.url` variable in
a post.
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
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:
@ -116,8 +116,8 @@ Linking to a PDF for readers to download:
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](../templates/)) is easy, thanks to the [Liquid template
language](http://wiki.shopify.com/Liquid) and its tags. Here’s a basic example of how
to create a list of links to your blog posts:
language](http://wiki.shopify.com/Liquid) and its tags. Here’s a basic example
of how to create a list of links to your blog posts:
{% highlight html %}
<ul>
@ -140,11 +140,11 @@ 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_separator`, and sets it as the `post.excerpt`.
Each post automatically takes the first block of text, from the beginning of
the content to the first occurrence of `excerpt_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:
a little hint about the post's content by adding the first paragraph of each of
your posts:
{% highlight html %}
<ul>
@ -157,20 +157,27 @@ posts:
</ul>
{% endhighlight %}
Because Jekyll grabs the first paragraph you will not need to wrap the excerpt in `p` tags,
which is already done for you. These tags can be removed with the following if you'd prefer:
Because Jekyll grabs the first paragraph you will not need to wrap the excerpt
in `p` tags, which is already done for you. These tags can be removed with the
following if you'd prefer:
{% highlight html %}
{% raw %}{{ post.excerpt | remove: '<p>' | remove: '</p>' }}{% endraw %}
{% endhighlight %}
If you don't like the automatically-generated post excerpt, it can be overridden by adding
`excerpt` to your post's YAML Front Matter. Completely disable it by setting
your `excerpt_separator` to `""`.
If you don't like the automatically-generated post excerpt, it can be
overridden by adding `excerpt` to your post's YAML Front Matter. Completely
disable it by setting your `excerpt_separator` to `""`.
Also, as with any output generated by Liquid tags, you can pass the `| strip_html` flag 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.
Also, as with any output generated by Liquid tags, you can pass the
`| strip_html` flag 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.
Additionally you are able to specify per-post `excerpt_separator` value if it is required just only the the selected post. Just specify the `excerpt_separator` with the same way as `excerpt` in the post's YAML head:
Additionally you are able to specify per-post `excerpt_separator` value if it
is required just only the the selected post. Just specify the
`excerpt_separator` with the same way as `excerpt` in the post's YAML head:
{% highlight text %}
---
@ -185,8 +192,8 @@ Out-of-excerpt
## Highlighting code snippets
Jekyll also has built-in support for syntax highlighting of code snippets using
either Pygments or Rouge, and including a code snippet in any post is easy. Just
use the dedicated Liquid tag as follows:
either Pygments or Rouge, and including a code snippet in any post is easy.
Just use the dedicated Liquid tag as follows:
{% highlight text %}
{% raw %}{% highlight ruby %}{% endraw %}
@ -222,6 +229,7 @@ end
</div>
These basics should be enough to get you started writing your first posts. When
you’re ready to dig into what else is possible, you might be interested in doing
things like [customizing post permalinks](../permalinks/) or using [custom
variables](../variables/) in your posts and elsewhere on your site.
you’re ready to dig into what else is possible, you might be interested in
doing things like [customizing post permalinks](../permalinks/) or
using [custom variables](../variables/) in your posts and elsewhere on your
site.

3
site/_docs/quickstart.md
View File

@ -14,7 +14,8 @@ For the impatient, here's how to get a boilerplate Jekyll site up and running.
# => Now browse to http://localhost:4000
{% endhighlight %}
If you wish to install jekyll into the current directory, you can do so by alternatively running `jekyll new .` instead of a new directory name.
If you wish to install jekyll into the current directory, you can do so by
alternatively running `jekyll new .` instead of a new directory name.
That's nothing, though. The real magic happens when you start creating blog
posts, using the front matter to control templates and layouts, and taking

2
site/_docs/resources.md
View File

@ -42,5 +42,7 @@ A guide to implementing a tag cloud and per-tag content pages using Jekyll.
- A way to [extend Jekyll](https://github.com/rfelix/jekyll_ext) without forking and modifying the Jekyll gem codebase and some [portable Jekyll extensions](https://wiki.github.com/rfelix/jekyll_ext/extensions) that can be reused and shared.
- [Using your Rails layouts in Jekyll](http://numbers.brighterplanet.com/2010/08/09/sharing-rails-views-with-jekyll)
- [Adding Ajax pagination to Jekyll](https://eduardoboucas.com/blog/2014/11/10/adding-ajax-pagination-to-jekyll.html)
- [Using Jekyll’s Data Files to build a dynamic navbar](http://www.jordanthornquest.com/blog/building-dynamic-navbars-with-jekyll/)

33
site/_docs/structure.md
View File

@ -8,8 +8,8 @@ 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 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, and the static web site is the final
the site URLs to look, what data gets displayed in the layout, and more. This
is all done through editing text files, and the static web site is the final
product.
A basic Jekyll site usually looks something like this:
@ -67,7 +67,9 @@ An overview of what each of these does:
<td>
<p>
Drafts are unpublished posts. The format of these files is without a date: <code>title.MARKUP</code>. Learn how to <a href="../drafts/">work with drafts</a>.
Drafts are unpublished posts. The format of these files is without a
date: <code>title.MARKUP</code>. Learn how to <a href="../drafts/">
work with drafts</a>.
</p>
</td>
@ -95,8 +97,9 @@ An overview of what each of these does:
<td>
<p>
These are the templates that wrap posts. Layouts are chosen on a post-
by-post basis in the <a href="../frontmatter/">YAML Front Matter</a>,
These are the templates that wrap posts. Layouts are chosen on a
post-by-post basis in the
<a href="../frontmatter/">YAML Front Matter</a>,
which is described in the next section. The liquid tag
<code>{% raw %}{{ content }}{% endraw %}</code>
is used to inject content into the web page.
@ -111,12 +114,12 @@ An overview of what each of these does:
<td>
<p>
Your dynamic content, so to speak. The naming convention of these files is
important, and must follow the format:
Your dynamic content, so to speak. The naming convention of these
files is important, and must follow the format:
<code>YEAR-MONTH-DAY-title.MARKUP</code>.
The <a href="../permalinks/">permalinks</a> can be customized for each
post, but the date and markup language are determined solely by the
file name.
The <a href="../permalinks/">permalinks</a> can be customized for
each post, but the date and markup language are determined solely by
the file name.
</p>
</td>
@ -128,10 +131,12 @@ An overview of what each of these does:
<td>
<p>
Well-formatted site data should be placed here. The jekyll engine will
autoload all yaml files (ends with <code>.yml</code> or <code>.yaml</code>)
in this directory. If there's a file <code>members.yml</code> under the directory,
then you can access contents of the file through <code>site.data.members</code>.
Well-formatted site data should be placed here. The jekyll engine
will autoload all yaml files (ends with
<code>.yml</code> or <code>.yaml</code>) in this directory. If
there's a file <code>members.yml</code> under the directory,
then you can access contents of the file
through <code>site.data.members</code>.
</p>
</td>

3
site/_docs/templates.md
View File

@ -405,7 +405,8 @@ You can also use this tag to create a link to a post in Markdown as follows:
### Gist
Use the `gist` tag to easily embed a GitHub Gist onto your site. This works with public or secret gists:
Use the `gist` tag to easily embed a GitHub Gist onto your site. This works
with public or secret gists:
{% highlight text %}
{% raw %}