You can configure most Jekyll settings by editing your _config.yml file.

Note: For more information on configuring your site with Jekyll, see the official Jekyll configuration documentation.

For more information about default and optional Jekyll plugins, see "Configuring Jekyll Plugins."

Defaults you can change

The following defaults are set by GitHub, which you are free to override in your _config.yml file:

 github: [metadata]
 encoding: UTF-8
   input: GFM
   hard_wrap: false
 future: true
 jailed: false
 theme: jekyll-theme-primer
 gfm_quirks: paragraph_end

Configuration settings you cannot change

GitHub Pages & Jekyll override the following settings in your _config.yml file, which you cannot change:

 lsi: false
 safe: true
 source: [your repo's top level directory]
 incremental: false
 highlighter: rouge
   noscript: false
   math_engine: mathjax
   syntax_highlighter: rouge


  • For the content of the repository metadata object, see repository metadata on GitHub Pages.
  • Keep in mind that if you change the source setting, your pages may not build correctly. GitHub Pages only considers source files in the top-level directory of a repository.

Front matter is required

Jekyll requires that Markdown files have front matter defined at the top of every file. Front matter is just a set of metadata, delineated by three dashes:

title: This is my title
layout: post

Here is my page.

If you like, you can choose to omit front matter from your file, but you'll still need to make the triple-dashes:


Here is my page.

If your file is within the _posts directory, you can omit the dashes entirely.

For more information on configuring the front matter, see the official Jekyll front matter documentation.

Further reading