Static site generator written in Ruby. Having a table of contents (TOC) makes an article more readable. Our goal is to automatically generate TOC out of the headings in an article, for a site based on Jekyll and hosted on GitHub Pages.

The various Markdown renderers supported by Jekyll sometimes have extra optionsavailable.

• During my migration to Jekyll I’ve found that the markdown parser, Maruku, doesn’t compile the current Codepen embed code.
• I’ve been using Jekyll as my static blog generator for a few years now but noticed a minor annoyance a few days ago; whenever I use footnotes1, the return arrow (↩︎) is converted into an emoji (↩️.
• Octopress is a wonderful blogging framework for hackers, but it does not supportmath typesetting by default. What hacker doesn’t use Latex math?

Kramdown

Kramdown is the default Markdown renderer for Jekyll. Below is a list of thecurrently supported options:

• auto_id_prefix - Prefix used for automatically generated header IDs
• auto_id_stripping - Strip all formatting from header text for automatic ID generation
• auto_ids - Use automatic header ID generation
• coderay_bold_every - Defines how often a line number should be made bold
• coderay_css - Defines how the highlighted code gets styled
• coderay_default_lang - Sets the default language for highlighting code blocks
• coderay_line_number_start - The start value for the line numbers
• coderay_line_numbers - Defines how and if line numbers should be shown
• coderay_tab_width - The tab width used in highlighted code
• coderay_wrap - Defines how the highlighted code should be wrapped
• enable_coderay - Use coderay for syntax highlighting
• entity_output - Defines how entities are output
• footnote_backlink - Defines the text that should be used for the footnote backlinks
• footnote_backlink_inline - Specifies whether the footnote backlink should always be inline
• footnote_nr - The number of the first footnote
• gfm_quirks - Enables a set of GFM specific quirks
• hard_wrap - Interprets line breaks literally
• header_offset - Sets the output offset for headers
• html_to_native - Convert HTML elements to native elements
• line_width - Defines the line width to be used when outputting a document
• link_defs - Pre-defines link definitions
• math_engine - Set the math engine
• math_engine_opts - Set the math engine options
• parse_block_html - Process kramdown syntax in block HTML tags
• parse_span_html - Process kramdown syntax in span HTML tags
• smart_quotes - Defines the HTML entity names or code points for smart quote output
• syntax_highlighter - Set the syntax highlighter
• syntax_highlighter_opts - Set the syntax highlighter options
• toc_levels - Defines the levels that are used for the table of contents
• transliterated_header_ids - Transliterate the header text before generating the ID
• typographic_symbols - Defines a mapping from typographical symbol to output characters

Example Usage

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.

For more details about these options have a look at the Kramdown configuration documentation.

CommonMark

CommonMark is a rationalized version of Markdown syntax, implemented in C and thus faster than default Kramdown implemented in Ruby. It slightly differs from original Markdown and does not support all the syntax elements implemented in Kramdown, like Block Inline Attribute Lists.

It comes in two flavors: basic CommonMark with jekyll-commonmark plugin and GitHub Flavored Markdown supported by GitHub Pages.

Custom Markdown Processors

If you’re interested in creating a custom markdown processor, you’re in luck! Create a new class in the Jekyll::Converters::Markdown namespace:

Once you’ve created your class and have it properly set up either as a pluginin the _plugins folder or as a gem, specify it in your _config.yml:

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

Configuration Settings

Global Configuration

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

Destination folders are cleaned on site builds

The contents of <destination> are automatically cleaned, by default, when the site is built. Files or folders that are not created by your site will be removed. Some files could be retained by specifying them within the <keep_files> configuration directive.

Do not use an important location for <destination>; instead, use it as a staging area and copy files from there to your web server.

Build Command Options

Serve Command Options

In addition to the options below, the serve sub-command can accept any of the optionsfor the build sub-command, which are then applied to the site build which occurs rightbefore your site is served.

Do not use tabs in configuration files

This will either lead to parsing errors, or Jekyll will revert to the default settings. Use spaces instead.

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 variables 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 a 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:

Jekyll Kramdown-parser-gfm

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

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.

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

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.

Jekyll Kramdown-parser-gfm

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

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

Jekyll runs with the following configuration options by default. Alternativesettings for these options can be explicitly specified in the configurationfile 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.

Markdown Options

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.

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.

Note that you can also specify a language for highlighting after the first delimiter:

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

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

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

For example, in your _config.yml:

Jekyll Kramdown Coderay

Custom Markdown Processors

If you’re interested in creating a custom markdown processor, you’re in luck! Create a new class in the Jekyll::Converters::Markdown namespace:

Jekyll Kramdown Restaurant

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: