Switching to Markdown Format

published on

I am starting to get comfortable with hugo as a static site generator, I know I haven’t made my theme the “correct way” but for now it works to an acceptable minimum and most importantly the pages it produces are formatted perfectly.

I had an issue in that I couldn’t decide if I wanted to use Markdown or HTML when writing blog posts. The issue may seem silly (it is) but my reasons for having it were pretty straight forward:

Of course hugo (currently) supports the use of both at the same time but with some minor issues. Ideally I would prefer to use one standard for blog posts and stick with it. For the sake of uniformity and simplicity.

Here’s what I was previously doing when drafting a post:

  1. Write it in Markdown for ease of writing and proofreading
  2. Start hugo server -D so that I can preview the page
  3. Convert everything to HTML in the document
  4. Check preview again
  5. If it’s all good then publish.

Now the issue here should be obvious, I was effectively putting in twice the work for the same result. But this did mean that I had absolute control of the page contents and could ensure certain elements are displayed correctly if I wanted them to have a unique style or position that Markdown itself wouldn’t produce.

I also realised after the Learning German entry that I could just take the HTML output from the hugo output. Oops.

My goal was to eliminate steps 3 and 4 above. The easiest way to do this is to just eliminate HTML conversion of the entire document and use HTML when needed instead.

This eliminates steps 3 and 4 as well as allowing me to control elements very specifically when needed and keeps the document readable.

So going forward all posts will be created this way unless it isn’t viable for the post type. All previous posts will be converted too. Top level pages AKA “base” pages will still be written in HTML for functional reasons.

Additionally the site will now be rendered using the uglyURLs = true option as I don’t like the look of /blog/post-name/index.html in the file tree.