Mercurial > public > pelican-blog

comparison content/Coding/001-blogofile-rst.rst @ 4:7ce6393e6d30

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