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.

1
hexo new post "Post Name"

generate my site

This command generates the full site in the public folder.

1
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.

1
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.

1
xcopy D:\Projects\sitecorn\public C:\Users\rubenv\Documents\GitHub\rubenVerschueren.github.io /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.

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

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

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