markdown to blog and documents

Recently I started using markdown files as a quick way to write documentation on projects. At first I didn’t bother converting the files as there is at least one plug in in chrome that can render them as HTML. In Visual studio I just used the Markdown Mode extension to work with.

Then I thought of starting a (static) blog and since I already had markdown files, I was in the market for a static site generator. After trying out several different generators I settled on Hexo which works with simple command line instructions to create posts (in markdown) and generate a site from them.

I could then easily host this static site on github pages. Refer to the deployment page of the Hexo documentation on how to achieve that. There are a lot of blog posts out there on how to set this up as well if you need further assistance.

Now I still wanted to have these documents in my project folder as documentation, so I looked for a way to generate them without all the headers and navigation and such that I would have on the blog. I could a new theme or renderer to Hexo, but I found a better alternative called Pandoc. This lets me generate PDF files from markdown. So now I have one source document written in markdown and (at least) two different output formats.

There are still some issues I’m having, that I want to clear up. The first is a problem with image links Hexo seems to like a leading slash in the image URLs, while Pandoc only seems to work without. Now I haven’t spent much time on this, so there’s bound to be a solution for it.

The second issue is that now I have two different tools to render the output. It’s not a big problem but I would like to have them both in a single command or pipeline. At the moment this is how I do it. I’m using windows command line to navigate to the Hexo directory first.

create a new post

Using the statement below creates a new markdown document in the _posts folder of your Hexo folder structure.

hexo new post "Post Name"

generate my site

This command generates the full site in the public folder.

hexo generate

copy the generated site to a local IIS site

As I want to verify that the site works (and also to have an offline copy), I have a local IIS site setup. This is in a different location so I can see what would be deployed.

xcopy D:\SITE_PATH\public D:\[IIS_SITE_PATH]\Sitecorn /e /d

Copy to a GIT repository

For the moment I’m not using the hexo deploy feature. I have several GIT repositories set up for other projects so it makes sense to have this one in the same location. I commit and deploy this repository with the github desktop application, but there are many more tools out there you could use.

xcopy D:\Projects\sitecorn\public C:\Users\rubenv\Documents\GitHub\ /e /d

Generate PDF documents

This command loops through the markdown documents and uses Pandoc to generate the PDF files and puts them in the LOCATION folder.

for /r %i in (_posts/*.md) do pandoc _posts/ -o  LOCATION/%~ni.pdf

Finally if you only need to generate a single file you can use the following command.

pandoc source/_posts/ -o portal/my_document.pdf