Article Series

Jekyll in General

Jekyll Plain

Where to Discuss?

Local Group


Goal: Common use of markdown in Jekyll content.

Source Code

This article use tutor-04 theme. We will create it step by step.

Layout Preview for Tutor 04

Liquid: Layout Preview for Tutor 04

0: Markdown Content

Focus on document structure

Illustration: Markdown Content

1: Separate of Concern

There is not much to say about markdown. Markdown is easy, however there might be a tricky issue.

Why Markdown?

More on Writing Content

While markup focus on document formatting, markdown focus on document structure.


Common Structure

The common structure for content in Jekyll are:

  1. Frontmatter: YAML only.

  2. Content: Markdown or HTML

Real Life Structure

I think that, it is easier just to live with this structure, split the content, and the resource (link and image).

  1. Frontmatter: YAML

  2. Content: Markdown

  3. Resource: Markdown

layout : page

# Header 1

My content

[My Link][my-image]

-- -- --

## Header 1.1

My sub content

![My Image][mylink]

-- -- --

## Header 1.2

My other sub content

[//]: <> ( -- -- -- links below -- -- -- )


Split Resource

Notice, that the markdown divided into two part by using.

[//]: <> ()

It is a good practice to split resource and content. But do not take that to far. Simple things do not need to be separated.

2: Line Break

Jekyll markdown require double space to make a new line break. So you do not need to worry about different markdown standard.

Page Content: Post

As usual, we require example content.

# Heading 1

You swallow me whole without even thinking now  
Your hands are as cold as whatever you're drinking down

## Heading 2

> Been trying to fill all the holes you've been digging for yourself  
  But I can't replace everything that's gone missing from your shell

### Example Content

* Do you think I'll make you feel better?  
* Do you think I'll make you feel better?

Markdown is simply text format.

Jekyll Markdown: Simple Text in ViM

Consider have a look at the whitespace in Vim.

Jekyll Markdown: Newline in ViM

And notice the double space at the end of the sentence.

Render: With Issue

This will result as:

Jekyll Markdown: Newline in Browser

We can utilize pure markdown to provide link, or to provide image in jekyll.

Page Content: Resources in Markdown

Again, content for example purpose:

[Terminal Dofiles][one-link].

There's no crying in baseball.  
Try to understand.

![Business Card][one-image]

-- -- --

### Example Dotfiles

ViM RC: [bandithijo][link-dotfiles]

-- -- --

### What's next ?

Our next song would be [Company of Thieves - Oscar Wilde][local-whats-next]

And the resource defined below, the above code, in the same document.

[//]: <> ( -- -- -- links below -- -- -- )

{% assign asset_path = '/assets/images' %}
{% assign dotfiles = '' %}

[local-whats-next]: /lyric/2020/03/15/company-of-thieves-oscar-wilde.html
[link-dotfiles]:    {{ dotfiles }}/terminal/vimrc/vimrc.bandithijo

[one-image]:    {{ asset_path }}/logo-gear.png
[one-link]:     {{ dotfiles }}/terminal/

Jekyll Markdown: Image and Link Resources in Markdown

Prepare Image Directory

It is, a good practice to have a good structured directory. Just put all your resources in assets directory. And how you structure you image, javascript, vector and such, is actually up to you.

$ tree assets/images/
├── adverts
│   └── oto-spies-01.png
└── logo-gear.png

1 directory, 2 files

4: Shortcode

Just include statement.

We can also utilize shortcode liek code in Jekyll, that can be equipped with parameter argument, to provide raw HTML in the middle of content.


We need to add a shortcode in _layout:

<img alt="advertisement" 
     src="{{ "/assets/images/adverts/"
             | append: include.img
             | prepend: site.baseurl }}">

We can use this advert shortcode later, in markdown as liquid code as shown below:

{% include shortcodes/advert.html img="oto-spies-01.png" %}

This shortcode is just an include statement.

Page Content: Markdown with Shortcut

Again, content for example purpose

layout      : post
title       : Emma Ruth Rundle - Shadows of My Name
date        : 2018-02-15 07:35:05 +0700

I lay back in salt  
Please forgive my name  

{% include shortcodes/advert.html img="oto-spies-01.png" %}

I won’t speak at all  
Just to sing again  

Jekyll Content: Shortcode in ViM

With result as below:

Jekyll Content: Advertisement in Markdown using Shortcode

You can use markdown directly to show images, or in special case you might consider shortcode. Now it is your choice, which one is easier for you.

What’s Next?

Consider continue reading [ Jekyll - Plain - Managing Code - Part One ].

Thank you for reading.