Preface
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
0: Markdown Content
Focus on document structure
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.
Reading
Common Structure
The common structure for content in Jekyll are:
-
Frontmatter: YAML only.
-
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).
-
Frontmatter: YAML
-
Content: Markdown
-
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 -- -- -- )
[my-image]: http://some.site/an-image.jpg
[my-link]: http://some.site/an-article.html
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.
Consider have a look at the whitespace in Vim.
And notice the double space at the end of the sentence.
Render: With Issue
This will result as:
3: Resources: Link and Image
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 = 'https://gitlab.com/epsi-rns/dotfiles/tree/master' %}
[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/
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/
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.
Shortcode
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
With result as below:
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.