From 1cd880f9d09223a54a7d5eba0208652d3ab6a617 Mon Sep 17 00:00:00 2001 From: Ashwin Maroli Date: Sat, 20 Aug 2016 12:01:25 +0530 Subject: [PATCH] replace liquid highlight tag with backticks --- site/_docs/assets.md | 16 +++---- site/_docs/collections.md | 28 ++++++------ site/_docs/configuration.md | 48 ++++++++++---------- site/_docs/continuous-integration.md | 56 +++++++++++------------ site/_docs/datafiles.md | 32 ++++++------- site/_docs/deployment-methods.md | 41 +++++++++-------- site/_docs/drafts.md | 4 +- site/_docs/extras.md | 4 +- site/_docs/frontmatter.md | 8 ++-- site/_docs/github-pages.md | 12 ++--- site/_docs/installation.md | 16 +++---- site/_docs/pages.md | 8 ++-- site/_docs/pagination.md | 16 +++---- site/_docs/plugins.md | 48 ++++++++++---------- site/_docs/posts.md | 40 ++++++++-------- site/_docs/quickstart.md | 4 +- site/_docs/structure.md | 4 +- site/_docs/templates.md | 52 ++++++++++----------- site/_docs/themes.md | 4 +- site/_docs/troubleshooting.md | 68 ++++++++++++++-------------- site/_docs/upgrading/0-to-2.md | 4 +- site/_docs/upgrading/2-to-3.md | 24 +++++----- site/_docs/usage.md | 20 ++++---- site/_docs/windows.md | 16 +++---- 24 files changed, 287 insertions(+), 286 deletions(-) diff --git a/site/_docs/assets.md b/site/_docs/assets.md index fd163e06..4908a400 100644 --- a/site/_docs/assets.md +++ b/site/_docs/assets.md @@ -9,14 +9,14 @@ a Ruby gem. In order to use them, you must first create a file with the proper extension name (one of `.sass`, `.scss`, or `.coffee`) and ***start the file with two lines of triple dashes***, like this: -{% highlight sass %} +```sass --- --- // start content .my-definition font-size: 1.2em -{% endhighlight %} +``` Jekyll treats these files the same as a regular page, in that the output file will be placed in the same directory that it came from. For instance, if you @@ -46,10 +46,10 @@ If you are using Sass `@import` statements, you'll need to ensure that your `sass_dir` is set to the base directory that contains your Sass files. You can do that thusly: -{% highlight yaml %} +```yaml sass: sass_dir: _sass -{% endhighlight %} +``` The Sass converter will default the `sass_dir` configuration option to `_sass`. @@ -72,10 +72,10 @@ The Sass converter will default the `sass_dir` configuration option to You may also specify the output style with the `style` option in your `_config.yml` file: -{% highlight yaml %} +```yaml sass: style: compressed -{% endhighlight %} +``` These are passed to Sass, so any output style options Sass supports are valid here, too. @@ -88,7 +88,7 @@ To enable Coffeescript in Jekyll 3.0 and up you must * Install the `jekyll-coffeescript` gem * Ensure that your `_config.yml` is up-to-date and includes the following: -{% highlight yaml %} +```yaml gems: - jekyll-coffeescript -{% endhighlight %} +``` diff --git a/site/_docs/collections.md b/site/_docs/collections.md index c1e1e7c2..22a86e60 100644 --- a/site/_docs/collections.md +++ b/site/_docs/collections.md @@ -17,29 +17,29 @@ namespace. Add the following to your site's `_config.yml` file, replacing `my_collection` with the name of your collection: -{% highlight yaml %} +```yaml collections: - my_collection -{% endhighlight %} +``` You can optionally specify metadata for your collection in the configuration: -{% highlight yaml %} +```yaml collections: my_collection: foo: bar -{% endhighlight %} +``` Default attributes can also be set for a collection: -{% highlight yaml %} +```yaml defaults: - scope: path: "" type: my_collection values: layout: page -{% endhighlight %} +``` ### Step 2: Add your content @@ -62,11 +62,11 @@ 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 %} +```yaml collections: my_collection: output: true -{% endhighlight %} +``` This will produce a file for each document in the collection. For example, if you have `_my_collection/some_subdir/some_doc.md`, @@ -76,12 +76,12 @@ choice and written out to `/my_collection/some_subdir/some_doc.html`. As for posts with [Permalinks](../permalinks/), the document URL can be customized by setting `permalink` metadata for the collection: -{% highlight yaml %} +```yaml collections: my_collection: output: true 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`. @@ -339,7 +339,7 @@ one might have front matter in an individual file structured as follows (which must use a supported markup format, and cannot be saved with a `.yaml` extension): -{% highlight yaml %} +```yaml title: "Josquin: Missa De beata virgine and Missa Ave maris stella" artist: "The Tallis Scholars" director: "Peter Phillips" @@ -357,11 +357,11 @@ works: duration: "7:47" - title: "Agnus Dei I, II & III" duration: "6:49" -{% endhighlight %} +``` Every album in the collection could be listed on a single page with a template: -{% highlight html %} +```html {% raw %} {% for album in site.albums %}

{{ album.title }}

