Markdown Blogging with Git + Vim + Hercule

I've been enjoying some posts on dev.to about blogging style, so I wanted to briefly write about my dead simple setup that vibes with my coding style.

Dev style

I've a big fan of vim+tmux. I like being able to quickly open terminals, jumping from editor panes to terminal panes and running snippets of code to test them.

I've been a vim person for 3 years now, so that feels like home. I like the splitting, jumping from tab to tab, file to file, buffer to buffer. It feels simple and snappy.

That's how I want blogging to feel, simple, and snappy. This approach is new, and will probably evolve a good bit, but I like it so far.

Blog Goals

• Simplicity - I should be able to write a post quickly and have it online without doing very much
• Code friendly - I should be able to write technical posts, and run the snippets in my post, so I can be sure they work

Simplicity

My posts are all written as Readme files as markdown, and pushed to my blog repo on github.

When I have post ideas, I create a folder in my todo folder.

If I want that folder to be committed, I'll create a template.md file. More on that later

Deploying is as simple as a git push since I'm using github static pages.

Code Friendly

I want to blog about code, and I don't want to have to copy and paste updates into my posts as I refine the code.

After searching for a bit, I found out you can transclude markdown files with a tool called hercule

Transcluding is like linking, but it takes the contents of a file, and puts it where the link was.

So I can write

    javascript
    : [an example of transcluding] (example.js)

and the contents of example.js will be put inside the javascript code block.

which looks like

console.log('this file was transcluded!');

If this is unclear, feel free to checkout the template.md for this post

Make tools for yourself

So with this in mind, I wrote a quick little script that uses hercule to automatically transclude a file named template.md into a new file named Readme.md

To run this I just type gen readme

So now I can use test snippets, and then transclude them into my Readme file all from the terminal

This testing phase tends to look like the following.

Wrapping it all up

Using hercule is awesome, because now I can break my post into multiple files, and then recombine them.

One interesting usecase I've found for this, is breaking the header into it's own file, and then using it again in my toplevel readme.

Once I've finished my post, I move the folder up a directory, and add a reference to it in the top level template.md file

which looks like

This makes it pretty easy to maintain an index of my posts, with little summaries, which update when I change the corresponding file

Posting to dev.to

After pushing everything up to github, I copy the markdown, and find all relative links, and replace them with absolute links to the github repo.

Now all my pictures and links should work.

Conclusion

You can use hercule to turn your files into components, which can be imported into multiple markdown files. This allows you to write tests against examples, and have your blog posts update as you change source files.