Emacs, Markdown, Pandoc, Org Mode, Blogging, Wikis and More

Today I received an email from Chris Harrington asking me about how I use Emacs and Markdown to write this blog. It sparked a conversation that we both agreed could be useful to others, and Chris graciously gave me the thumbs-up to post our conversation here. So I hope fellow Emacs users find some useful information here, and I welcome any comments.

The rest of this post is made up of verbatim copies of our emails, with certain parts redacted for privacy and readability.

First Email From Chris

I’ve been reading your blog – Emacs and Markdown topics, etc. Very helpful stuff. Saw mention a couple times that you use emacs and markdown to write your blog and wondered if you have written anything which describes your tools and process.

My Response

Saw mention a couple times that you use emacs and markdown to write your blog and wondered if you have written anything which describes your tools and process.

Huh—I could have sworn that I did. But when I actually look at the site apparently I never have.

Besides Emacs and Markdown Mode I use two other programs for my blog:

  1. Pandoc
  2. Tup

Pandoc is really the important one, as it’s what I use to convert Markdown documents into HTML. Also Pandoc provides some convenient extensions to Markdown which I find useful. Tup is just there to automate the whole process of converting the Markdown documents into HTML files. I keep them all in a public GitHub repo. At the top-level is one Tup macro that I use everywhere. All of the articles are Markdown documents stored in the drafts folder. The structure of the content folder is a mirror of that, with Tupfiles everywhere that use that macro to generate the HTML files, which Git explicitly ignores since I don’t care to commit those.

So I will write an article, something like drafts/Tools/Emacs/foo.md. Then run tup upd, and that will use Pandoc to create content/Tools/Emacs/foo.html which I simply copy-paste right into WordPress.

Follow-Up Question About Pandoc

I had downloaded Pandoc and was just researching how to integrate it into Emacs when I got your email. Do you use Pandoc with Markdown Mode? What .emacs settings facilitate that?

My Suggestions Regarding Pandoc

I wrote this little bit of Emacs Lisp for that purpose:

