diff --git a/site/_docs/collections.md b/site/_docs/collections.md index 81d0074b..f83190cb 100644 --- a/site/_docs/collections.md +++ b/site/_docs/collections.md @@ -11,13 +11,18 @@ permalink: /docs/collections/

-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. `/_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. `/_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 `/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 `/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 `/awesome/some_subdir/some_doc/index.html`.
@@ -95,7 +108,8 @@ For example, if you have `_my_collection/some_subdir/some_doc.md`, it will be wr

name

@@ -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:
-

The document's base filename, with every sequence of spaces and non-alphanumeric characters replaced by a hyphen.

+

The document's base filename, with every sequence of spaces + and non-alphanumeric characters replaced by a hyphen.
@@ -161,7 +180,8 @@ The collections are also available under `site.collections`, with the metadata y @@ -181,7 +201,8 @@ The collections are also available under `site.collections`, with the metadata y @@ -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:

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

- Whether the collection's documents will be output as individual files. + Whether the collection's documents will be output as individual + files.

@@ -209,8 +231,10 @@ In addition to any YAML Front Matter provided in the document's corresponding fi @@ -221,7 +245,8 @@ In addition to any YAML Front Matter provided in the document's corresponding fi @@ -253,7 +278,8 @@ In addition to any YAML Front Matter provided in the document's corresponding fi

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 render key in the site's configuration file. + included in the render key in the site's configuration + file.

diff --git a/site/_docs/configuration.md b/site/_docs/configuration.md index 827d99bd..836eed37 100644 --- a/site/_docs/configuration.md +++ b/site/_docs/configuration.md @@ -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.
There are two unsupported kramdown options

Please note that both remove_block_html_tags and - remove_span_html_tags are currently unsupported in Jekyll due to the - fact that they are not included within the kramdown HTML converter. + remove_span_html_tags are currently unsupported in Jekyll due + to the fact that they are not included within the kramdown HTML converter.

@@ -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 `` 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 `` 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 diff --git a/site/_docs/contributing.md b/site/_docs/contributing.md index 2ff5cd4f..b91c9d73 100644 --- a/site/_docs/contributing.md +++ b/site/_docs/contributing.md @@ -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.
Let us know what could be better!
diff --git a/site/_docs/datafiles.md b/site/_docs/datafiles.md index 7f54a279..2996eb52 100644 --- a/site/_docs/datafiles.md +++ b/site/_docs/datafiles.md @@ -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 %} diff --git a/site/_docs/drafts.md b/site/_docs/drafts.md index 9e7f1c6f..e50af474 100644 --- a/site/_docs/drafts.md +++ b/site/_docs/drafts.md @@ -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. diff --git a/site/_docs/frontmatter.md b/site/_docs/frontmatter.md index 8c08f7df..f21b765c 100644 --- a/site/_docs/frontmatter.md +++ b/site/_docs/frontmatter.md @@ -36,10 +36,10 @@ relies on.
ProTip™: Front Matter Variables Are Optional

- 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!) + 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!)

@@ -122,8 +122,8 @@ front matter of a page or post.

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.

@@ -170,8 +170,8 @@ These are available out-of-the-box to be used in the front matter for a post.
@@ -183,9 +183,9 @@ These are available out-of-the-box to be used in the front matter for a post.
ProTip™: Don't repeat yourself

- If you don't want to repeat your frequently used front matter variables over and over, - just define defaults - 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 defaults + for them and only override them where necessary (or not at all). This works + both for predefined and custom variables.

diff --git a/site/_docs/github-pages.md b/site/_docs/github-pages.md index eac7d1ea..86e9682a 100644 --- a/site/_docs/github-pages.md +++ b/site/_docs/github-pages.md @@ -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 diff --git a/site/_docs/installation.md b/site/_docs/installation.md index 0f4398b3..aee4b594 100644 --- a/site/_docs/installation.md +++ b/site/_docs/installation.md @@ -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) diff --git a/site/_docs/pages.md b/site/_docs/pages.md index d3008daf..fa76a9fb 100644 --- a/site/_docs/pages.md +++ b/site/_docs/pages.md @@ -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 %} . diff --git a/site/_docs/pagination.md b/site/_docs/pagination.md index 71403d2a..756e1480 100644 --- a/site/_docs/pagination.md +++ b/site/_docs/pagination.md @@ -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.
Pagination only works within HTML files

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

@@ -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.
Don't set a permalink

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

@@ -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 %} diff --git a/site/_docs/permalinks.md b/site/_docs/permalinks.md index bc9633b9..1435d1c8 100644 --- a/site/_docs/permalinks.md +++ b/site/_docs/permalinks.md @@ -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 diff --git a/site/_docs/plugins.md b/site/_docs/plugins.md index 6b62d3fe..3619d8ff 100644 --- a/site/_docs/plugins.md +++ b/site/_docs/plugins.md @@ -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:

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.

@@ -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. diff --git a/site/_docs/posts.md b/site/_docs/posts.md index 0b0e8773..c65dd2e2 100644 --- a/site/_docs/posts.md +++ b/site/_docs/posts.md @@ -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 %}
    @@ -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 %}
      @@ -157,20 +157,27 @@ posts:
    {% 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: '

    ' | remove: '

    ' }}{% 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 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. diff --git a/site/_docs/quickstart.md b/site/_docs/quickstart.md index 666ac03d..d8ad5511 100644 --- a/site/_docs/quickstart.md +++ b/site/_docs/quickstart.md @@ -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 diff --git a/site/_docs/structure.md b/site/_docs/structure.md index 848f1cce..e708ff25 100644 --- a/site/_docs/structure.md +++ b/site/_docs/structure.md @@ -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:
@@ -95,8 +97,9 @@ An overview of what each of these does: @@ -128,10 +131,12 @@ An overview of what each of these does: diff --git a/site/_docs/templates.md b/site/_docs/templates.md index 8014a2ee..637aeee6 100644 --- a/site/_docs/templates.md +++ b/site/_docs/templates.md @@ -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 %}

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

- The rendered output of the document, based on the content. + The rendered output of the document, based on the + content.

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

- Drafts are unpublished posts. The format of these files is without a date: title.MARKUP. Learn how to work with drafts. + Drafts are unpublished posts. The format of these files is without a + date: title.MARKUP. Learn how to + work with drafts.

- These are the templates that wrap posts. Layouts are chosen on a post- - by-post basis in the YAML Front Matter, + 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. @@ -111,12 +114,12 @@ An overview of what each of these does:

- 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: 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. + The permalinks can be customized for + each post, but the date and markup language are determined solely by + the file name.

- Well-formatted site data should be placed here. The jekyll engine will - autoload all yaml files (ends with .yml or .yaml) - in this directory. If there's a file members.yml under the directory, - then you can access contents of the file through site.data.members. + Well-formatted site data should be placed here. The jekyll engine + will autoload all yaml files (ends with + .yml or .yaml) in this directory. If + there's a file members.yml under the directory, + then you can access contents of the file + through site.data.members.