@@ -377,4 +377,4 @@ Every album in the collection could be listed on a single page with a template: {% endfor %} {% endfor %} {% endraw %} -{% endhighlight %} +``` diff --git a/site/_docs/configuration.md b/site/_docs/configuration.md index 82f3436d..abb9e234 100644 --- a/site/_docs/configuration.md +++ b/site/_docs/configuration.md @@ -399,13 +399,13 @@ before your site is served. You can provide custom headers for your site by adding them to `_config.yml` -{% highlight yaml %} +```yaml # File: _config.yml webrick: headers: My-Header: My-Value My-Other-Header: My-Other-Value -{% endhighlight %} +``` ### Defaults @@ -420,19 +420,19 @@ In the build (or serve) arguments, you can specify a Jekyll environment and valu For example, suppose you set this conditional statement in your code: -{% highlight liquid %} +```liquid {% raw %} {% if jekyll.environment == "production" %} {% include disqus.html %} {% endif %} {% endraw %} -{% endhighlight %} +``` When you build your Jekyll site, the content inside the `if` statement won't be run unless you also specify a `production` environment in the build command, like this: -{% highlight sh %} +```sh JEKYLL_ENV=production jekyll build -{% endhighlight %} +``` Specifying an environment value allows you to make certain content available only within specific environments. @@ -454,14 +454,14 @@ The `defaults` key holds an array of scope/values pairs that define what default Let's say that you want to add a default layout to all pages and posts in your site. You would add this to your `_config.yml` file: -{% highlight yaml %} +```yaml defaults: - scope: path: "" # an empty string here means all files in the project values: layout: "default" -{% endhighlight %} +```
Please stop and rerun `jekyll serve` command.
@@ -477,7 +477,7 @@ defaults: Here, we are scoping the `values` to any file that exists in the path `scope`. Since the path is set as an empty string, it will apply to **all files** in your project. You probably don't want to set a layout on every file in your project - like css files, for example - so you can also specify a `type` value under the `scope` key. -{% highlight yaml %} +```yaml defaults: - scope: @@ -485,14 +485,14 @@ defaults: type: "posts" # previously `post` in Jekyll 2.2. values: layout: "default" -{% endhighlight %} +``` Now, this will only set the layout for files where the type is `posts`. The different types that are available to you are `pages`, `posts`, `drafts` or any collection in your site. While `type` is optional, you must specify a value for `path` when creating a `scope/values` pair. As mentioned earlier, you can set multiple scope/values pairs for `defaults`. -{% highlight yaml %} +```yaml defaults: - scope: @@ -507,11 +507,11 @@ defaults: values: layout: "project" # overrides previous default layout author: "Mr. Hyde" -{% endhighlight %} +``` With these defaults, all posts would use the `my-site` layout. Any html files that exist in the `projects/` folder will use the `project` layout, if it exists. Those files will also have the `page.author` [liquid variable](../variables/) set to `Mr. Hyde`. -{% highlight yaml %} +```yaml collections: - my_collection: output: true @@ -523,7 +523,7 @@ defaults: type: "my_collection" # a collection in your site, in plural form values: layout: "default" -{% endhighlight %} +``` In this example, the `layout` is set to `default` inside the [collection](../collections/) with the name `my_collection`. @@ -536,7 +536,7 @@ You can see that in the second to last example above. First, we set the default Finally, if you set defaults in the site configuration by adding a `defaults` section to your `_config.yml` file, you can override those settings in a post or page file. All you need to do is specify the settings in the post or page front matter. For example: -{% highlight yaml %} +```yaml # In _config.yml ... defaults: @@ -549,16 +549,16 @@ defaults: author: "Mr. Hyde" category: "project" ... -{% endhighlight %} +``` -{% highlight yaml %} +```yaml # In projects/foo_project.md --- author: "John Smith" 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 @@ -579,7 +579,7 @@ file or on the command-line.

-{% highlight yaml %} +```yaml # Where things are source: . destination: ./_site @@ -651,7 +651,7 @@ kramdown: input: GFM hard_wrap: false footnote_nr: 1 -{% endhighlight %} +``` ## Liquid Options @@ -715,7 +715,7 @@ extensions are: If you're interested in creating a custom markdown processor, you're in luck! Create a new class in the `Jekyll::Converters::Markdown` namespace: -{% highlight ruby %} +```ruby class Jekyll::Converters::Markdown::MyCustomProcessor def initialize(config) require 'funky_markdown' @@ -730,14 +730,14 @@ class Jekyll::Converters::Markdown::MyCustomProcessor ::FunkyMarkdown.new(content).convert end end -{% endhighlight %} +``` Once you've created your class and have it properly set up either as a plugin in the `_plugins` folder or as a gem, specify it in your `_config.yml`: -{% highlight yaml %} +```yaml markdown: MyCustomProcessor -{% endhighlight %} +``` ## Incremental Regeneration
diff --git a/site/_docs/continuous-integration.md b/site/_docs/continuous-integration.md index c01d1d1b..4599115d 100644 --- a/site/_docs/continuous-integration.md +++ b/site/_docs/continuous-integration.md @@ -38,13 +38,13 @@ Save the commands you want to run and succeed in a file: `./script/cibuild` ### The HTML Proofer Executable -{% highlight shell %} +```sh #!/usr/bin/env bash set -e # halt script on error bundle exec jekyll build bundle exec htmlproofer ./_site -{% endhighlight %} +``` Some options can be specified via command-line switches. Check out the `html-proofer` README for more information about these switches, or run @@ -52,20 +52,20 @@ Some options can be specified via command-line switches. Check out the For example to avoid testing external sites, use this command: -{% highlight shell %} +```sh $ bundle exec htmlproofer ./_site --disable-external -{% endhighlight %} +``` ### The HTML Proofer Library You can also invoke `html-proofer` in Ruby scripts (e.g. in a Rakefile): -{% highlight ruby %} +```ruby #!/usr/bin/env ruby require 'html-proofer' HTMLProofer.check_directory("./_site").run -{% endhighlight %} +``` Options are given as a second argument to `.new`, and are encoded in a symbol-keyed Ruby Hash. For more information about the configuration options, @@ -82,16 +82,16 @@ an explanation of each line. **Note:** You will need a Gemfile as well, [Travis will automatically install](https://docs.travis-ci.com/user/languages/ruby/#Dependency-Management) the dependencies based on the referenced gems: -{% highlight ruby %} +```ruby source "https://rubygems.org" gem "jekyll" gem "html-proofer" -{% endhighlight %} +``` Your `.travis.yml` file should look like this: -{% highlight yaml %} +```yaml language: ruby rvm: - 2.1 @@ -114,39 +114,39 @@ env: - NOKOGIRI_USE_SYSTEM_LIBRARIES=true # speeds up installation of html-proofer sudo: false # route your build to the container-based infrastructure for a faster build -{% endhighlight %} +``` Ok, now for an explanation of each line: -{% highlight yaml %} +```yaml language: ruby -{% endhighlight %} +``` This line tells Travis to use a Ruby build container. It gives your script access to Bundler, RubyGems, and a Ruby runtime. -{% highlight yaml %} +```yaml rvm: - 2.1 -{% endhighlight %} +``` RVM is a popular Ruby Version Manager (like rbenv, chruby, etc). This directive tells Travis the Ruby version to use when running your test script. -{% highlight yaml %} +```yaml before_script: - chmod +x ./script/cibuild -{% endhighlight %} +``` The build script file needs to have the *executable* attribute set or Travis will fail with a permission denied error. You can also run this locally and commit the permissions directly, thus rendering this step irrelevant. -{% highlight yaml %} +```yaml script: ./script/cibuild -{% endhighlight %} +``` Travis allows you to run any arbitrary shell script to test your site. One convention is to put all scripts for your project in the `script` @@ -154,20 +154,20 @@ directory, and to call your test script `cibuild`. This line is completely customizable. If your script won't change much, you can write your test incantation here directly: -{% highlight yaml %} +```yaml install: gem install jekyll html-proofer script: jekyll build && htmlproofer ./_site -{% endhighlight %} +``` The `script` directive can be absolutely any valid shell command. -{% highlight yaml %} +```yaml # branch whitelist, only for GitHub Pages branches: only: - gh-pages # test the gh-pages branch - /pages-(.*)/ # test every branch which starts with "pages-" -{% endhighlight %} +``` You want to ensure the Travis builds for your site are being run only on the branch or branches which contain your site. One means of ensuring this @@ -181,11 +181,11 @@ prefixed, exemplified above with the `/pages-(.*)/` regular expression. The `branches` directive is completely optional. Travis will build from every push to any branch of your repo if leave it out. -{% highlight yaml %} +```yaml env: global: - NOKOGIRI_USE_SYSTEM_LIBRARIES=true # speeds up installation of html-proofer -{% endhighlight %} +``` Using `html-proofer`? You'll want this environment variable. Nokogiri, used to parse HTML files in your compiled site, comes bundled with libraries @@ -200,9 +200,9 @@ environment variable `NOKOGIRI_USE_SYSTEM_LIBRARIES` to `true`. servers, which Jekyll will mistakenly read and explode on.

