3 October 2019 - 5 minute read

Having a simpler means of creating content for my website has been something of a want for a while now, but I only recently got around to doing something about it. I briefly asked on Mastodon if there was anything that would fit the bill of "MarkDown with macros", but after finding nothing I decided I'd just do it myself.

Introducing MacroDown! MacroDown is a pretty simple MarkDown flavour with basic macro support, along with a very small selection of hard-coded macros for including CSS in the resulting output, setting a page title or favicon, and including the content of other pages.

MacroDown allows basic in-line formatting for things like underlines, bold/italic, and strike through text. Monospaced blocks, and links. It also supports images, tables, code blocks, nestable block quotes, both numbered and bulleted lists, headings, and horizontal rules. Most formatting is done in much the way you'd expect, and the readme on the GitLab page runs through everything.


It was only after my little project was done and I'd ported a lot of this site over to MacroDown that I was told about Hugo, which is designed to do sort of the same thing MacroDown is achieving. I had a look around it and while it does appear to do very much the same thing that I'm achieving, it seems far more geared towards more complicated and bloated up sites. Most "themes" for the site are overflowing with JavaScript, and it seems that support for document-style projects isn't really a thing. It's a website-building tool, where I made MacroDown to be a document-building tool.


You'll also notice the site looks different. This is because of the different structure of the output from MacroDown as opposed to what I was manually putting together before. The general look is much the same, but for instance there are now horizontal rules rather than gaps between blocks of text. Throughout blog posts, places where I used bold text for things like program names or values that you'd normally see highlighted like inline code are now formatted as such.

The biggest change is on the homepage, where I've shrunk the picture at the top to have less padding around it. You'll also notice that if you gradually shrink your browser window, below 700px it will change layout. The main body will fill the display width and the ASCII art changes to a thinner design. The text content on the page will also wrap properly now which should make reading on a mobile browser much more comfortable.

On text-browsers, the appearance will also be quite different. Now that there are no longer the manually-inserted line-breaks in content, it doesn't read wonderfully on wide displays or with high column counts, but on more usual screen sizes it still looks fine.

One thing I'm very happy with is with the ASCII art. In order to make it "responsive", I had to create an empty code block and then set the content with CSS, but the problem then is that it never shows up on text-browsers. The way I solved the problem was to have 2 code blocks. The first has the default content that is shown on text-browsers and is hidden with CSS for everything else, and the second one is empty and has the responsive content set by CSS. As these are the only code blocks on the homepage, I was able to fairly easily target them for styling with a homepage-specific CSS file.

Overall, my new tool combined with some hacky CSS has made writing content for my site much simpler. This is the first post written directly in MacroDown, but just porting other posts over to it, the space savings are very obvious and it's much easier to work with. I've combined MacroDown with a simple bash script that builds each markdown file in my project tree to HTML, then copies them into a separate tree for the actual site content. It then goes over each markdown file and picks out some strategically placed content to use to even generate the XML for my RSS feed.

MacroDown is free and open source software, so anyone and everyone is welcome to give it a try, contribute bug fixes or suggest new features, and hopefully help turn it into a nice little document-building tool!


Meta - Programming


Copyright Oliver Ayre 2019. Site licensed under the GNU Affero General Public Licence version 3 (AGPLv3).