I've deployed my Jekyll blog on a VPS. I would now like to add Github-flavored Markdown to it, using Pygments highlighting, but I don't know which files do I have to edit and how.
So far, the only file I've configured is _config.yml
which looks like this:
1 safe: false
2 auto: false
3 server: false
4 server_port: 4000
5 baseurl: /
6 url: http://localhost:4000
7
8 source: .
9 destination: ./_site
10 plugins: ./_plugins
11
12 future: true
13 lsi: false
14 pygments: false
15 markdown: maruku
16 permalink: date
17
18 maruku:
19 use_tex: false
20 use_divs: false
21 png_engine: blahtex
22 png_dir: images/latex
23 png_url: /images/latex
24
25 rdiscount:
26 extensions: []
27
28 kramdown:
29 auto_ids: true,
30 footnote_nr: 1
31 entity_output: as_char
32 toc_levels: 1..6
33 use_coderay: false
34
35 coderay:
36 coderay_wrap: div
37 coderay_line_numbers: inline
38 coderay_line_numbers_start: 1
39 coderay_tab_width: 4
40 coderay_bold_every: 10
41 coderay_css: style
How do I properly configure Jekyll to use Github flavored Markdown and Pygments highlighting?
as of Jekyll >= 0.12.1 redcarpet2 is natively supported by Jekyll, so you can simply set your config to markdown: redcarpet
and you are good to go with GFM / fenced code blocks without the rest of this mumbojumbo...
You explicitly ask for Github-flavored markdown, so I presume you aren't looking for answers that create code blocks with the non-markdown liquid format:
{% highlight python %}
def yourfunction():
print "Hello World!"
{% endhighlight %}
but would rather be able to write something with fenced code blocks:
```python
def yourfunction():
print "Hello World!"
```
etc. For this, you will want to use the redcarpet markdown parser.
Github-flavored markdown uses a markdown parser called "Redcarpet" 1. Ironically, though Github flavored markdown uses redcarpet2, this markdown parser is not supported by Jekyll by default. Instead, you can add this as a plugin by installing that ruby gem
gem install redcarpet
and then adding the redcarpet2 Jekyll plugin. (Installing a plugin in Jekyll amounts to placing the .rb
ruby script given in that repository into your _plugins
directory. Can be in a subdirectory of _plugins
too).
Then, as explained on the documentation there, edit your _config.yml
to use redcarpet2:
markdown: redcarpet2
redcarpet:
extensions: ["no_intra_emphasis", "fenced_code_blocks", "autolink", "strikethrough", "superscript"]
which adds the common extensions provided by github-flavored-markdown aka redcarpet2 (Well, almost. This won't do github specific markdown things like identify issues by number, or commits by hash, so they aren't technically the same).
Having the plugin means, for the moment, you will have to build your site locally and copy the _site
to github if you are hosting your site there, as redcarpet2 isn't available on the Github version of the jekyll engine (see this open issue on Jekyll)
Note: You don't need all the markdown editors you've specified in your _config.yml
by the way. For a basic example using redcarpet2, you might want to see this config and the associated jekyll directory that goes with it.