(defun convert-markdown-to (newtype)
  "Converts the current buffer, assumed to be in Markdown format,
into a new format.  The new format must be one acceptable to
`Pandoc'.  The function opens the new file in a buffer if called
interactively.  If not called interactively then it returns the
name of the new file."
  (interactive "sOutput: ")
  (let ((current-document (buffer-file-name))
        (temp-filename (concat "/tmp/output." newtype)))
    (with-temp-file temp-filename
      (call-process-shell-command (concat "pandoc -f markdown -t " newtype)
                                  nil t nil current-document))
    (cond ((called-interactively-p 'any)
           (with-current-buffer (find-file temp-filename)))
          (t temp-filename))))

(define-key markdown-mode-map (kbd "C-c c") 'convert-markdown-to)

With that I can be working on a Markdown document and then convert it via Pandoc by pressing C-c c and then typing in anything acceptable for Pandoc’s --to parameter. If you want to use that code you will probably want to change the value of temp-filename, as it makes an assumption about directory structure that may not be true for your system. Zaike Yuki did that today along with making a few other tweaks. So you may it useful to compare those Elisp changes to mine.

I also suggest Pandoc Mode by Joost Kremers. I would not have bothered to write that utility function if his mode had been released at the time. It requires a little bit of setup and configuration, but I think it’s a great package and I highly recommend it.

Finally, I also write all of these emails in Markdown. I use Thunderbird as my email client, so if you happen to use that then you would like the Markdown Here plugin. When it comes to email it saves me from having to do C-c c html and then copy-pasting the output.

I would honestly recommend Kremers’ Pandoc Mode over my own little function. Not only does it provide a great interface for conversion, it has a cool template system if you ever really want to customize your Pandoc output.

Chris Talking About More Than Markdown

I had seen the Pandoc mode, but wanted to get a base understanding first. I found this guy’s .emacs write up and found that he had this:

(add-to-list 'auto-mode-alist '("\\.md$" . markdown-mode))
(add-to-list 'auto-mode-alist '("\\.mdown$" . markdown-mode))
(add-hook 'markdown-mode-hook (lambda () (visual-line-mode t)))
(setq markdown-command "pandoc --smart -f markdown -t html")
(setq markdown-css-path (expand-file-name "markdown.css" abedra/vendor-dir))

So what go me started on all this you might ask. Well, I sat down today to write up some new documentation, and I just couldn’t convince myself to use Word. After using Emacs for 30+ years, I decided to join the Markdown and Org tribes.

Next I’ll be looking at automation with Tup, etc. My dream scenario is this. I write tech stuff all day anyway. Project notes. Just for myself. Dozens of projects for dozens of clients. I want to selectively publish this material to the web, including posting to Blog, Facebook, Twitter, etc. I know some such automation is already available in those platforms. But currently I don’t even have a blog. I’m leaning towards WordPress but it appears that only the installed version supports automation add-ons.

My Response About Hooks, Tup, Wikis, and Org Mode

(add-hook 'markdown-mode-hook (lambda () (visual-line-mode t)))

Even though it seems trivial, I would recommend against using lambdas with hooks like this. Personally I would write something like this:

(defun ejmr/setup-markdown-mode ()
(visual-line-mode t))

(add-hook ‘markdown-mode-hook ’ejmr/setup-markdown-mode)

There are two nice benefits to this:

  1. You can use remove-hook if you ever need to temporarily disable some settings. You cannot easily disable a hook which is an anonymous function.

  2. If there is a bug in your hook code you will get debugging output that is a lot easier to read, as it will have a function name to give you.

Next I’ll be looking at automation with Tup, etc. My dream scenario is this. I write tech stuff all day anyway. Project notes. Just for myself. Dozens of projects for dozens of clients. I want to selectively publish this material to the web, including posting to Blog, Facebook, Twitter, etc. I know some such automation is already available in those platforms. But currently I don’t even have a blog. I’m leaning towards WordPress but it appears that only the installed version supports automation add-ons.

I like using Tup a lot but there is one feature of its design that you should be aware of: you must create a Tupfile for every directory in which you create output. So for example, on my blog I need one Tupfile in every sub-directory of articles. That can become tedious. When I am using Tup as an alternative to GNU Make or CMake or something for building software it is much less of an issue, because I rarely have that many sub-directories of source code to compile. But if you want to automate something that creates output in a lot of directories then Tup may not be the most convenient tool.

Regarding Twitter, I really enjoy using Twittering Mode.

And regarding blogging, WordPress is a platform that I like, but I don’t have any serious brand loyalty to it. If you choose to use it or any major blogging platform then you will be able to find Emacs packages to help you create your blog content in Emacs. For example, people have made bridges between Org Mode and WordPress, and there are similar Org Mode add-ons for a lot of other blogging platforms.

The same goes for wiki software as well. Very recently I’ve started using Zim, which actually I mean to blog about in the near future. It has a plugin so you can use it as a blog platform, but I’ve not tried that myself. But I am finding it to be great for collaboration with my non-Emacs–using teammates. For example, I’ve been working for almost two years now on a computer game with a close friend. He does his development on a Windows 7 machine, using Eclipse as his IDE. We have started using Zim to create a private wiki for notes about our game, and it works really well because:

  1. It has cross-platform support, with a nice GUI.

  2. It stores all content in plain text files that I can easily edit with existing wiki modes for Emacs.

  3. And since all of the data is plain text we can easily store it in a Git repository to keep a history of it. Zim actually comes built-in with a plugin for this.

Your comment about software with “automation add-ons” just made me think of Zim. For me it’s been a recent example of a great piece of content-publishing software that not only works very well with Emacs, but makes it easy to share and collaborate with non-Emacs users. Since you’re writing a lot I’d definitely look at all of the options out there for Emacs, particularly those based around Org Mode, because that has become very popular as an authoring tool and there’s a lot of support out there for organizing and publishing your writings through Org Mode.

Advertisements

2 thoughts on “Emacs, Markdown, Pandoc, Org Mode, Blogging, Wikis and More

  1. I still basically do everything in org-mode at work. They’ve really improved the export process in the last few years (though some of the textile stuff can get a little funky).

Add Your Thoughts

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s