I have a number of documents I keep up to date. I write the text in markdown and I output to either HTML or PDF.

This post documents how you can run a command in Vim such as :Pandoc -o index.html --metadata date="01.04.2020" -s --template yourTemplate.html and get a HTML file generated with a given name, using a template for the output file, with the relevant meta data inserted.

The problem

Until recently, when I wanted to produce an HTML version of my markdown file, I have selected the markdown text, pasted it into Byword and then run ‘Copy HTML’ from the menu. Then taken that copied HTML and pasted it into the <body> of the HTML file I was using as a template. Then saved that off with the appropriate filename.

Hardly efficient.

The solution

We can use Pandoc, a universal document converter, to make our conversion. All that follows is macOS centric.

Our steps will be:

  • install Pandoc
  • install Vim-pandoc
  • create a HTML template for our md => conversions
  • understand the commands to run for various outputs

Install Pandoc

I used Homebrew brew install pandoc to install but it has a ‘clicky clicky’ installer if you prefer.


vim-pandoc provides some Vim integration for Pandoc. It means you can do conversions from within a buffer rather than having to break open another Terminal window.

I use Vim Plug: so Plug 'vim-pandoc/vim-pandoc' in my init.vim file and :PlugInstall.

Creating a basic HTML template

You can go nuts with your template. There are good examples to steal from here too.

Easiest thing to do is get the HTML file you are already happy with and just remove the contents of the body. Inside the HTML <body> tag, just type ${body}. That’s where the converted output from your markdown file is going to be written. You can specify the location of the CSS separately if you wish but I chose to stick my CSS in the head inside style tags.

I also wanted to print the date into the file. At present I’ve added the interpolated variable ${date} to do this. You can see where this data comes from in the command below.

Now save the template with an appropriate filename e.g. ‘template.html’.

Create the HTML from markdown

Here is an example of the command I now run to create my file:

:Pandoc --template template.html -s --metadata date="01.04.2020"

That’s going to run pandoc on the current buffer, use the template.html we just made, the -s flag tells it we want a standalone file (as opposed to just the content), and also passing in the metadata date so our template will insert 01.04.2020 where we added the variable.

Suppose you wanted to have a different name for the output file. It defaults to the name of your buffer. If your buffer is sausages.md then the resultant file will be sausages.html. Pass a different name with the -o flag (o for ‘output’). For example, to name the output cake.html and save it into the ‘myFolder’ folder:

:Pandoc --template template.html -o myFolder/cake.html -s --metadata date="01.04.2020"

I only got up and running with this today, I’d like to be able to pass todays date into the HTML template automatically. Haven’t figured that out.

It turns out, if you run the command as :exe you can pass the date programatically, so in the example below, the current days date will be added automatically.

:exe 'Pandoc! --template template.html -s -o myFolder/cake.html --metadata date='.strftime('%Y-%m-%d')


The command line arguments can seen off-putting for casual use. However, if you find yourself doing lots of tedious exports to the same format/file, this can be worth the time to set up.

In addition Pandoc supports output to a multitude of formats, making exports to PDF and the like a breeze too.

Learn to use CSS effectively, 'Enduring CSS' is out now

Get $5 off HERE ↠

Write and maintain large scale modular CSS and embrace modern tooling including PostCSS, Stylelint and Gulp