A brief overview of how to get things started quickly and some not so obvious Jekyll and Markdown features.

Table of Contents

Getting Started

The best is to start with a working template, for example, the same that was used for this project, template. This template also includes a very nice tutorial, setup.

However a few side notes; You maybe need to export the path to your ruby installation (GNU+Linux)

export PATH=/home/<USERDIR>/.local/share/gem/ruby/<ruby version, eg: 3.0.0>/bin:$PATH
export GEM_HOME=$(ls -t -U | ruby -e 'puts Gem.user_dir')

It might be that the live preview has a missing json dependency. In that cas just add it to the Gemfile.

gem "json", "~> 2.7"

If you intend to do something with tags, keep the following in mind

  • GitHub Pages comes with fixed plugins if you want Github to take care of building
  • Tag overview pages cant be created programmatically without a plugin

Not so obvious Markdown and Jekyll features

For a complete list of all github flavoured markdown features head to the official 1

Github Pages can be configured among other tools to use kramdown as converter. The docs for this can be found here 2.

Footnotes

You can use footnotes in conjunction with the markdown parser kramdown. Kramdown is one of default github markdown parsers for gh-pages.

The announcement was in 20213 <== footnote example. Some additional resources:

Table of Contents

To create a toc 2 steps are necessary. First use kramdown as markdown converter, for this add ‘markdown: kramdown’ to your _config.yml file.

Secondly, use something like the following snippet to your posts kramdown: html#toc:

### Table of Contents
{:.no_toc}
* A markdown unordered list which will be replaced with the ToC, excluding the "Contents header" from above
{:toc}

See this Jeyll discussion

Or copy paste this example:

[link text](the link){:target="_blank"}

Github flavoured Markdown

Alerts

Alert Commands listed in the docs4 dont work with jekyll. So the following snippet from the docs will not create the nice warning box :cry:.

[!NOTE]
Useful information that users should know, even when skimming content.

To use something similar you have to use some include magic. The basic idea that is used goes something like this: Create a include statement in your markdown file.

<div markdown="span" style="border-width:0.25em; border-style:solid; border-color:#cbda07; padding: 1em; margin-bottom: 1em;"><b>Warning:</b> :warning: Useful information that users should know, even when skimming content. :warning:</div>

In your ‘_includes’ directory create a file named the same, in this case ‘warning.html’. In this file add something along the lines of:

<div markdown="span" style="border-width:0.25em; border-style:solid; border-color:#cbda07; padding: 1em; margin-bottom: 1em;"><b>Warning:</b> :warning:  :warning:</div>

The :warning: statement is the jemoji yntax for :warning:.

Resulting in this:

Warning: :warning: Useful information that users should know, even when skimming content. :warning:

References

  1. https://docs.github.com/en/enterprise-cloud@latest/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax ↩

  2. https://kramdown.gettalong.org/converter/html.html ↩

  3. https://github.blog/changelog/2021-09-30-footnotes-now-supported-in-markdown-fields/ ↩

  4. https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax#alerts ↩