Using a Global Rakefile with Pandoc

I've recently migrated this blog, and the older posts might not yet be satisfactorily cleaned up. Apologies for the temporary mess.

I wrote a post a while ago about how to use Rake to automate the process of building PDFs using Pandoc. The idea is that you drop the Rakefile into each project that has Markdown files, and by running rake pdfs you can generate the PDFs without typing long and awkward Pandoc commands. It works great.

But since I’m lazy (in the sense used by Larry Wall), it’s too much work to copy the Rakefile into each project. I just learned that you can use global Rakefiles, which will then be available in any directory. Here is how to do it.

First, create the directory ~/.rake. Then in that directory create a file pandoc.rake. The file should contain something like this:

<span class=“no”>MDFILES</span> <span class=“o”>=</span> <span class=“no”>FileList</span><span class=“p”>[</span><span class=“s2”>”*.md”</span><span class=“p”>]</span>
<span class=“no”>PDFS</span> <span class=“o”>=</span> <span class=“no”>MDFILES</span><span class=“p”>.</span><span class=“nf”>ext</span><span class=“p”>(</span><span class=“s2”>“.pdf”</span><span class=“p”>)</span>

<span class=“n”>desc</span> <span class=“s2”>“Use Pandoc to build PDFs of all Markdown documents”</span> <span class=“n”>task</span> <span class=“ss”>:pandoc</span> <span class=“o”>=></span> <span class=“no”>PDFS</span>

<span class=“n”>rule</span> <span class=“s2”>“.pdf”</span> <span class=“o”>=></span> <span class=“s2”>“.md”</span> <span class=“k”>do</span> <span class=“o”>|</span><span class=“n”>t</span><span class=“o”>|</span> <span class=“n”>sh</span> <span class=“s2”>“pandoc </span><span class=“si”>#{</span><span class=“n”>t</span><span class=“p”>.</span><span class=“nf”>source</span><span class=“si”>}</span><span class=“s2”> -o </span><span class=“si”>#{</span><span class=“n”>t</span><span class=“p”>.</span><span class=“nf”>name</span><span class=“si”>}</span><span class=“s2”>”</span> <span class=“k”>end</span>

<span class=“c1”># Only clobber generated PDFs</span> <span class=“nb”>require</span> <span class=“s2”>“rake/clean”</span> <span class=“no”>CLOBBER</span><span class=“p”>.</span><span class=“nf”>include</span><span class=“p”>(</span><span class=“no”>PDFS</span><span class=“p”>)</span>

Now in each directory you should be able to run rake -g pandoc to generate a PDF from each Markdown file. You can customize the shell command if you have more complicated needs, or you can create a project-specific Rakefile if the project is more complicated. For important projects you should definitely include a Rakefile in the repository, since the Rakefile records how to reproduce your outputs.

But for simple projects this is sufficient.