Well, hi there!
This is one of those 'I've been meaning to do this forever' kind of things. I feel like I've had all the tools in my toolbox, but never the exact amount of time or motivation. But here it is. I decided to make my first post a little meta: some of the nuts and bolts of how I actually came to develop this blog.
First of all, I needed somewhere to host this thing. As luck turned out, I recently went through the work of developing my website. Using Github's pages feature was a natural choice. I'm still a bit of a website noob, so (at the time of writing), I'm just using the extended domain mattgidden.com/blog. One day I'll get a better grasp on subdomains and look to make it rather blog.mattgidden.com or some such. I have the feeling that the ghpages-all-in-one-website approach may be limiting there.
How do you say 'notebook' in French?
In any case, the next question was what blog static website generator service to use. I really only looked at two:
My initial thought was "Why not Jekyll? You get automatic ghpages support!", but (un)fortunately, my use case was a bit more complicated. Since I'm using Github as my only (free) webhosting service, I need it to support all of my websites. Not only was I interested in having a blog, but I also wanted to host my Sphinx-generated Cyclopts project documentation. This ran afoul of a major design decision in Jekyll and the way Sphinx generates websites: Jekyll doesn't publish directories that start with a _, and Sphinx generates websites with exactly those kinds of directories. The answer? Bypass Jekyll. The consequence? We bypassed Jekyll.
But, lo, we get a nice benefit. You see, Jekyll has no native ReST support. It has a plugin, but I found it hard to use. I happen to write a lot of ReST, and I wanted to write this blog in ReST.
Enter Pelican. It had everything I wanted: an easy build system, easy content discovery, a getting started executable, and an html layout that fits in seamlessly with a ghpages repo with a .nojekyll file in it.
Makefiles are amazing things
I actually keep my blog repository separate from my website repo, and I only keep html in my website repository. My local copy of each is in ~/personal/site and ~/personal/blog, respectively. Accordingly, I had to update the blog repos Makefile with the following lines:
# override default output dir OUTPUTDIR=$(BASEDIR)/build # doc publishing variables BUILDDIR = $(OUTPUTDIR) DOCREPOURL = git@github.com:gidden/gidden.github.io DOCREPODIR = ~/personal/site DOCUPDATENAME = blog DOCHTMLDIR = $(DOCREPODIR)/blog TMPDOCDIR = $(DOCREPODIR)/.$(DOCUPDATENAME)tmpdocs # this should likely go at the end -- other targets use OUTPUTDIR publish: @echo @echo "Updating $(DOCHTMLDIR) with current documentation." test -d $(DOCREPODIR) || git clone $(DOCREPOURL) $(DOCREPONAME) && \ test ! -d $(TMPDOCDIR) || rm -r $(TMPDOCDIR) && \ mkdir -p $(TMPDOCDIR) && \ cp -r $(BUILDDIR)/* $(TMPDOCDIR) && \ cd $(DOCREPODIR) && git pull origin master && \ test ! -d $(DOCHTMLDIR) || rm -r $(DOCHTMLDIR) && \ mkdir -p $(DOCHTMLDIR) && mv $(TMPDOCDIR)/* $(DOCHTMLDIR) && \ rm -r $(TMPDOCDIR)/ && \ cd $(DOCREPODIR) && git add $(DOCHTMLDIR) && \ if [ -n "$$(git status $(DOCHTMLDIR) --porcelain)" ]; \ then git commit -m "updated $(DOCUPDATENAME) html" && git push origin master; \ fi @echo @echo "$(DOCHTMLDIR) updated and pushed to $(DOCREPOURL)." .PHONY: publish
Now, any time I write a new blog post, I can publish it with a simple
$ make html && make publish
I need an interior decorator
Or some time and a desire more front-end design practice. The css they give you is pretty ugly. But I have frisbee to play, so I'll leave that for another time!