Github flavored Markdown and pygments highlighting

问题:

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 wich 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?

回答1:

Edit: Easier now

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...

Original answer

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.

回答2:

The best parts of Jekyll are, as said here,

...It takes a template directory (representing the raw form of a website), runs it through Textile or Markdown and Liquid converters, and spits out a complete, static website...

That means, you get Markdown and pygments highlighting by default.

You can discard or use the default _config.yaml for this setup. With your existing config, you might want to set pygments to true: pygments: true.

Here's what you do for

• Markdown: just name your file as *.markdown, for example 2012-12-01-my-post.markdown and place it anywhere inside the root directory. Normally, you would place it in _posts.

  When jekyll parses this file, it'll pass it through markdown filter. As an added bonus, you get to save as *.textile and it parses using textile. And, ofcourse, you can keep it .html so no parsing takes place for markdown.

• pygments: Just do this with your code:

  {% highlight python %}
  def yourfunction():
       print "Hello World!"
  {% endhighlight %}
  

  You also get linenumbers by doing:

  {% highlight python linenos %}   
  {% endhighlight %}
  

Edit: And also, You'll need to generate the syntax stylesheet using the command

pygmentize -S default -f html > style.css

as mentioned here and by @joshuahornby10. Include style.css in your html, obviously. Then, your code will be syntax-highlighted with pygments.

Oh, and you needn't change any settings in _config.yaml for this to work. Just run your site using jekyll --server --auto and see if it's looking good. Side note, when editing the _config file you will need to stop the auto run and re run jekyll for any changes to take place.

回答3:

In the config file change

 pygments:    false 

to

 pygments:    true

This will mean when you write code sections in the markdown file (great resource http://daringfireball.net/projects/markdown/) they will use the pygments styling. Make sure you have installed, this is a mistake i made. Also once its installed you will need to create a css file for the styling to take place (sounds obvious but i made this mistake)

 pygmentize -S default -f html > stylesheets/pygments.css

You can change default to anyone of the themes found here:

http://pygments.org/demo/35195/

With regards to markdown I have read that in order to get pygments to work you need to markdown to be maruku which you already have set up in the config file.

Hope this helps, I have found Jekyll is a brillant blogging platform but very under documented.