This post is a technical cheatsheet for syntactical constructs used to create pretty posts, specifically in the Jekyll/Github Pages environment. Much of the content here is taken directly from the Jekyll docs about writing docs, but I wanted to create a cheatsheet briefly summarizing what I think is the most helpful content.
I found a generic markdown cheatsheet here but some things mentioned there don’t appear to work in this specific environment. Another Jekyll-specific cheatsheet can be found here but it’s not super comprehensive– thus the need for this post here. Yet another link here proved itself very helpful in the creation of this cheatsheet, too. Wordpress official quick reference has good info too. I’ll be adding to it continuously over the next few days (probably weeks) as I learn more and more about what’s possible and as I test my markdown, so if it seems a little small or improperly formatted, you know why.
Formatting text
To create headers, use pounds symbols/hashtags.
One pound
# One pound
Question: Why does one pound result in smaller text than two?
Two pounds
## Two pounds
Three pounds
### Three pounds
Four pounds
#### Four pounds
Five pounds
##### Five pounds
Six pounds
###### Six pounds
Italics: italic text here
_italic text here_
or
*italic text here*
Bold/Emphasis: bold text here
__bold text here__
or
**bold text here**
Combine the two: B/I text here
**B/I text _here_**
Lists
* Bullet 1
* Bullet 2
* Bullet 2a
* Bullet 2b
* Bullet 3
Renders as:
- Bullet 1
- Bullet 2
- Bullet 2.1
- Bullet 2.1.1
- Bullet 2.1
- Bullet 3
1. item 1
2. item 2
1. Item 2a
3. item 3
Renders as:
- item 1
- item 2
- item 2a
- item 3
Sadly, it seems that markdown doesn’t support numbered sublists (such as 1, 2, 2.1, 2.2, 3, etc).
Tables
Credit to the real MVP Adam-P for this sweet table example:
| Tables | Are | Cool |
| ------------- |:-------------:| -----:|
| col 3 is | right-aligned | $1600 |
| col 2 is | centered | $12 |
| zebra stripes | are neat | $1 |
Renders as:
| Tables | Are | Cool |
|---|---|---|
| col 3 is | right-aligned | $1600 |
| col 2 is | centered | $12 |
| zebra stripes | are neat | $1 |
Markdown Comments
To make a single line markdown comment:
[/]: comment here
Note that you may need to add some blank lines above or below to get the comment to register as a comment. Also, I don’t know why but things like [asdf/]: comment text here register properly as comments too.
To make a multiline markdown comment, HTML comment tags seem to work:
<!---
line 1 here
line 2 here
...
line X here
-->
Inserting code snippets
Jekyll makes use of something called Liquid to do templates. It looks like there’s about a million and ten things you can do with this and they’re all nicely organized on Jekyll’s Liquid docs, so check that out there. If it ends up being super complex, I will write up another post explaining the basics of templating for noobs like myself.
1
2
3
4
5
def print_hi(name)
puts "Hi, #{name}"
end
print_hi('Tom')
#=> prints 'Hi, Tom' to STDOUT.
created with:
{% highlight ruby linenos %}
def print_hi(name)
puts "Hi, #{name}"
end
print_hi('Tom')
#=> prints 'Hi, Tom' to STDOUT.
{% endhighlight %}
Posting raw/verbatim code blocks
This one took me a while to figure out. Encapsulate your stuff as follows but remove the spaces on the closing tag, and replace the double-triple-double backticks with just triple backticks (tricking the parser is hard and I’m not good at it yet).
`` ``` ``
{% raw %}
put your raw
code stuff here
{ % endraw % }
`` ``` ``
Inserting links
These require two lines of stuff:
1
2
3
4
5
yadda yadda [link text][link tag] blahblah
//OR
yadda yadda [link text](http://yourlinkhere.com/GettingGood) blahblah
// at bottom of doc, place this as is:
[link tag]: http://yourlinkhere.com/GettingGood
Inserting pictures
Inserting pictures from a link
Inserting local pictures
Inserting local pictures can be done by identifying the path to the picture (treating the root part of the repo as the ‘root’ directory). The picture below is called ‘zz.jpeg’ and is in the ‘assets/images/posts’ directory.
Check out the Jekyll docs for more info on how to get the most out of Jekyll. File all bugs/feature requests at Jekyll’s GitHub repo. If you have questions, you can ask them on Jekyll Talk.
