Experimenting with Markdown

I’m a software engineer at Microsoft. As part of my job, I use git everyday for version control, I do some writing in markdown for readme files and technical design docs, and I work on the Pipelines product for Azure DevOps. As I started writing notes for the mini-campaign that I was running for my daughter, I decided to see if I could set up a workflow to use the same tools for some game writing.

Wait… What’s Markdown?

Markdown is a text markup language that is intended to be simple and easy to read. Here’s an example:

# Green Slime

Green slimes are yellow-green oozes that are highly poisonous. They often 
hunt by waiting in ambush, poisoning something that comes close enough, 
and then slowly slithering behind it while the poison does its work.

Health | Speed | Size | Armor
:-----:|:-----:|:----:|:-----:
12     |6      |small |0

Com  |Con  |Dex  |Int  |Per  |Str  |Wil
:---:|:---:|:---:|:---:|:---:|:---:|:---:
-3   |+2   |+1   |-3   |0    |+2   |0

**Squelch:** A green slime can make a melee attack with a pseudopod. This 
attack deals 1d6+Str damage.

**Poison goo:** When a green slime attacks, it can use a stunt for 4 SP
that causes the target to become poisoned. A poisoned creature must make
a Constitution check against a difficulty of 11 at the start of each turn. 
If it fails, it takes 2 damage that ignores armor. If it succeeds, then it 
is no longer poisoned.

In that sample, there are a few types of formatting. Green Slime is a top-level header thanks to the leading octothorpe. The ability names have strong emphasis thanks to the wrapping asterisks. The tables aren’t a part of the original version of markdown, but that syntax is recognized by most markdown parsers.

I use Visual Studio Code as my local editor, but there are plenty of options for markdown editors. GitHub and Azure Repos also both offer online editors for markdown that include preview functionality to view the styled versions of the documents.

And What’s Git?

Git is one of the most popular version control systems for source code. It keeps a history of changes to the tracked files and makes it easy to examine a file’s history. It is supported by services like GitHub and Azure Repos that allow a repository to be stored and accessed online. The basic idea is that I can have a copy of my markdown files stored online and if I wanted to, I could easily collaborate with other authors by giving them access to my git repo.

Markdown to Document

While writing in markdown is pretty simple with any text editor, the interesting part is converting from the markdown to a formatted document. There are a lot of tools available for converting markdown to html locally, but I decided that I wanted to use Azure Pipelines to automate my conversion. I already had my markdown stored in Azure Repos, so this was just a matter of setting up a build with a continuous integration trigger so that it runs every time I push my updates to the file to the server.

There is a Markdown2Html task available in the Azure DevOps marketplace, so I used that as my starting point. It supported a template html file where the content from the markdown would be inserted. That’s great because it makes it easy to have custom css styles defined for the document.

After getting that to work, I decided to see if I could automate pdf creation too. Pdf files are a bit easier to share than html since their packaged as a single file and will render consistently everywhere. After a bit of research and experimentation, I settled on a tool called html5-to-pdf and added that to my build process.

When my build runs on the sample markdown at the beginning of the post, the server generates a pdf file like this one: Sample.pdf

If you’re interested in trying it out yourself, I’ve copied my sample to a GitHub repo: scottboehmer/markdown-to-pdf-sample.

What’s Next?

What I have right now is good enough for writing and the generated pdf files look decent, but I plan on experimenting with a few more things. First, the build agent only has the fonts that are included in Windows which is a pretty limited set. To address that, I want to figure out a way to install a new font as part of the build process. The pdf also is pretty basic with things like page margins not being ideal. For that I think I’ll need to do some more searching to see if I can find a better option than html5-to-pdf. I’d also like to experiment with incorporating spell-checking as part of the automation since that’s one thing I give up when I’m not writing in Word.