This post summarize some basic stuff for using Jekyll.
Kramdown Quick Reference
Things as a refresher, from this official page. Note that I simplified some of them because I don’t necessarily need all alternatives.
I also have a kind of feeling that I should refrain from using the advanced features that kramdown provides, and stick only to the basics.
- Paragraphs with empty lines.
- Two spaces or two backslashes for manual line break.
- Headers using
#(for my blog, starting with
- Blockquotes by prefixing each line with a
>, or prefixing only the first line with
>with an empty line as a terminator.
- Code block: prefxing each line with 4 spaces, or using tildes (optionally followed by the language tag).
- Horizontal rule: 3 or more
- List with
3., or with
- Some less used features: Definition Lists, Tables, HTML Tags, Block Attributes and Extensions.
- Text modifiers:
[linked text](url "title text")
[linked text][ref name], and define
ref nameelsewhere on the page, as
[ref name]: url
[linked text]and just use
linked textis then the same as the
![alt text](relative path): no need to quote the path or the text
- Inline code: use
`to wrap around the code; if
`itself is needed, then use two
`to wrap the code.
- Footnote, Abbrevations, HTML Elements, and Inline HTML Attributes.
- When including an image, use
site.urlenclosed by two curly braces to obtain the actual absolute path of your site (obtained from
_config.yml) instead of using relative path.
- Links to files other than images are similar to hyperlinks.
- Jekyll built-in support for code highlighting seems simpler. See this example.
Pages are simply other markdown files not in
_post folder or
_drafts folders. There are two conventions to organize them.
What’s important is that, for pages to be regarded as pages by Jekyll (thus available from the
site.pages variable), the page should at least have to have the
title: field in its front matter. Otherwise, Jekyll will process the page still, but does not regard it as a page.
To make things better, specify the
layout: and other front matter field as well.