How I write my blog

In a distant memory I typed some text, pressed "Submit", and had a blog post. Though simple, it lacked finesse; the articles lacked polish. With each article, I'd tweak my process, my site, and my tools. Let me give you an overview of how this looks now, from ideas, through markdown and HTML, to publishing and promotion.

If you don't care too much for technical details scroll down to "Proofreading" or "Publishing".

Topic and text

Coming up with a topic is kind of like plucking feathers from a deranged chicken: so much to choose from, some easy to catch, others elusive, some pretty and others ugly. A blend of what I want to write, what I'm motivated to write, and what I think people are interested in reading, the choice is never clear. Let's just assume topics bubble up magically from the quagmire.

By comparison, the writing process itself is surprisingly simple: a plain text editor, Kate with markdown. I don't want to be distracted by formatting; a text editor lets me immediately start, jump around the doc, and make changes with ease.

Like with coding, I use a proportional font and enable line wrapping.

I won't talk much about style here. I have a mental style guide that my fingers sometimes obey, but I'm prone to experiment and try new things. Given the lack of awards hanging on my walls, we can also safely assume I'm doing nothing spectacular in this area.

Markdown formatting

I chose markdown as it impacts the text minimally. It's low overhead and has limited syntactic cruft. It doesn't, however, provide much in the way of formatting.

When I started I did not use markdown. I think I just wrote text files than formatted them in the online editor. It undoubtedly wasn't good as my brain has nearly erased those memories.

I use a customized markdown processor to change my text into HTML code, which Wordpress, my primary platform, accepts. The processor is written in Python with the markdown library. It's not really a pleasant module; it's hard to change formatting and doesn't handle extensions well. I put up with it as an acceptable solution for now.

Let's look at some of the extensions I use.

Latex

$`a + b`

Many of my articles use formulas and benefit from proper mathematical formatting. As much as I think Latex is an awful language, it has support for any equation I might need. The dollar+backtick extension lets me inline latex.

For testing, my processor will create the PNG files using a sequence of texi2dvi, dvips and convert. It lets me view the pages locally with the equations. When exporting to HTML, it uses the WordPress inline latex notation.

Before I change my site appearance again I'll need to handle the Latex myself on Wordpress. The themes offered do a terrible job of getting it right. I was forced to abandon a previous theme change quickly as none of my latex stuff formatted correctly. Doing the equation images myself though requires going through all old articles and updating them!

MyFencedCode

I didn't like the formatting of the default code blocks. It didn't offer any way to modify it; I copied the code and made changes to produce different formatting suitable for my site. I modified both the generated HTML structure and options passed to the codehilite extension.

As I share this generator with the Leaf site, I also added an option to make Leaf the default language.

I have a pygments formatter for Leaf. This fits into the normal toolchain for syntax highlighting.

Center and Blurb

For images, I have a >> processor that centers the paragraph. I used to use it for the latex formulas, but since changed it to auto-center them on their own. Now I should use it for images, but I tend to insert those in the visual editor later in WordPress. I'm planning on doing this "correctly" now by uploading first and adding an image link in markdown.

The final promotional blurb in each article is a >B> block, which creates an aside tag in HTML. If you're reading this article on another site, like dev.to you might not see these; I sometimes remove blurbs when cross-posting.

Proofreading

After writing an article, I let it sit for a day. Then I reread it with a fresher mind, giving me a chance to fix sentence structure or reconsider the importance of paragraphs.

Not being a fan of filler, I remove as much information as possible. Doing so results in shorter articles than one might find in a book, or in other technical references, but are quicker to read. I know in some cases this makes a trade-off, increasing the detail density and complexity. If something needs additional explanation, I may expand on a second article -- often published first, so I have a linkable reference.

Prior to publishing I paste my text to Grammarly. It gives a lot of bogus suggestions, but does find many common mistakes that my brain otherwise ignores.

Long ago I had a friend edit my articles, but it was too much of a time commitment. I would like to have a human editor again.

Publishing

After proofreading, I do a visual check locally. As mentioned, the markdown processor can produce a local test. It changes a few items, but also adds the CSS to the generated HTML (the same CSS I use on the website). I can open this file locally and get a good approximation of how it will look on mortoray.com.

If it's too much like a wall of text, I'll find ways to make it more approachable, such as section breaks, asides, or occasionally an image.

Now is also the time to right-click all links to make sure they're correct.

Once ready I generate the final HTML code. I view this once again Firefox to make sure it works -- because the previous file is already there, I just need to reload. I press Ctrl+U to view the source, copy, and paste into WordPress.

Some finagling with the details now: move the title into the special field, pick a category, add some tags, choose the social media blurb (to which I add hashtags). A featured image is also required; I tend to look at pixabay for these.

Press "Publish" and done...

Cross-Posting

Alas, my site is not a household name (yet), and despite having a decent number of followers, posting only to my site and social feeds doesn't give my articles a lot of attention. It could, and sometimes I fair well, but there's a vast amount of luck involved here. I've been meaning to write an article about the Internet Lottery at some point.

My reads are increased by cross-posting. Where I post changes over time; I'm continually watching out for quality opportunities. I don't want to spam everywhere, nor do I want low-return (it takes effort).

Currently, I post nearly all of my articles to dev.to. I use the markdown source, but need to make some changes. If there are too many equations, I may not cross-post, as it involves too much manual work of grabbing image links from my site. Had I already switched to producing my own latex images this wouldn't be a problem.

Many of my articles also make it to Medium. They have an import functionality, but it's terrible for source code. I won't publish any code-heavy articles there.

I publish a few articles on CodeMentor to help bolster my profile there. I suppose taking on some students would probably help more.

I used to post links to Reddit, but the lottery effect and title-bias are quite pronounced there. Moreso, it's easy to get yourself banned, blacklisted, or otherwise hated. I now hope other people do the posting for me -- though at one point I saw my domain itself got blacklisted from some subreddits, even if I wasn't self-promoting!

Shiny new egg

At the end of it all is an article. Perhaps it sounds like a lot of effort for relatively few words, but as long as people read and enjoy it, I think its worth it.

And if you're thinking of starting a blog, I suggest keeping it simple at first. I didn't sit down and create my tools all at once, decide on my style overnight, or tackle every technical detail immediately. As with all things, this is an evolving work in progress. Chances are I'll change something before I even press "Submit" on this article.

If you enjoy my writing then follow me on Twitter or Facebook, or to keep me going, become a patron. Thank you for reading.