|
bgneal@4
|
1 Blogofile, reStructuredText, and Pygments
|
|
bgneal@4
|
2 #########################################
|
|
bgneal@4
|
3
|
|
bgneal@4
|
4 :date: 2011-04-17 19:15
|
|
bgneal@4
|
5 :tags: Blogofile, Pygments, reStructuredText
|
|
bgneal@4
|
6 :slug: blogofile-restructuredtext-and-pygments
|
|
bgneal@4
|
7 :author: Brian Neal
|
|
bgneal@4
|
8
|
|
bgneal@4
|
9 Blogofile_ has support out-of-the-box for reStructuredText_ and Pygments_. Blogofile's
|
|
bgneal@4
|
10 ``syntax_highlight.py`` filter wants you to mark your code blocks with a token such as
|
|
bgneal@4
|
11 ``$$code(lang=python)``. I wanted to use the method I am more familiar with, by configuring
|
|
bgneal@4
|
12 reStructuredText with a `custom directive`_. Luckily this is very easy. Here is how I did it.
|
|
bgneal@4
|
13
|
|
bgneal@4
|
14 First of all, I checked what version of Pygments I had since I used Ubuntu's package
|
|
bgneal@4
|
15 manager to install it. I then visited `Pygments on BitBucket`_, and switched to the tag that matched
|
|
bgneal@4
|
16 my version. I then drilled into the ``external`` directory. I then saved the ``rst-directive.py``
|
|
bgneal@4
|
17 file to my blog's local repository under the name ``_rst_directive.py``. I named it with a leading
|
|
bgneal@4
|
18 underscore so that Blogofile would ignore it. If this bothers you, you could also add it to
|
|
bgneal@4
|
19 Blogofile's ``site.file_ignore_patterns`` setting.
|
|
bgneal@4
|
20
|
|
bgneal@4
|
21 Next, I tweaked the settings in ``_rst_directive.py`` by un-commenting the ``linenos`` variant.
|
|
bgneal@4
|
22
|
|
bgneal@4
|
23 All we have to do now is to get Blogofile to import this module. This can be accomplished by making
|
|
bgneal@4
|
24 use of the `pre_build() hook`_ in your ``_config.py`` file. This is a convenient place to hang
|
|
bgneal@4
|
25 custom code that will run before your blog is built. I added the following code to my
|
|
bgneal@4
|
26 ``_config.py`` module
|
|
bgneal@4
|
27
|
|
bgneal@4
|
28 .. sourcecode:: python
|
|
bgneal@4
|
29
|
|
bgneal@4
|
30 def pre_build():
|
|
bgneal@4
|
31 # Register the Pygments Docutils directive
|
|
bgneal@4
|
32 import _rst_directive
|
|
bgneal@4
|
33
|
|
bgneal@4
|
34 This allows me to embed code in my ``.rst`` files with the ``sourcecode`` directive. For example,
|
|
bgneal@4
|
35 here is what I typed to create the source code snippet above::
|
|
bgneal@4
|
36
|
|
bgneal@4
|
37 .. sourcecode:: python
|
|
bgneal@4
|
38
|
|
bgneal@4
|
39 def pre_build():
|
|
bgneal@4
|
40 # Register the Pygments Docutils directive
|
|
bgneal@4
|
41 import _rst_directive
|
|
bgneal@4
|
42
|
|
bgneal@4
|
43 Of course to get it to look nice, we'll need some CSS. I used this Pygments command to generate
|
|
bgneal@4
|
44 a ``.css`` file for the blog.
|
|
bgneal@4
|
45
|
|
bgneal@4
|
46 .. sourcecode:: bash
|
|
bgneal@4
|
47
|
|
bgneal@4
|
48 $ pygmentize -f html -S monokai -a .highlight > pygments.css
|
|
bgneal@4
|
49
|
|
bgneal@4
|
50 I saved ``pygments.css`` in my ``css`` directory and updated my site template to link it in.
|
|
bgneal@4
|
51 Blogofile will copy this file into my ``_site`` directory when I build the blog.
|
|
bgneal@4
|
52
|
|
bgneal@4
|
53 Here is what I added to my blog's main ``.css`` file to style the code snippets. The important thing
|
|
bgneal@4
|
54 for me was to add an ``overflow: auto;`` setting. This will ensure that a scrollbar will
|
|
bgneal@4
|
55 appear on long lines instead of the code being truncated.
|
|
bgneal@4
|
56
|
|
bgneal@4
|
57 .. sourcecode:: css
|
|
bgneal@4
|
58
|
|
bgneal@4
|
59 .highlight {
|
|
bgneal@4
|
60 width: 96%;
|
|
bgneal@4
|
61 padding: 0.5em 0.5em;
|
|
bgneal@4
|
62 border: 1px solid #00ff00;
|
|
bgneal@4
|
63 margin: 1.0em auto;
|
|
bgneal@4
|
64 overflow: auto;
|
|
bgneal@4
|
65 }
|
|
bgneal@4
|
66
|
|
bgneal@4
|
67 That's it!
|
|
bgneal@4
|
68
|
|
bgneal@4
|
69 .. _Blogofile: http://blogofile.com
|
|
bgneal@4
|
70 .. _reStructuredText: http://docutils.sourceforge.net/rst.html
|
|
bgneal@4
|
71 .. _Pygments: http://pygments.org/
|
|
bgneal@4
|
72 .. _custom directive: http://pygments.org/docs/rstdirective/
|
|
bgneal@4
|
73 .. _Pygments on BitBucket: https://bitbucket.org/birkenfeld/pygments-main
|
|
bgneal@4
|
74 .. _pre_build() hook: http://blogofile.com/documentation/config_file.html#pre-build
|
