IAMOR!!!!!

First step: lovely tutorial!

_config.yml

Stores configuration data. Many of these options can be specified from the command line executable but it's easier to specify them here so you don't have to remember them.

configuration

Jekyll allows you to concoct your sites in any way you can dream up, and it's thanks to the powerful and flexible configuration options that this is possible. These options can either be specified in a _config.yml file placed in your site's root directory, or can be specified as flags for the jekyll executable in the terminal.

settings

global configuration

The table below lists the available setting for Jekyll, and the various options (specified in the configuration file) and flags (specified on the command-line) that control them.

seting | options, flags

• | - Site Source Change the directory where Jekyll will read files | source: DIR, -s, --source DIR Site Distination Change the directory where Jekyll will write files | destination: DIR, -d, --destination DIR Safe Disable custom plugins, and ignore symbolic links. | safe: BOOL, --safe Exclude Exclude derectories and/or files from the conversion. These exclusions are relative to the site's source directory and cannot be outside the source directory. | exclude: [DIR, FILE, ...] Include Force inclusion of directories and/or files in the conversion. .htaccess is a good example since dotfiles are excluded by default | include: [DIR, FILE, ...] Keep files When clobbering the site destination, keep the selected files. Useful for files that are not generated by jekyll; e.g. files or assets that are generated by your build tool. The paths are relative to the destination | keep_files: [DIR, FILE, ...] Time Zone Set the time zone for site generation | timezone: TIMEZONE Encoding Set the encoding of files by name. | encoding: ENCODING Defaults Set defaults for YAML Front Matter variables | see below

build command options

specifying a Jekyll environment at build time

In the build (or serve) arguments, you can specify a Jekyll environment and value. The build will then apply this value in any conditional statements in your content. For example, suppose you set this conditional statement in your code:

{% if jekyll.environment == "production" %}
  {% include disqus.html %}
{% endif %}

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:

JEKYLL_ENV=production jekyll build

Specifying an environment value allow you to make certain content available only with specific environments.

The default value for JEKYLL_ENV is development. Therefore if you omit JEKYLL_ENV from the build arguments, the default value will be JEKYLL_ENV=development. Any content inside {% if jekyll.environment == "development" %} tags will automatically appear in the build.

Your environment values can be anything you want (not just development or production). Some elements you might want to hide in development environments include Disqus comment forms or Google Analytics. Conversely, you might want to expose an “Edit me in GitHub” button in a development environment but not include it in production environments.

By specifying the option in the build command, you avoid having to change values in your configuration files when moving from one environment to another.

Front Matter defaults

Using YAML Front Matter is one way that you can specify configuration in the pages and posts for your site. Setting things like a default layout, or customizing the title, or specifying a more precise date/time for the post can all be added to your page or post front matter.

Often times, you will find that you are repeating a lot of configuration options. Setting the same layout in each file, adding the same category - or categories - to a post, etc. You can even add custom variable like author names, which might be the same for the majority of posts on your blog.

Instead of repeating this configuration each time you create a new post or page, Jekyll provides a way to set these defaults in the site configuration. To do this, you can specify site-wide defaults using the defaults key in the _config.yml file in your projects root directory.

The defaults key holds an array of scope/values pairs that define what defaults SHOULD be set for particular file path, and optionally, a file type in that path.

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:

defaults:
  -
    scope:
      path: "" #an empty string here means all files in the projects
    values:
      layout: "default"

Here, we are scoping the values to any file that exists in the scopes path. Since the path is set as an empty string, it will apply to all files in your project. You probably do NOT 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.

defaults:
  -
    scope:
      path: ""
      typeL "posts" # previously `post` in Jekyll 2.2.
    values:
      layout: "default"

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.

defaults:
  -
    scope:
      path: ""
      type: "posts"
    values:
      layout: "my-site"
  -
    scope:
      path: "projects"
      type: "pages"
    values:
      layout: "project"
      author: "Mr. Hyde"

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 set to Mr. Hyde as well as have the category for the page set to project.

collection:
  - my_collection:
    output: true
defaults:
  -
    scope:
      path: ""
      type: "my_collection"
    values:
      layout: "default"

In this example the layout is set to default inside the collection with the name my_collection

precedence

Jekyll will apply all of the configuration settings you specify in the defaults section of your _config.yml file. However, you can choose to override settings from other scope/values pair by specifying a more specific path for the scope.

You can see that in the last example above. First, we set the default layout to my-site. Then, using a more specific path, we set the default layout for files in the projects/ path to project. This can be done with any value that you would set in the page or post front matter.

Finally, if you set defaults in the site configuration by adding a defaults section to your _config.xml 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:

# In _config.yml
...
defaults:
  -
    scope:
      path: "projects"
      type: "pages"
    values:
      layout: "project"
      author: "Mr. Hyde"
      category: "project"
...

# In projects/foo_project.md
---
author: "John Smith"
layout: "foobar"
---
The post text goes here...

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.