-{% highlight yaml %} +```yaml exclude: [vendor] -{% endhighlight %} +``` By default you should supply the `sudo: false` command to Travis. This command explicitly tells Travis to run your build on Travis's [container-based @@ -210,9 +210,9 @@ explicitly tells Travis to run your build on Travis's [container-based speed up your build. If you have any trouble with your build, or if your build does need `sudo` access, modify the line to `sudo: required`. -{% highlight yaml %} +```yaml sudo: false -{% endhighlight %} +``` ### Troubleshooting diff --git a/site/_docs/datafiles.md b/site/_docs/datafiles.md index 474e8e82..d61c1bfa 100644 --- a/site/_docs/datafiles.md +++ b/site/_docs/datafiles.md @@ -32,7 +32,7 @@ of code in your Jekyll templates: In `_data/members.yml`: -{% highlight yaml %} +```yaml - name: Eric Mill github: konklone @@ -41,23 +41,23 @@ In `_data/members.yml`: - name: Liu Fengyun github: liufengyun -{% endhighlight %} +``` Or `_data/members.csv`: -{% highlight text %} +```text name,github Eric Mill,konklone Parker Moore,parkr Liu Fengyun,liufengyun -{% endhighlight %} +``` This data can be accessed via `site.data.members` (notice that the filename determines the variable name). You can now render the list of members in a template: -{% highlight html %} +```html {% raw %}
    {% for member in site.data.members %} @@ -69,7 +69,7 @@ You can now render the list of members in a template: {% endfor %}
{% endraw %} -{% endhighlight %} +``` ## Example: Organizations @@ -80,7 +80,7 @@ folder: In `_data/orgs/jekyll.yml`: -{% highlight yaml %} +```yaml username: jekyll name: Jekyll members: @@ -89,22 +89,22 @@ members: - name: Parker Moore github: parkr -{% endhighlight %} +``` In `_data/orgs/doeorg.yml`: -{% highlight yaml %} +```yaml username: doeorg name: Doe Org members: - name: John Doe github: jdoe -{% endhighlight %} +``` The organizations can then be accessed via `site.data.orgs`, followed by the file name: -{% highlight html %} +```html {% raw %}
    {% for org_hash in site.data.orgs %} @@ -118,22 +118,22 @@ file name: {% endfor %}
{% endraw %} -{% endhighlight %} +``` ## Example: Accessing a specific author Pages and posts can also access a specific data item. The example below shows how to access a specific item: `_data/people.yml`: -{% highlight yaml %} +```yaml dave: name: David Smith twitter: DavidSilvaSmith -{% endhighlight %} +``` The author can then be specified as a page variable in a post's frontmatter: -{% highlight html %} +```html {% raw %} --- title: sample post @@ -148,4 +148,4 @@ author: dave {% endraw %} -{% endhighlight %} +``` diff --git a/site/_docs/deployment-methods.md b/site/_docs/deployment-methods.md index af6edf73..7391fe03 100644 --- a/site/_docs/deployment-methods.md +++ b/site/_docs/deployment-methods.md @@ -35,19 +35,19 @@ this](http://web.archive.org/web/20091223025644/http://www.taknado.com/en/2009/0 To have a remote server handle the deploy for you every time you push changes using Git, you can create a user account which has all the public keys that are authorized to deploy in its `authorized_keys` file. With that in place, setting up the post-receive hook is done as follows: -{% highlight shell %} +```sh laptop$ ssh deployer@example.com server$ mkdir myrepo.git server$ cd myrepo.git server$ git --bare init server$ cp hooks/post-receive.sample hooks/post-receive server$ mkdir /var/www/myrepo -{% endhighlight %} +``` Next, add the following lines to hooks/post-receive and be sure Jekyll is installed on the server: -{% highlight shell %} +```sh GIT_REPO=$HOME/myrepo.git TMP_GIT_CLONE=$HOME/tmp/myrepo PUBLIC_WWW=/var/www/myrepo @@ -56,21 +56,21 @@ git clone $GIT_REPO $TMP_GIT_CLONE jekyll build -s $TMP_GIT_CLONE -d $PUBLIC_WWW rm -Rf $TMP_GIT_CLONE exit -{% endhighlight %} +``` Finally, run the following command on any users laptop that needs to be able to deploy using this hook: -{% highlight shell %} +```sh laptops$ git remote add deploy deployer@example.com:~/myrepo.git -{% endhighlight %} +``` Deploying is now as easy as telling nginx or Apache to look at `/var/www/myrepo` and running the following: -{% highlight shell %} +```sh laptops$ git push deploy master -{% endhighlight %} +``` ### Jekyll-hook @@ -98,12 +98,13 @@ Another way to deploy your Jekyll site is to use [Rake](https://github.com/ruby/ ### scp Once you’ve generated the `_site` directory, you can easily scp it using a -`tasks/deploy` shell script similar to this: +`tasks/deploy` shell script similar to [this deploy script][]. You’d obviously +need to change the values to reflect your site’s details. There is even [a +matching TextMate command][] that will help you run this script. - #!/bin/bash - - scp -r _site/* user@server:/home/user/public_html +[this deploy script here]: https://github.com/henrik/henrik.nyh.se/blob/master/script/deploy +[a matching TextMate command]: https://gist.github.com/henrik/214959 ### rsync @@ -128,9 +129,9 @@ is to put the restriction to certificate-based authorization in `~/.ssh/authorized_keys`. Then, launch `rrsync` and supply it with the folder it shall have read-write access to: -{% highlight shell %} +```sh command="$HOME/bin/rrsync ",no-agent-forwarding,no-port-forwarding,no-pty,no-user-rc,no-X11-forwarding ssh-rsa -{% endhighlight %} +``` `` is the path to your site. E.g., `~/public_html/you.org/blog-html/`. @@ -138,11 +139,11 @@ command="$HOME/bin/rrsync ",no-agent-forwarding,no-port-forwarding,no-pt Add the `deploy` script to the site source folder: -{% highlight shell %} +```sh #!/bin/sh rsync -crvz --rsh='ssh -p2222' --delete-after --delete-excluded @: -{% endhighlight %} +``` Command line parameters are: @@ -154,9 +155,9 @@ your host uses a different port than the default (e.g, HostGator) Using this setup, you might run the following command: -{% highlight shell %} +```sh rsync -crvz --rsh='ssh -p2222' --delete-after --delete-excluded _site/ hostuser@example.org: -{% endhighlight %} +``` Don't forget the column `:` after server name! @@ -168,10 +169,10 @@ copy it to the output folder. This behavior can be changed in `_config.yml`. Just add the following line: -{% highlight yaml %} +```yaml # Do not copy these files to the output directory exclude: ["deploy"] -{% endhighlight %} +``` Alternatively, you can use an `rsync-exclude.txt` file to control which files will be transferred to your server. diff --git a/site/_docs/drafts.md b/site/_docs/drafts.md index e50af474..d5513f75 100644 --- a/site/_docs/drafts.md +++ b/site/_docs/drafts.md @@ -9,10 +9,10 @@ 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 %} +```text |-- _drafts/ | |-- 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 diff --git a/site/_docs/extras.md b/site/_docs/extras.md index 5abd0d73..83e79963 100644 --- a/site/_docs/extras.md +++ b/site/_docs/extras.md @@ -11,9 +11,9 @@ may want to install, depending on how you plan to use Jekyll. Kramdown comes with optional support for LaTeX to PNG rendering via [MathJax](https://www.mathjax.org) within math blocks. See the Kramdown documentation on [math blocks](http://kramdown.gettalong.org/syntax.html#math-blocks) and [math support](http://kramdown.gettalong.org/converter/html.html#math-support) for more details. MathJax requires you to include JavaScript or CSS to render the LaTeX, e.g. -{% highlight html %} +```html -{% endhighlight %} +``` For more information about getting started, check out [this excellent blog post](http://gastonsanchez.com/opinion/2014/02/16/Mathjax-with-jekyll/). diff --git a/site/_docs/frontmatter.md b/site/_docs/frontmatter.md index faf67b73..7e427552 100644 --- a/site/_docs/frontmatter.md +++ b/site/_docs/frontmatter.md @@ -10,12 +10,12 @@ Jekyll as a special file. The front matter must be the first thing in the file and must take the form of valid YAML set between triple-dashed lines. Here is a basic example: -{% highlight yaml %} +```yaml --- layout: post title: Blogging Like a Hacker --- -{% endhighlight %} +``` Between these triple-dashed lines, you can set predefined variables (see below for a reference) or even create custom ones of your own. These variables will @@ -108,7 +108,7 @@ data that is sent to the Liquid templating engine during the conversion. For instance, if you set a title, you can use that in your layout to set the page title: -{% highlight html %} +```html @@ -116,7 +116,7 @@ title: ... -{% endhighlight %} +``` ## Predefined Variables for Posts diff --git a/site/_docs/github-pages.md b/site/_docs/github-pages.md index 4a4c3895..6a449d68 100644 --- a/site/_docs/github-pages.md +++ b/site/_docs/github-pages.md @@ -22,14 +22,14 @@ branch to GitHub. However, the subdirectory-like URL structure GitHub uses for Project Pages complicates the proper resolution of URLs. In order to assure your site builds properly, use `site.github.url` in your URL's. -{% highlight html %} +```html {% raw %} {{ page.title }} {% endraw %} -{% endhighlight %} +``` 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 @@ -54,7 +54,7 @@ few minor details. currently-deployed version of the gem in your project, add the following to your Gemfile: -{% highlight ruby %} +```ruby source 'https://rubygems.org' require 'json' @@ -62,18 +62,18 @@ require 'open-uri' versions = JSON.parse(open('https://pages.github.com/versions.json').read) gem 'github-pages', versions['github-pages'] -{% endhighlight %} +``` This will ensure that when you run bundle install, you have the correct version of the github-pages gem. If that fails, simplify it: -{% highlight ruby %} +```ruby source 'https://rubygems.org' gem 'github-pages' -{% endhighlight %} +``` And be sure to run bundle update often. diff --git a/site/_docs/installation.md b/site/_docs/installation.md index f608a299..b86d179e 100644 --- a/site/_docs/installation.md +++ b/site/_docs/installation.md @@ -37,9 +37,9 @@ The best way to install Jekyll is via [RubyGems](http://rubygems.org/pages/download). At the terminal prompt, simply run the following command to install Jekyll: -{% highlight shell %} +```sh $ gem install jekyll -{% endhighlight %} +``` All of Jekyll’s gem dependencies are automatically installed by the above command, so you won’t have to worry about them at all. If you have problems @@ -62,28 +62,28 @@ community can improve the experience for everyone. In order to install a pre-release, make sure you have all the requirements installed properly and run: -{% highlight shell %} +```sh gem install jekyll --pre -{% endhighlight %} +``` This will install the latest pre-release. If you want a particular pre-release, use the `-v` switch to indicate the version you'd like to install: -{% highlight shell %} +```sh gem install jekyll -v '2.0.0.alpha.1' -{% endhighlight %} +``` If you'd like to install a development version of Jekyll, the process is a bit more involved. This gives you the advantage of having the latest and greatest, but may be unstable. -{% highlight shell %} +```sh $ git clone git://github.com/jekyll/jekyll.git $ cd jekyll $ script/bootstrap $ bundle exec rake build $ ls pkg/*.gem | head -n 1 | xargs gem install -l -{% endhighlight %} +``` ## Optional Extras diff --git a/site/_docs/pages.md b/site/_docs/pages.md index 48ba3de6..15e8f830 100644 --- a/site/_docs/pages.md +++ b/site/_docs/pages.md @@ -46,7 +46,7 @@ directory with a suitable name for the page you want to create. For a site with a homepage, an about page, and a contact page, here’s what the root directory and associated URLs might look like: -{% highlight shell %} +```sh . |-- _config.yml |-- _includes/ @@ -57,7 +57,7 @@ and associated URLs might look like: |-- index.html # => http://example.com/ |-- other.md # => http://example.com/other.html └── contact.html # => http://example.com/contact.html -{% endhighlight %} +``` ### Named folders containing index HTML files @@ -69,7 +69,7 @@ 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 shell %} +```sh . ├── _config.yml ├── _includes/ @@ -83,7 +83,7 @@ might look like: |── other/ | └── index.md # => http://example.com/other/ └── index.html # => http://example.com/ -{% endhighlight %} +``` This approach may not suit everyone, but for people who like clean URLs it’s simple and it works. In the end, the decision is yours! diff --git a/site/_docs/pagination.md b/site/_docs/pagination.md index 1ef2d496..b32b934c 100644 --- a/site/_docs/pagination.md +++ b/site/_docs/pagination.md @@ -28,18 +28,18 @@ your `_config.yml` under `gems`. For Jekyll 2, this is standard. To enable pagination for your blog, add a line to the `_config.yml` file that specifies how many items should be displayed per page: -{% highlight yaml %} +```yaml paginate: 5 -{% endhighlight %} +``` 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: -{% highlight yaml %} +```yaml 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 @@ -146,7 +146,7 @@ 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 %} +```html {% raw %} --- layout: default @@ -179,7 +179,7 @@ title: My Blog {% endif %} {% endraw %} -{% endhighlight %} +```
Beware the page one edge-case
@@ -193,7 +193,7 @@ title: My Blog The following HTML snippet should handle page one, and render a list of each page with links to all but the current page. -{% highlight html %} +```html {% raw %} {% if paginator.total_pages > 1 %} {% endif %} {% endraw %} -{% endhighlight %} +``` diff --git a/site/_docs/plugins.md b/site/_docs/plugins.md index b6a12932..218a9443 100644 --- a/site/_docs/plugins.md +++ b/site/_docs/plugins.md @@ -93,7 +93,7 @@ For instance, a generator can inject values computed at build time for template variables. In the following example the template `reading.html` has two variables `ongoing` and `done` that we fill in the generator: -{% highlight ruby %} +```ruby module Reading class Generator < Jekyll::Generator def generate(site) @@ -105,11 +105,11 @@ module Reading end end end -{% endhighlight %} +``` This is a more complex generator that generates new pages: -{% highlight ruby %} +```ruby module Jekyll class CategoryPage < Page @@ -142,7 +142,7 @@ module Jekyll end end -{% endhighlight %} +``` In this example, our generator will create a series of files under the `categories` directory for each category, listing the posts in each category @@ -189,7 +189,7 @@ languages are implemented using this method. Below is a converter that will take all posts ending in `.upcase` and process them using the `UpcaseConverter`: -{% highlight ruby %} +```ruby module Jekyll class UpcaseConverter < Converter safe true @@ -208,7 +208,7 @@ module Jekyll end end end -{% endhighlight %} +``` Converters should implement at a minimum 3 methods: @@ -266,16 +266,16 @@ As of version 2.5.0, Jekyll can be extended with plugins which provide subcommands for the `jekyll` executable. This is possible by including the relevant plugins in a `Gemfile` group called `:jekyll_plugins`: -{% highlight ruby %} +```ruby group :jekyll_plugins do gem "my_fancy_jekyll_plugin" end -{% endhighlight %} +``` Each `Command` must be a subclass of the `Jekyll::Command` class and must contain one class method: `init_with_program`. An example: -{% highlight ruby %} +```ruby class MyNewCommand < Jekyll::Command class << self def init_with_program(prog) @@ -292,7 +292,7 @@ class MyNewCommand < Jekyll::Command end end end -{% endhighlight %} +``` Commands should implement this single class method: @@ -328,7 +328,7 @@ hooking into the tagging system. Built-in examples added by Jekyll include the `highlight` and `include` tags. Below is an example of a custom liquid tag that will output the time the page was rendered: -{% highlight ruby %} +```ruby module Jekyll class RenderTimeTag < Liquid::Tag @@ -344,7 +344,7 @@ module Jekyll end Liquid::Template.register_tag('render_time', Jekyll::RenderTimeTag) -{% endhighlight %} +``` At a minimum, liquid tags must implement: @@ -372,24 +372,24 @@ At a minimum, liquid tags must implement: You must also register the custom tag with the Liquid template engine as follows: -{% highlight ruby %} +```ruby Liquid::Template.register_tag('render_time', Jekyll::RenderTimeTag) -{% endhighlight %} +``` In the example above, we can place the following tag anywhere in one of our pages: -{% highlight ruby %} +```ruby {% raw %}

{% render_time page rendered at: %}

{% endraw %} -{% endhighlight %} +``` And we would get something like this on the page: -{% highlight html %} +```html

page rendered at: Tue June 22 23:38:47 –0500 2010

-{% endhighlight %} +``` ### Liquid filters @@ -398,7 +398,7 @@ 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 %} +```ruby module Jekyll module AssetFilter def asset_url(input) @@ -408,7 +408,7 @@ module Jekyll end Liquid::Template.register_filter(Jekyll::AssetFilter) -{% endhighlight %} +```
ProTip™: Access the site object using Liquid
@@ -469,7 +469,7 @@ There are two flags to be aware of when writing a plugin: To use one of the example plugins above as an illustration, here is how you’d specify these two flags: -{% highlight ruby %} +```ruby module Jekyll class UpcaseConverter < Converter safe true @@ -477,7 +477,7 @@ module Jekyll ... end end -{% endhighlight %} +``` ## Hooks @@ -491,11 +491,11 @@ call whenever the hook is triggered. For example, if you want to execute some custom functionality every time Jekyll renders a post, you could register a hook like this: -{% highlight ruby %} +```ruby Jekyll::Hooks.register :posts, :post_render do |post| # code to call after Jekyll renders a post end -{% endhighlight %} +``` Jekyll provides hooks for :site, :pages, :posts, and :documents. In all cases, Jekyll calls your diff --git a/site/_docs/posts.md b/site/_docs/posts.md index 2a9bf3fa..0253dbac 100644 --- a/site/_docs/posts.md +++ b/site/_docs/posts.md @@ -27,18 +27,18 @@ To create a new post, all you need to do is create a file in the `_posts` directory. How you name files in this folder is important. Jekyll requires blog post files to be named according to the following format: -{% highlight shell %} +```sh YEAR-MONTH-DAY-title.MARKUP -{% endhighlight %} +``` Where `YEAR` is a four-digit number, `MONTH` and `DAY` are both two-digit numbers, and `MARKUP` is the file extension representing the format used in the file. For example, the following are examples of valid post filenames: -{% highlight shell %} +```sh 2011-12-31-new-years-eve-is-awesome.md 2012-09-12-how-to-write-a-blog.textile -{% endhighlight %} +```
ProTip™: Link to other posts
@@ -90,16 +90,16 @@ variable in a post. Including an image asset in a post: -{% highlight text %} +```text ... which is shown in the screenshot below: ![My helpful screenshot]({% raw %}{{ site.url }}{% endraw %}/assets/screenshot.jpg) -{% endhighlight %} +``` Linking to a PDF for readers to download: -{% highlight text %} +```text ... you can [get the PDF]({% raw %}{{ site.url }}{% endraw %}/assets/mydoc.pdf) directly. -{% endhighlight %} +```
ProTip™: Link using just the site root URL
@@ -119,7 +119,7 @@ you have a list of posts somewhere. Creating an index of posts on another page language](https://docs.shopify.com/themes/liquid/basics) and its tags. Here’s a basic example of how to create a list of links to your blog posts: -{% highlight html %} +```html
    {% raw %}{% for post in site.posts %}{% endraw %}
  • @@ -127,7 +127,7 @@ basic example of how to create a list of links to your blog posts:
    • {% raw %}{% endfor %}{% endraw %}
-{% endhighlight %} +``` Of course, you have full control over how (and where) you display your posts, and how you structure your site. You should read more about [how templates @@ -146,7 +146,7 @@ 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: -{% highlight html %} +```html
    {% raw %}{% for post in site.posts %}{% endraw %}
  • @@ -155,22 +155,22 @@ your posts:
    • {% raw %}{% endfor %}{% endraw %}
-{% 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: -{% highlight html %} +```html {% raw %}{{ post.excerpt | remove: '

' | remove: '

' }}{% endraw %} -{% endhighlight %} +``` If you don't like the automatically-generated post excerpt, it can be explicitly overridden by adding an `excerpt` value to your post's YAML Front Matter. Alternatively, you can choose to define a custom `excerpt_separator` in the post's YAML front matter: -{% highlight text %} +```text --- excerpt_separator: --- @@ -178,7 +178,7 @@ excerpt_separator: Excerpt Out-of-excerpt -{% endhighlight %} +``` You can also set the `excerpt_separator` globally in your `_config.yml` configuration file. @@ -197,7 +197,7 @@ 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: -{% highlight text %} +```text {% raw %}{% highlight ruby %}{% endraw %} def show @widget = Widget(params[:id]) @@ -207,11 +207,11 @@ def show end end {% raw %}{% endhighlight %}{% endraw %} -{% endhighlight %} +``` And the output will look like this: -{% highlight ruby %} +```ruby def show @widget = Widget(params[:id]) respond_to do |format| @@ -219,7 +219,7 @@ def show format.json { render json: @widget } end end -{% endhighlight %} +```
ProTip™: Show line numbers
diff --git a/site/_docs/quickstart.md b/site/_docs/quickstart.md index 81bd74d2..b6cb5895 100644 --- a/site/_docs/quickstart.md +++ b/site/_docs/quickstart.md @@ -6,14 +6,14 @@ permalink: /docs/quickstart/ For the impatient, here's how to get a boilerplate Jekyll site up and running. -{% highlight shell %} +```sh ~ $ gem install jekyll bundler ~ $ jekyll new myblog ~ $ cd myblog ~/myblog $ bundle install ~/myblog $ bundle exec jekyll serve # => Now browse to http://localhost:4000 -{% endhighlight %} +``` If you wish to install jekyll into an existing directory, you can do so by running `jekyll new .` from within the directory instead of creating a new one. If the existing directory isn't empty, you'll also have to pass the `--force` option like so `jekyll new . --force`. diff --git a/site/_docs/structure.md b/site/_docs/structure.md index 227b8491..de077c5e 100644 --- a/site/_docs/structure.md +++ b/site/_docs/structure.md @@ -14,7 +14,7 @@ product. A basic Jekyll site usually looks something like this: -{% highlight shell %} +```sh . ├── _config.yml ├── _drafts @@ -34,7 +34,7 @@ A basic Jekyll site usually looks something like this: ├── _site ├── .jekyll-metadata └── index.html -{% endhighlight %} +``` An overview of what each of these does: diff --git a/site/_docs/templates.md b/site/_docs/templates.md index 080ac5fa..55bd8b5b 100644 --- a/site/_docs/templates.md +++ b/site/_docs/templates.md @@ -374,9 +374,9 @@ The default is `default`. They are as follows (with what they filter): If you have small page fragments that you wish to include in multiple places on your site, you can use the `include` tag. -{% highlight liquid %} +```liquid {% raw %}{% include footer.html %}{% endraw %} -{% endhighlight %} +``` Jekyll expects all include files to be placed in an `_includes` directory at the root of your source directory. This will embed the contents of @@ -395,23 +395,23 @@ root of your source directory. This will embed the contents of You can also pass parameters to an include. Omit the quotation marks to send a variable's value. Liquid curly brackets should not be used here: -{% highlight liquid %} +```liquid {% raw %}{% include footer.html param="value" variable-param=page.variable %}{% endraw %} -{% endhighlight %} +``` These parameters are available via Liquid in the include: -{% highlight liquid %} +```liquid {% raw %}{{ include.param }}{% endraw %} -{% endhighlight %} +``` #### Including files relative to another file You can also choose to include file fragments relative to the current file: -{% highlight liquid %} +```liquid {% raw %}{% include_relative somedir/footer.html %}{% endraw %} -{% endhighlight %} +``` You won't need to place your included content within the `_includes` directory. Instead, the inclusion is specifically relative to the file where the tag is being used. For example, @@ -437,7 +437,7 @@ languages](http://pygments.org/languages/) To render a code block with syntax highlighting, surround your code as follows: -{% highlight liquid %} +```liquid {% raw %} {% highlight ruby %} def foo @@ -445,7 +445,7 @@ def foo end {% endhighlight %} {% endraw %} -{% endhighlight %} +``` The argument to the `highlight` tag (`ruby` in the example above) is the language identifier. To find the appropriate identifier to use for the language @@ -460,7 +460,7 @@ Including the `linenos` argument will force the highlighted code to include line numbers. For instance, the following code block would include line numbers next to each line: -{% highlight liquid %} +```liquid {% raw %} {% highlight ruby linenos %} def foo @@ -468,7 +468,7 @@ def foo end {% endhighlight %} {% endraw %} -{% endhighlight %} +``` #### Stylesheets for syntax highlighting @@ -488,21 +488,21 @@ specify. You must include the file extension when using the `link` tag. -{% highlight liquid %} +```liquid {% raw %} {% link _collection/name-of-document.md %} {% link _posts/2016-07-26-name-of-post.md %} {% endraw %} -{% endhighlight %} +``` You can also use this tag to create a link in Markdown as follows: -{% highlight liquid %} +```liquid {% raw %} [Link to a document]({% link _collection/name-of-document.md %}) [Link to a post]({% link _posts/2016-07-26-name-of-post.md %}) {% endraw %} -{% endhighlight %} +``` Support for static files and pages is coming in a later release but is **not** released as of v3.2.1. @@ -512,49 +512,49 @@ Support for static files and pages is coming in a later release but is If you would like to include a link to a post on your site, the `post_url` tag will generate the correct permalink URL for the post you specify. -{% highlight liquid %} +```liquid {% raw %} {% post_url 2010-07-21-name-of-post %} {% endraw %} -{% endhighlight %} +``` If you organize your posts in subdirectories, you need to include subdirectory path to the post: -{% highlight liquid %} +```liquid {% raw %} {% post_url /subdir/2010-07-21-name-of-post %} {% endraw %} -{% endhighlight %} +``` There is no need to include the file extension when using the `post_url` tag. You can also use this tag to create a link to a post in Markdown as follows: -{% highlight liquid %} +```liquid {% raw %} [Name of Link]({% post_url 2010-07-21-name-of-post %}) {% endraw %} -{% endhighlight %} +``` ### Gist Use the `gist` tag to easily embed a GitHub Gist onto your site. This works with public or secret gists: -{% highlight liquid %} +```liquid {% raw %} {% gist parkr/931c1c8d465a04042403 %} {% endraw %} -{% endhighlight %} +``` You may also optionally specify the filename in the gist to display: -{% highlight liquid %} +```liquid {% raw %} {% gist parkr/931c1c8d465a04042403 jekyll-private-gist.markdown %} {% endraw %} -{% endhighlight %} +``` To use the `gist` tag, you'll need to add the [jekyll-gist](https://github.com/jekyll/jekyll-gist) gem to your project. diff --git a/site/_docs/themes.md b/site/_docs/themes.md index 41b3c4db..55e14b4b 100644 --- a/site/_docs/themes.md +++ b/site/_docs/themes.md @@ -38,7 +38,7 @@ Refer to your selected theme's documentation and source repository for more info Jekyll themes are distributed as Ruby gems. Don't worry, Jekyll will help you scaffold a new theme with the `new-theme` command. Just run `jekyll new-theme` with the theme name as an argument: -{% highlight plaintext %} +```sh jekyll new-theme my-awesome-theme create /path/to/my-awesome-theme/_layouts create /path/to/my-awesome-theme/_includes @@ -54,7 +54,7 @@ jekyll new-theme my-awesome-theme create /path/to/my-awesome-theme/.gitignore Your new Jekyll theme, my-awesome-theme, is ready for you in /path/to/my-awesome-theme! For help getting started, read /path/to/my-awesome-theme/README.md. -{% endhighlight %} +``` Add your template files in the corresponding folders, complete the `.gemspec` and the README files according to your needs. diff --git a/site/_docs/troubleshooting.md b/site/_docs/troubleshooting.md index a1299612..c4580f69 100644 --- a/site/_docs/troubleshooting.md +++ b/site/_docs/troubleshooting.md @@ -20,61 +20,61 @@ If you encounter errors during gem installation, you may need to install the header files for compiling extension modules for Ruby 2.0.0. This can be done on Ubuntu or Debian by running: -{% highlight shell %} +```sh sudo apt-get install ruby2.0.0-dev -{% endhighlight %} +``` On Red Hat, CentOS, and Fedora systems you can do this by running: -{% highlight shell %} +```sh sudo yum install ruby-devel -{% endhighlight %} +``` If you installed the above - specifically on Fedora 23 - but the extensions would still not compile, you are probably running a Fedora image that misses the `redhat-rpm-config` package. To solve this, simply run: -{% highlight shell %} +```sh sudo dnf install redhat-rpm-config -{% endhighlight %} +``` On [NearlyFreeSpeech](https://www.nearlyfreespeech.net/) you need to run the following commands before installing Jekyll: -{% highlight shell %} +```sh export GEM_HOME=/home/private/gems export GEM_PATH=/home/private/gems:/usr/local/lib/ruby/gems/1.8/ export PATH=$PATH:/home/private/gems/bin export RB_USER_INSTALL='true' -{% endhighlight %} +``` To install RubyGems on Gentoo: -{% highlight shell %} +```sh sudo emerge -av dev-ruby/rubygems -{% endhighlight %} +``` On Windows, you may need to install [RubyInstaller DevKit](https://wiki.github.com/oneclick/rubyinstaller/development-kit). On Mac OS X, you may need to update RubyGems (using `sudo` only if necessary): -{% highlight shell %} +```sh sudo gem update --system -{% endhighlight %} +``` If you still have issues, you can download and install new Command Line Tools (such as `gcc`) using the command -{% highlight shell %} +```sh xcode-select --install -{% endhighlight %} +``` which may allow you to install native gems using this command (again using `sudo` only if necessary): -{% highlight shell %} +```sh sudo gem install jekyll -{% endhighlight %} +``` Note that upgrading Mac OS X does not automatically upgrade Xcode itself (that can be done separately via the App Store), and having an out-of-date @@ -90,22 +90,22 @@ longer available. Given these changes, there are a couple of simple ways to get up and running. One option is to change the location where the gem will be installed (again using `sudo` only if necessary): -{% highlight shell %} +```sh sudo gem install -n /usr/local/bin jekyll -{% endhighlight %} +``` Alternatively, Homebrew can be installed and used to set up Ruby. This can be done as follows: -{% highlight shell %} +```sh ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)" -{% endhighlight %} +``` Once Homebrew is installed, the second step is easy: -{% highlight shell %} +```sh brew install ruby -{% endhighlight %} +``` Advanced users (with more complex needs) may find it helpful to choose one of a number of Ruby version managers ([RVM][], [rbenv][], [chruby][], [etc][].) in @@ -119,15 +119,15 @@ which to install Jekyll. If you elect to use one of the above methods to install Ruby, it might be necessary to modify your `$PATH` variable using the following command: -{% highlight shell %} +```sh export PATH=/usr/local/bin:$PATH -{% endhighlight %} +``` GUI apps can modify the `$PATH` as follows: -{% highlight shell %} +```sh launchctl setenv PATH "/usr/local/bin:$PATH" -{% endhighlight %} +``` Either of these approaches are useful because `/usr/local` is considered a "safe" location on systems which have SIP enabled, they avoid potential @@ -151,21 +151,21 @@ in order to have the `jekyll` executable be available in your Terminal. If you are using base-url option like: -{% highlight shell %} +```sh jekyll serve --baseurl '/blog' -{% endhighlight %} +``` … then make sure that you access the site at: -{% highlight shell %} +```sh http://localhost:4000/blog/index.html -{% endhighlight %} +``` It won’t work to just access: -{% highlight shell %} +```sh http://localhost:4000/blog -{% endhighlight %} +``` ## Configuration problems @@ -197,9 +197,9 @@ The latest version, version 2.0, seems to break the use of `{{ "{{" }}` in templates. Unlike previous versions, using `{{ "{{" }}` in 2.0 triggers the following error: -{% highlight shell %} +```sh '{{ "{{" }}' was not properly terminated with regexp: /\}\}/ (Liquid::SyntaxError) -{% endhighlight %} +``` ### Excerpts diff --git a/site/_docs/upgrading/0-to-2.md b/site/_docs/upgrading/0-to-2.md index 9d91b019..9de63455 100644 --- a/site/_docs/upgrading/0-to-2.md +++ b/site/_docs/upgrading/0-to-2.md @@ -9,9 +9,9 @@ and 2.0 that you'll want to know about. Before we dive in, go ahead and fetch the latest version of Jekyll: -{% highlight shell %} +```sh $ gem update jekyll -{% endhighlight %} +```
Diving in
diff --git a/site/_docs/upgrading/2-to-3.md b/site/_docs/upgrading/2-to-3.md index 3d15ec55..9e7b0a6e 100644 --- a/site/_docs/upgrading/2-to-3.md +++ b/site/_docs/upgrading/2-to-3.md @@ -9,9 +9,9 @@ that you'll want to know about. Before we dive in, go ahead and fetch the latest version of Jekyll: -{% highlight shell %} +```sh $ gem update jekyll -{% endhighlight %} +``` Please note: Jekyll 3 requires Ruby version >= 2.0.0. @@ -36,11 +36,11 @@ When iterating over `site.collections`, ensure the above conversions are made. For `site.collections.myCollection` in Jekyll 2, you now do: -{% highlight liquid %} +```liquid {% raw %} {% assign myCollection = site.collections | where: "label", "myCollection" | first %} {% endraw %} -{% endhighlight %} +``` This is a bit cumbersome at first, but is easier than a big `for` loop. @@ -97,17 +97,17 @@ In Jekyll 3 and above, relative permalinks have been deprecated. If you created your site using Jekyll 2 and below, you may receive the following error when trying to **serve** or **build**: -{% highlight text %} +```text Since v3.0, permalinks for pages in subfolders must be relative to the site source directory, not the parent directory. Check http://jekyllrb.com/docs/upgrading/ for more info. -{% endhighlight %} +``` This can be fixed by removing the following line from your `_config.yml` file: -{% highlight yaml %} +```yaml relative_permalinks: true -{% endhighlight %} +``` ### Permalinks no longer automatically add a trailing slash @@ -117,19 +117,19 @@ In Jekyll 2, any URL constructed from the `permalink:` field had a trailing slas Try adding `future: true` to your `_config.yml` file. Are they showing up now? If they are, then you were ensnared by an issue with the way Ruby parses times. Each of your posts is being read in a different timezone than you might expect and, when compared to the computer's current time, is "in the future." The fix for this is to add [a timezone offset](https://en.wikipedia.org/wiki/List_of_UTC_time_offsets) to each post (and make sure you remove `future: true` from your `_config.yml` file). If you're writing from California, for example, you would change this: -{% highlight yaml %} +```yaml --- date: 2016-02-06 19:32:10 --- -{% endhighlight %} +``` to this (note the offset): -{% highlight yaml %} +```yaml --- date: 2016-02-06 19:32:10 -0800 --- -{% endhighlight %} +``` ### My categories have stopped working! diff --git a/site/_docs/usage.md b/site/_docs/usage.md index ee02b508..3d2413d4 100644 --- a/site/_docs/usage.md +++ b/site/_docs/usage.md @@ -7,7 +7,7 @@ permalink: /docs/usage/ The Jekyll gem makes a `jekyll` executable available to you in your Terminal window. You can use this command in a number of ways: -{% highlight shell %} +```sh $ jekyll build # => The current folder will be generated into ./_site @@ -20,7 +20,7 @@ $ jekyll build --source --destination $ jekyll build --watch # => The current folder will be generated into ./_site, # watched for changes, and regenerated automatically. -{% endhighlight %} +```
Changes to _config.yml are not included during automatic regeneration.
@@ -52,7 +52,7 @@ $ jekyll build --watch Jekyll also comes with a built-in development server that will allow you to preview what the generated site will look like in your browser locally. -{% highlight shell %} +```sh $ jekyll serve # => A development server will run at http://localhost:4000/ # Auto-regeneration: enabled. Use `--no-watch` to disable. @@ -61,7 +61,7 @@ $ jekyll serve --detach # => Same as `jekyll serve` but will detach from the current terminal. # If you need to kill the server, you can `kill -9 1234` where "1234" is the PID. # If you cannot find the PID, then do, `ps aux | grep jekyll` and kill the instance. [Read more](http://unixhelp.ed.ac.uk/shell/jobz5.html). -{% endhighlight %} +```
Be aware of default behavior
@@ -70,10 +70,10 @@ $ jekyll serve --detach

-{% highlight shell %} +```sh $ jekyll serve --no-watch # => Same as `jekyll serve` but will not watch for changes. -{% endhighlight %} +``` These are just a few of the available [configuration options](../configuration/). Many configuration options can either be specified as flags on the command line, @@ -82,17 +82,17 @@ file at the root of the source directory. Jekyll will automatically use the options from this file when run. For example, if you place the following lines in your `_config.yml` file: -{% highlight yaml %} +```yaml source: _source destination: _deploy -{% endhighlight %} +``` Then the following two commands will be equivalent: -{% highlight shell %} +```sh $ jekyll build $ jekyll build --source _source --destination _deploy -{% endhighlight %} +``` For more about the possible configuration options, see the [configuration](../configuration/) page. diff --git a/site/_docs/windows.md b/site/_docs/windows.md index 3a8dddc6..f64ac6d4 100644 --- a/site/_docs/windows.md +++ b/site/_docs/windows.md @@ -29,9 +29,9 @@ Additionally, you might need to change the code page of the console window to UT in case you get a "Liquid Exception: Incompatible character encoding" error during the site generation process. It can be done with the following command: -{% highlight shell %} +```sh $ chcp 65001 -{% endhighlight %} +``` [windows-installation]: http://jekyll-windows.juthilo.com/ [hitimes-issue]: https://github.com/copiousfreetime/hitimes/issues/40 @@ -43,9 +43,9 @@ As of v1.3.0, Jekyll uses the `listen` gem to watch for changes when the built-in support for UNIX systems, it requires an extra gem for compatibility with Windows. Add the following to the Gemfile for your site: -{% highlight ruby %} +```ruby gem 'wdm', '~> 0.1.0' if Gem.win_platform? -{% endhighlight %} +``` ### How to install github-pages @@ -81,7 +81,7 @@ This gem is also needed in the github-pages and to get it running on Windows x64 `choco install libiconv -Source "https://www.nuget.org/api/v2/"`{:.language-ruby} -{% highlight ruby %} +```ruby gem install nokogiri --^ --with-xml2-include=C:\Chocolatey\lib\libxml2.2.7.8.7\build\native\include^ --with-xml2-lib=C:\Chocolatey\lib\libxml2.redist.2.7.8.7\build\native\bin\v110\x64\Release\dynamic\cdecl^ @@ -89,7 +89,7 @@ This gem is also needed in the github-pages and to get it running on Windows x64 --with-iconv-lib=C:\Chocolatey\lib\libiconv.redist.1.14.0.11\build\native\bin\v110\x64\Release\dynamic\cdecl^ --with-xslt-include=C:\Chocolatey\lib\libxslt.1.1.28.0\build\native\include^ --with-xslt-lib=C:\Chocolatey\lib\libxslt.redist.1.1.28.0\build\native\bin\v110\x64\Release\dynamic -{% endhighlight %} +``` #### Install github-pages @@ -98,10 +98,10 @@ This gem is also needed in the github-pages and to get it running on Windows x64 * Copy & paste the two lines into the file: -{% highlight ruby %} +```ruby source 'http://rubygems.org' gem 'github-pages' -{% endhighlight %} +``` * **Note:** We use an unsecure connection because SSL throws exceptions in the version of Ruby * Open a command prompt, target your local blog repository root, and install github-pages: `bundle install`