You can control many things about each post with a few entries in its front matter. The entries provide layout controls and the ability to combine many posts in a series with BACK and NEXT buttons.

If you use the ruby compose.rb command to initiate your post, many of these front matter entries are provided for you. This part of the guide explains all of the entries available in this theme.

Required

categories

If it’s a post, the categories array is required with at least the first element set to the permalink name of its parent page (so that breadcrumbs work).

categories: topics ...

The two top-level categories with provided index pages are topics and works.

If you want BACK and NEXT navigation within a subcategory:

• Create a first post for the sub-category, but with a permalink. The category list can be space-delimited on one line or in a bulleted list. Note that the category names must exactly match the permalink.

  categories: topics my-great-vacation
  permalink: /topics/my-great-vacation/
  

• The site permalink would be: /topics/my-great-vacation/index.html

• If your subcategory contains spaces, specify categories as an array

  categories:
    - topics
    - my great vacation
  permalink: /topics/my great vacation/
  

• For subsequent topics in the sub-category, add the sub-category and no permalink:

  categories: topics my-great-vacation
  

• That results in: /topics/my-great-vacation/topic-title.html

• Topics in the sub-category are sorted by date and time. Therefore, if they all fall on the same day, specify the date in the post with a timestamp by which to sort.

  date: 3009-09-22 00:00:03
  

excerpt

You’ll probably wanna provide an excerpt in front-matter, because relying on Jekyll to get the excerpt from the body has too many caveats. The excerpt is truncated as necessary in references, so it can be as long as you want, but because it’s also displayed in all caps right under the topic title, you’ll definitely want to preview how it looks.

excerpt: yada yada

permalink

If it’s the first page of a sub-category, use a permalink for the categories. It becomes the index that a breadcrumb link would pop up to, ie: /topics/new-category/index.html. Also see categories.

permalink: /topics/new-category/

title

Title for <title/> and article <h1/>. For this and all other fields, refer to Yaml restrictions on when you need to quote the value.

title: My interesting topic

Presentation options

author

If you want the article to be attributed to an author, specify a name that corresponds to a key in the _data\authors.yml file.

author: key_name

background-image

If you want a larger title block with a background image, specify it here. If it’s in the /images/ folder, specify just the name; otherwise specify the folder relative to your jekyll root, starting with /. If it’s a remote image, begin the name with //. Use a high resolution image, if possible, for when viewed full screen. Once displayed, you’ll wanna slowly resize your browser or use its developer tools to see how the image responds for all @media breakpoints and crop it as necessary.

background-image: imagefile.png

icon

For the featured articles on the main page, if you want an icon other than the heart icon, specify the font-awesome icon identifier (just the text after fa-). See the font-awesome icons topic for a list of available icons.

icon: industry

image

For pages to be listed on the front landing page, you can provide an image to be used in the listing. If you do not provide an image, the banner image will be used instead.

image: imagefile.png

layout

For both posts and pages, there’s no need to specify the layout. Specifying the layout is optional because defaults are set in the _config.yml file to set the layout based on the folder it’s in (_posts or _pages). The layout is useful for pages outside of these folders, however.

layout: {page|post}

options

The options allow you to customize the page somewhat.

options:
  - minihead      # as minimal a title as possible, and no date printed
  - fullwidth     # leaving only a tiny margin on all media sizes
  - nocomment     # disable disqus comments for this post
  - nomenu        # for pages, don't add to the menu
  - nolanding     # for pages and featured posts, don't add to the landing page

Ordering and site map options

changefreq

The default change frequency for all pages in the site map is monthly. Depending on how often you think you’ll edit a page, you can set the page change frequency. Here’s a good guide on when to use the available values.

changefreq: weekly

key

All files in the _pages folder are displayed in the nav menu unless you set the nomenu option. Use key to specify the order you want the pages listed in the nav menu. Values are sorted in ascending order.

key: 2

lastmod, date

If you want the site map lastmod setting to be updated, you can set one or both of these to your new modified date as YYYY-MM-DD HH:MM:SS +/-TTTT (lastmod has priority). If you use date, the date shown on the page is also modified, overriding the date in the filename. The timestamp is assumed to be UTC unless you specify the time zone offset afterward.

lastmod: 2016-03-13 23:11:00
date: 2016-01-01 00:00:00 -0800

priority

Use priority to specify two things:

• the grouping in the works index
• the site map priority

priority: 0.8

In the works index, the works are grouped by priority, listed by descending priority and by descending date within each priority.

Because the value is used to set the site map priority, it must be set to a value between 0 and 1.0. I’ve personally chosen three groups of works, with priorities 0.7, 0.6, and 0.5. None as high as featured posts, but then, I’m not looking for a job right now. ;-)

Default priorities in the sitemap.xml file:

• 1.0 - Landing page
• 0.9 - Featured posts
• 0.7 - Other posts
• 0.5 - Pages

sitemap_exclude

Set to yes if you want to exclude a page from the sitemap.

sitemap_exclude: yes

tags

For topics posts, the only tag that has an effect right now is featured, which adds it to the top of the /topics/ page. The eight most recent featured posts are also added to the main landing page.

tags: featured

For works posts, the tags become a listing of skills demonstrated. For example:

tags:
  - Jekyll
  - Sass/SCSS
  - Ruby

You can add the featured tag to a work if you want it to appear on the main landing page. The featured tag is excluded from the list of skills on the page and works index. However, its page priority overrides the standard priority of featured posts in the site map.

CSS and Script support

includes

If your page needs to include stylesheets or scripts, provide ‘em as either local or remote URLs. Prefix remote urls with //, not http. Stylesheets are included in the header and scripts at the bottom before the body closes.

style-includes:
  - /local/path/to/stylesheet.css
  - //remote.com/url/to/stylesheet.css

script-includes:
  - /local/path/to/script.js
  - //remote.com/url/to/script.js

style, script

These are useful when you want to embed styles and scripts outside of the {{ content }} area. Use the Yaml | indented block to ensure line breaks are preserved. The styles are included in the header below stylesheet includes; scripts are included at the bottom below script includes.

style: |
  /* some css block here */
  .some-class {
    somestyle: definition;
  }

script: |
  // some script block here...
  $(document).ready(function(){
    ...
  });