This post summarize some basic stuff for using Jekyll.

Jekyll Logo

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 start 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 1., 2., 3., or with - , * , + .
  • Some less used features: Definition Lists, Tables, HTML Tags, Block Attributes and Extensions.
  • Text modifiers:
    • Emphasis: *text* or _text_
    • Strong: **text** or __text__
    • Links
      1. [linked text](url)
      2. [linked text](url "title text")
      3. [linked text][ref name], and define ref name elsewhere on the page, as [ref name]: url
      4. omit [linked text] and just use [ref name]: linked text is then the same as the ref name
    • Images: ![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.

Jekyll Notes

Markups Specifics

  • When including an image, use site.url enclosed 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

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.