bgneal@4: Blogofile, reStructuredText, and Pygments
bgneal@4: #########################################
bgneal@4: 
bgneal@4: :date: 2011-04-17 19:15
bgneal@4: :tags: Blogofile, Pygments, reStructuredText
bgneal@4: :slug: blogofile-restructuredtext-and-pygments
bgneal@4: :author: Brian Neal
bgneal@4: 
bgneal@4: Blogofile_ has support out-of-the-box for reStructuredText_ and Pygments_. Blogofile's
bgneal@4: ``syntax_highlight.py`` filter wants you to mark your code blocks with a token such as
bgneal@4: ``$$code(lang=python)``. I wanted to use the method I am more familiar with, by configuring
bgneal@4: reStructuredText with a `custom directive`_. Luckily this is very easy. Here is how I did it.
bgneal@4: 
bgneal@4: First of all, I checked what version of Pygments I had since I used Ubuntu's package
bgneal@4: manager to install it. I then visited `Pygments on BitBucket`_, and switched to the tag that matched
bgneal@4: my version. I then drilled into the ``external`` directory. I then saved the ``rst-directive.py``
bgneal@4: file to my blog's local repository under the name ``_rst_directive.py``. I named it with a leading
bgneal@4: underscore so that Blogofile would ignore it. If this bothers you, you could also add it to
bgneal@4: Blogofile's ``site.file_ignore_patterns`` setting.
bgneal@4: 
bgneal@4: Next, I tweaked the settings in ``_rst_directive.py`` by un-commenting the ``linenos`` variant.
bgneal@4: 
bgneal@4: All we have to do now is to get Blogofile to import this module. This can be accomplished by making
bgneal@4: use of the `pre_build() hook`_ in your ``_config.py`` file. This is a convenient place to hang
bgneal@4: custom code that will run before your blog is built. I added the following code to my
bgneal@4: ``_config.py`` module
bgneal@4: 
bgneal@4: .. sourcecode:: python
bgneal@4: 
bgneal@4:    def pre_build():
bgneal@4:        # Register the Pygments Docutils directive
bgneal@4:        import _rst_directive
bgneal@4: 
bgneal@4: This allows me to embed code in my ``.rst`` files with the ``sourcecode`` directive. For example,
bgneal@4: here is what I typed to create the source code snippet above::
bgneal@4: 
bgneal@4:    .. sourcecode:: python
bgneal@4: 
bgneal@4:       def pre_build():
bgneal@4:           # Register the Pygments Docutils directive
bgneal@4:           import _rst_directive
bgneal@4:    
bgneal@4: Of course to get it to look nice, we'll need some CSS. I used this Pygments command to generate 
bgneal@4: a ``.css`` file for the blog.
bgneal@4: 
bgneal@4: .. sourcecode:: bash
bgneal@4: 
bgneal@4:    $ pygmentize -f html -S monokai -a .highlight > pygments.css
bgneal@4: 
bgneal@4: I saved ``pygments.css`` in my ``css`` directory and updated my site template to link it in.
bgneal@4: Blogofile will copy this file into my ``_site`` directory when I build the blog.
bgneal@4: 
bgneal@4: Here is what I added to my blog's main ``.css`` file to style the code snippets. The important thing
bgneal@4: for me was to add an ``overflow: auto;`` setting. This will ensure that a scrollbar will
bgneal@4: appear on long lines instead of the code being truncated.
bgneal@4: 
bgneal@4: .. sourcecode:: css
bgneal@4: 
bgneal@4:    .highlight {
bgneal@4:       width: 96%;
bgneal@4:       padding: 0.5em 0.5em;
bgneal@4:       border: 1px solid #00ff00;
bgneal@4:       margin: 1.0em auto;
bgneal@4:       overflow: auto;
bgneal@4:    }
bgneal@4:    
bgneal@4: That's it!
bgneal@4: 
bgneal@4: .. _Blogofile: http://blogofile.com
bgneal@4: .. _reStructuredText: http://docutils.sourceforge.net/rst.html
bgneal@4: .. _Pygments: http://pygments.org/
bgneal@4: .. _custom directive: http://pygments.org/docs/rstdirective/
bgneal@4: .. _Pygments on BitBucket: https://bitbucket.org/birkenfeld/pygments-main
bgneal@4: .. _pre_build() hook: http://blogofile.com/documentation/config_file.html#pre-build