How I Write Blog Posts These Days
Tags: writing, editors, markdown, vim
Published: 2019-04-02 23:01:12

---
layout: post
title: "How I Write Blog Posts These Days"
cover_image: https://thepracticaldev.s3.amazonaws.com/i/chnsurf8im7ofmjr5pxi.jpg
tags: 
- writing
- editors
- markdown
- vim
published: true
---

I read

{% link azure/how-i-write-online-articles-1lfb %}

and realised that I was doing things in a sufficiently different way to John to warrant a separate post. So, in some vague order, here's how I write a post for Dev.to and my own blog.

## 1. Editor: Vim

I write my Markdown in Vim. Or Emacs in Evil mode, which is just Vim emulation in Emacs.

Why? Well, I find the manipulation of text - any text - really quick and easy in Vim. Moving paragraphs, changing words, deleting sentences - Vim is aware of the structure of natural language, which makes using it to edit blog posts easy. But that's my experience which is coloured from having used it since the beginning of my career. You either like Vim or you don't - it's really not that important.

Why use Emacs and not just Vim? It just depends on whether I've got a terminal or Emacs open.

## 2. Format: Markdown

Markdown is both wonderful and terrible. Wonderful as it's _everywhere_, is human readable, is human _writable_, and supports the structures you want to use for technical writing - i.e. code blocks. Terrible because there is no standard - the HTML you'll get out of the other end of a parser is not consistent between parsers.

Think this isn't too much trouble? I have to join all the lines in a paragraph to a single line when I'm posting on Dev.to as the Markdown parser treats all the line breaks in a paragraph as hard breaks.[^1]

It's this inconsistency parsers that makes me avoid (or at least not rely on) Markdown linters and previewers. I tend to wait until the post is near finished before I see what it looks like with stage 5 (see below).

Still, the benefits outweigh the drawbacks and so Markdown it is.

### 3. Grammar and Spelling: aspell, style and diction

Markdown posts like this can be sent to [`aspell`](http://aspell.net/), a handy interactive and extensible spellchecker. Good editor integration for aspell exists in both Vim and Emacs.

[`style` and `diction`](https://www.gnu.org/software/diction/diction.html) are a pair of tools that check for grammar mistakes and readability. `diction` picks up on clichés, doubled-words and potential misspellings. It's _sometimes_ wrong but it gets you thinking about whether you could word things better and so makes an excellent starting point.

`style` describes how readable your document is through a series of scores - [Flesch-Kinkaid](https://en.wikipedia.org/wiki/Flesch%E2%80%93Kincaid_readability_tests) for instance. It's interesting information.

### 4. Storage: Public GitHub

I keep my posts [on GitHub](https://github.com/gypsydave5/gypsydave5.github.io).  If someone spots a mistake then at least this way they can open a pull request.

### 5. My Site: Static Site + GitHub Pages

I've been using [GitHub Pages](https://pages.github.com/) to host my blog as a static site since forever. It's an easy enough hosting solution and you can use it with any number of static site generators to turn your Markdown into HTML.

I wrote [my own static site generator](https://github.com/gypsydave5/blawg) because I found every one I tried a little too busy for my liking. It's _still_ too busy for my liking and I reckon it could be scrapped in favour of [Pandoc](https://pandoc.org/) and a few Bash scripts as glue, but it was fun to write. I wouldn't use it if I were you.

There's also some [MathJax](https://www.mathjax.org/) in there for the posts I wrote about [Lambda calculus](http://blog.gypsydave5.com/posts/2017/9/13/lambda-calculus-2---church-numbers/) which is overkill as I'm not a mathematician and it just adds a load of JavaScript to the page. But it's pretty so 🤷‍♀️.

I have a [horrible bash script](https://github.com/gypsydave5/gypsydave5.github.io/blob/source/publish.sh) to publish the blog, and it looks [like this](http://blog.gypsydave5.com/) when it's published:

![my blog](https://thepracticaldev.s3.amazonaws.com/i/nsv8xmr9qd8ay53t098p.png)

I like the colour orange.

### 6. Add to Dev.to: Copy and Paste

Hey, it works.[^2]

### 7. Dev.to Cover Picture: Moses

My personal site has no place for cover images, but Dev.to does and so I feel obliged to put _something_ there.

What I write can come across as an angry old man coming down from a mountain to shout at everyone to stop worshipping false idols,[^3] so a picture of Moses always makes an approprite Dev.to cover image. Usually something involving smashing tablets and looking angry, but this time I've been a bit more peaceful and so it's _The Finding of Moses_ by [Lawrence Alma-Tadema](https://en.wikipedia.org/wiki/Lawrence_Alma-Tadema).


[^1]: Would be annoying if it wasn't for Vim's `vip J`.
[^2]: Also made more exciting by Vim: `:% y +`
[^3]: At least that's what the score from `style` says.