Blogging with Emacs and Org-mode
I've finally got my new blog up! I've been wanting to migrate from Middleman, a static-site generator written in Ruby. The problem was that it was too many steps to post a new article - so I just never did.
I've been eyeing a few solutions for blogging completely from within Emacs. There's some good (and some outdated) software on the wiki to accomplish that.
I finally came across org-page, which seemed to be exactly what I wanted. The documentation was a little terse, but it's a simple setup so I decided to give it a shot.
Here's what I was able to get set up, with a few snippets to accompany the official documentation.
- Write blogs completely in
- Publish to GitHub pages (or anywhere you can push static files).
- One command publish
- Ability to customize a theme, or write my own
- Tags, RSS Feed, and all the other blog goodies.
- Never have to leave Emacs
Set up a repo
Org-page also handles this for you, with the available command
op/new-repository. So find a place on your system you want
M-x op/new-repository RET /path/to/new/blog RET
This sets up a new git repository, with a few pages already laid out for you (index.org, about.org, readme, etc).
Org-page in your init.el
There are few things you'll need to set up in your Emacs config file to get things working correctly. Here's an annotated example:
(require 'org-page) (setq op/repository-directory "~/workspace/play/newblog") (setq op/site-domain "http://codyreichert.github.io") (setq op/personal-github-link "https://github.com/CodyReichert") (setq op/site-main-title "The One True Blog") (setq op/site-sub-title "Emacs, Programming, and Arch Linux") (setq op/personal-disqus-shortname "theonetrueblog")
Kelvin used very sane variable names, so most of that should be self-explanatory. Not all of those are required, but if you leave out things like the GitHub Link, it just won't show at all - perfect.
Reload your Emacs config and let's move on
Creating a new post
You'll probably first want to fill out some of the generated
Pro-tip: If you remove the
index.orgit will default to a list of posts, like mine. It's preferable since there is already an about page.
Once again, org-page has another built in command to get a new post started. The best thing about it is that is handles the description, file name, post uri, tags, and more. Meaning you can get to just writing articles, not boilerplate.
M-x op/new-post RET
It will run you through a few steps to generate all of those fields for you post, and put your cursor where you can start writing. op/new-post gif
Publishing your new blog
Yet again...built in to org-page. And since we're in Emacs, we can make it do whatever we want. First, make sure you set the remote in your blogs git repo:
git remote add origin email@example.com:CodyReichert/CodyReichert.github.io git remote -v
Org-page has a command
op/do-publication. It asks a couple of
questions, and compiles the org mode pages for you. When you set up
your repository, org-page created two branches: source and
master. This is a good setup for GitHub-pages and probably most
other hosts. All of your org files live on the source branch, and
org-page will add and commit the compiled files to the mater branch.
- Publish all org-files (y or n)
- Publish to directory? (original repo if not) (y or n) This on is particularly useful for sending the compiled files to another directory, which you can watch with a simple HTTP server and quickly view changes when your writing.
- Auto-commit to repo? (y or n)
- Auto-push to repo? (y or n)
The last two are great, because all I need to do run
op/do-publication and the new post is live within a few
seconds. That's the Emacs way.
Here's a GIF of how I published this blog, right after I wrote this part.
I have a few other snippets for using a custom theme with org-page, and a couple other nice settings I'll share eventually.
My recommendation is to
C-h f RET ___ RET on some of the org-page
functions, they're documented well.
You can also view my org-page setup here.
:: Cody Reichert