Over the past week, I've had several people write me asking how I prefer to do syntax highlighting. It's funny that this question cropped up now, just as I changed the way that it's handled on this blog. The way that I used to do it was what I posted to djangosnippets almost a year ago: use a regular expression to parse out <code></code> blocks, highlight the stuff in-between, and spit it back out.
The problem with that method was that that would require some more sophisticated logic now that I'm using RestructuredText to write all of my posts. Unwilling to think any harder than necessary, I did a quick google search, and the second result was exactly what I was looking for: a RestructuredText directive, ready-made by the Pygments people.
The trick is to put this file somewhere on your python path. Then, in the __init__.py of one of the Django apps that will use syntax highlighting, just import the file. It's that simple! (I love RestructuredText.) But it's not only RestructuredText that benefits from this style of plugin. Markdown, too, has a similar plugin--again provided by the Pygments people.
.. sourcecode:: python
print "This is an example of how to use RestructuredText's new directive."
I hope that this answers some of the questions that people had. On a similar note, I'm extremely happy to see that people have been finding the Contact Me link on the right side of the page. Please continue to send me any questions and comments that you have for me!
All Content
Hi Eric,
Thanks for sharing your tips. I've been building my own Django-powered blog but I'm new to publishing concepts. Your posts have been timely in helping me connect the dots and saving me a few minutes in searching.
-Brian
How does restructuredtext compare to markdown? I've had a quick look at them both, and it seems that markdown has a more pleasant link syntax but rst looks more extendable (directives are a little more focussed and less messy in syntax than markdown extensions are proving to be).
Trouble is, I can't find any really good documentation on rst (ironic). The stuff on the docutils page is fairly awful -- can't even seem to find out how to make a linked image, or a link with a title attribute!
I agree that the stuff on the docutils site could use some work. I pretty much agree with your assessment that rst is more extendable but markdown's syntax is (by default) a bit better.
The image directive is here: http://docutils.sourceforge.net/docs/ref/rst/directives.html#image
Here's a good reference to the syntax: http://docutils.sourceforge.net/docs/user/rst/quickref.html
Yeah, I see how to include an image and also how to make a link... but how are they combined? Like an HTML "img" tag *inside* an "a href" link tag.
In markdown it's down by nesting (might not be supported by the python parser yet, though I think markdown2.py works):
[](http://url.com/ "Link Title")
Or as (preferred) reference style:
... [![alt text][image]][link] ...
afterwards:
[image]: /path/img.jpg "Image Title"
[link]: http://url.com/ "Link Title"
I can't see a way of doing that in rst -- or of getting the title attributes, either.
I have gotten an image link by doing the following:
.. image:: http://media.eflorenzano.com/img/powncesample.png
:target: http://media.eflorenzano.com/static/powncecreate.html
As for title attributes, I'm still not sure about that. Maybe a custom directive is in order?
...and sorry for the formatting on that last comment. I think you know what I was going for, though.
Ahhh... thanks! I wasted ages looking for that!
A directive for link titles... something like:
used inline in |some link text|?
.. |some link text| link:: http://foo.com/
:title: title
:rel: whatever
hmmm... could work, actually looks cleaner than the default links to me. I'll look into it.
Meh I take it back -- rst is no good for me. It seems the HTML writer is hardcoded to only output certain attributes that cannot be altered or added to by directives at all. That makes it impossible to add title or rel attributes to links without pretty much rewriting the output classes.
It's also hardcoded to output XHTML instead of HTML, which is annoying. Back to markdown I guess; shame as the syntax was really promising but the implementation is fairly awful :(