Well, it's happened again, I've jumped (back) on the static blog engine
bandwagon. Early versions of my site were generated literally using #define
,#include
, gcc
, and a Makefile
...). Back then I was transitioning away
from using livejournal, and decided to
use WordPress so I wouldn't have to roll my own RSS feed generator.
I tolerated WP for a while - and the frequency of my posts was so low, that it wasn't much of an issue.
Except for the security upgrades. I logged into the wp-admin
console way more
times than I cared to just to press the little "upgrade" box. The reason is that
wordpress keeps everything in a database that gets queried every time someone
hits the site. I was never comfortable with the fact, because content can be
lost in case of database corruption during either an upgrade or a security
breech. Also, my content just isn't that dynamic. The WP-cache stuff just seemed
overkill, since I don't get that many visitors.
But lately, I've found myself wanting to write more, to post more, but also shying away from it because I hate dealing with the WordPress editor. And I also hate being uncertain about whether any of it will survive the next upgrade, or the next security hole, whichever I happen to stub my toe on first.
And the thing is, I really like to use version control for everything I do. I liked my blog posts to be just text files I can check into version control. I also like typing "make" to generate the blog, and now I get to!
For added fun, I'm hoping that writing my posts in markdown will make it easier to coordinate my gopher presence, since it's pretty close.
For posterity, I'm capturing what the first version of my Pelican-based blog looked like. I did the same thing when I moved to WordPress.
I ran into some confusing things about transitioning to Pelican, so I thought I'd note them here, for the benefit of others.
Unadulturated code blocks
I like to use indentation as a proxy for the venerable <tt>
tag - which uses a
monospace font.
If you just want to use an indentation, but do not want the indented text parsed
as a programming language, put a :::text
at the top of that block. Here's what
I mean. Take this Oscar Wilde quote, where I've inserted a line break for
drammatic effect, for example:
A gentleman is one who never hurts anyone's feelings
unintentionally.
Now, you see that ugly red box around the apostrophe? Well, That's because all I
did was indent the two lines. If I just put a :::text
above the quote,
indented to the same level,
:::text
A gentleman is one who never hurts anyone's feelings
unintentionally.
the result will render like this.
A gentleman is one who never hurts anyone's feelings
unintentionally.
As the pelican documentation specifies, this is also the way you can also
specify the specific programming language you want, so :::python
would be one
way to not make pygments guess. You can get a list of all supported languages
here, just use one of the short names
for your language of choice.
And you should really do this, even if you aren't bothered by the red marks,
because the code highlighting plugin goes in and tokenizes all of those words
and surrounds them in <span>
tags. Here's the HTML generated for the first
version:
<div class="codehilite"><pre><span class="n">A</span> <span class="n">gentleman</span> <span class="n">is</span> <span class="n">one</span> <span class="n">who</span> <span class="n">never</span> <span class="n">hurts</span> <span class="n">anyone</span><span class="err">'</span><span class="n">s</span> <span class="n">feelings</span>
<span class="n">unintentionally</span><span class="p">.</span>
</pre></div>
and here's the version generated when you add the :::text
line at the top:
<div class="codehilite"><pre>A gentleman is one who never hurts anyone's feelings
unintentionally.
</pre></div>
nikola?
At some point, having a dialogue with myself, I wrote in here "or should I not use pelican and use nicola instead?"
Ok, tried it - nikola takes too long to startup -
nikola --help
real 0m1.202s
user 0m0.876s
sys 0m0.300s
pelican --help
real 0m0.639s
user 0m0.496s
sys 0m0.132s
I'm sure it's a fine static blogging engine - and Damian Avila's already
written IPython Notebook converters for it, but it just feels like it tries to
do too many things. Constraints are good. I'll stick with Pelican for now.
(Though I did use the nikola wordpress import
tool
to grab the wp-upload
images from my WordPress blog)
another set of instructions I consulted: Kevin Deldycke's WordPress to
Pelican, which is how
I did get my articles out using exitwp
which I patched slightly, so files got
saved as .md, and preserve other format properties.
Redirects
also known as: not breaking the web
I wanted to preserve rss feeds, and also not break old WordPress style
/YYYY/MM/DD urls - the Nikola wp-import script had created a url remapping
scheme in a file called url_map.csv
.
I don't have that many posts, so I just added them in by hand:
Options +FollowSymLinks
RewriteEngine on
RedirectMatch 301 /blog/feed/ /blog/feeds/all.atom.xml
RedirectMatch 301 /blog/2006/10/18/todd-chritien-greens-choice-voting/ /blog/todd-chritien-greens-choice-voting.html
RedirectMatch 301 /blog/2007/01/04/changelogs-with-dates-gui-goodness/ /blog/changelogs-with-dates-gui-goodness.html
...
Enabling table of contents for posts
If you want to include a table of contents within a post using [TOC]
, you must
enabled the markdown toc
processor with a line like this is your
pelicanconf.py
:
MD_EXTENSIONS = [ 'toc', 'codehilite','extra']
Categories and tags
Ok, so this was never clear to me in wordpress, either - but what's the difference between a tag and a category? is it the case that a post can only belong to one category, whereas it can have any number of tags?
I think I used categories as tags on wordpress. Looks like all posts on Pelican can have at most one category. Turns out this little aside was long enough to turn into its own post, so if you're interested, pelican tags-vs-categories has got you covered.
That's it for now
Thanks to Preston Holmes (@ptone) for encouraging me to transition away from WordPress, and pointing me to this post by Gabe Weatherhead (@MacDrifter) for how to do that. It should be said that the pelican documentation itself is very good for getting you going. Additionally, I consulted this post by Steve George which has a good description to get you started, and also covers a bunch of little gotchas, and lots of pointers. Also, thanks to Jake Vanderplas (@jakevdp) for his writeup on transitioning to Pelican, which I will consult later for incorporating IPython notebooks into my markdown posts, in the future. This is good enough for now. LTS.
permalink