loading...
Cover image for How I write my blog

How I write my blog

mortoray profile image edA‑qa mort‑ora‑y Originally published at mortoray.com ・6 min read

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.

Screenshot of this article

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.

Posted on by:

mortoray profile

edA‑qa mort‑ora‑y

@mortoray

I'm a creative writer and adventurous programmer. I cook monsters.

Discussion

markdown guide
 

I am currently in the process of trying to learn Jekyll so I can build my blog on my local machine and then push to Github Pages. My initial impression is that I'm not crazy about it. Why does it have to be so hard just to set up a blog using markdown? Sigh.

 

Just start with a free theme from the internet to get up and running quickly (just search "free Jekyll themes"). As time passes, you will find yourself rewriting half the code anyway and adding a heap of stuff.

You can see my blog now vs. the original theme — although I changed a lot behind the scenes SEO and performance-wise as well as the visible changes

 

That looks really good! Are you still on Github Pages using Jekyll? 😄

Pretty much! I'm still using Jekyll, still using the same original theme – although now I've changed so much of it that it's almost completely different! 😅

Now I use Netlify to host my blog (also free), but the code is still taken from the GitHub repository.

That's awesome! Thanks for sharing.

 

Hmm.. Are you trying to change templates and such? If not, Jekyll should not be so difficult to start with one of its many themes :).

The only reason I had chosen Jekyll was github.io. Later, I saw that effort as futile and moved to Hugo and Netlify.

Shameless self-plug: github.com/prashanth1k/levelup-you...

 

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.

One thing I do think Grammarly is great at is removing local jargon from text. A lot of what I write is Pittsburghese which doesn't help globally with people learning proper British English.

For instance, saying something needs fixed vs needs to be fixed. I will never naturally say the to be, but that's proper English.

 

Interesting read. It is pretty much exactly the same as I am doing it :)

  • I wrote my own blogging backend with Django, markdown with extensions for diagrams, tables and pygments for code highlighting. I was actually thinking about adding Latex as well although I don't have that much formulas.
  • I first write in Sublime with awesome Markdown support (through extensions), that paste that to my blog admin.
  • I also let it rest for some time until I proof read again
  • I also published my posts on Reddit and got hated a lot. However, the clicks and views I got was amazing. I had in article on /r/programming that was in the top 3 for half a day and got tens of thousands of view and hundreds of comments. The same article just got a few reactions on dev.to. However, I just love the community here.
 

Certainly Reddit can bring a lot of views. As can a post on the front-page of Hackernews.

For anybody who reads stuff regularly, posting what you like to Reddit, Hackernews, and other places, can help the authors a lot!

 

You use a proportional font and line wrapping for programming? I don't know if I'm impressed or horrified.

 

The line wrapping depends on the code actually. If a project has a lot of API docs I'll have it on to write those docs easily inline. Other code, like the Leaf compiler, it'll tend to remain off.

But yes, I've divorced myself from monospace fonts. I only ever see those ugly things in places here, like this edit box! Why on earth do comment boxes on the web use monospace fonts?