loading...
Cover image for How I Write Blog Posts These Days

How I Write Blog Posts These Days

gypsydave5 profile image David Wickes ・4 min read

I read

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, a handy interactive and extensible spellchecker. Good editor integration for aspell exists in both Vim and Emacs.

style and diction 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 for instance. It's interesting information.

4. Storage: Public GitHub

I keep my posts on GitHub. 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 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 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 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 in there for the posts I wrote about Lambda calculus 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 to publish the blog, and it looks like this when it's published:

my blog

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.


  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. 

Discussion

pic
Editor guide
Collapse
learnbyexample profile image
Sundeep

yay, most of it is similar to my workflow :)

I tried so-simple for GitHub pages, and I am more than okay with it so far

I need to change a few things for front matter (been lazy enough to not automate, maybe someday) between GitHub pages and Dev.to, and I always use preview as sanity check - like have I forgotten some change, rendering (found two bugs so far), etc

will check out style and diction, feels like it will be helpful

Collapse
aspittel profile image
Ali Spittel

This is awesome -- I am installing style and diction right now -- what a cool tool

Collapse
grahamlyons profile image
Graham Lyons

Yeah, I'd never heard of those before but I'll definitely try them out.

Collapse
gypsydave5 profile image
David Wickes Author

Glad you like it Ali!

Collapse
grahamlyons profile image
Graham Lyons

I have a similar workflow. I use Vim almost exclusively but I do switch to VS Code for the Markdown preview - I didn't realise there was no standard for it though.

I often use the spell checking in Vim: :set spell! to toggle on/off. I often have to :h spell to remember all the commands but z= on a word brings up a list of suggestions and ]s moves to the next bad word.

I have written my own site a few times but switched to Jekyll a year or two ago because the less of my own code hanging around doing stuff the better and any features I want are just a Gem away.

Collapse
gypsydave5 profile image
David Wickes Author

I have written my own site a few times but switched to Jekyll a year or two ago

This made me laugh as I switched from Jekyll to writing my own site a year or two ago. I think it was the Liquid tags that did it - found the syntax confusing and occasionally magical.

TBH I still think I could do it all with Pandoc and a few scripts, but I CBA to work it out right now.

I often have to :h spell

Always.

Collapse
nestedsoftware profile image
Nested Software

@mortoray I see that there are several people who may want to use your mdl thing!

Collapse
mortoray profile image
edA‑qa mort‑ora‑y

I'm working on it. It's almost far enough to do all my posts -- exception the latex bits.

Collapse
gypsydave5 profile image
David Wickes Author

Will now have to read your posts about writing a Markdown parser - thanks!

Collapse
micahriggan profile image
Micah Riggan

Very cool! I'm also blogging with vim + github. Made an MR on your githubs for some links on your main readme that weren't working for me

I've been trying out 100% markdown with the github static pages and then copy and pasting to dev.to.

Could you say more about what :%y+ does?

I've been :!pbcopy on my mac to copy out, but I have a feeling your thing does that too, without clearing all the text?

Collapse
gypsydave5 profile image
David Wickes Author

Could you say more about what :%y+ does?

SURE!

  • : - start command mode
  • % - with the whole buffer...
  • y - yank it to...
  • + - the register called +.

The register + is the system clipboard.

Collapse
micahriggan profile image
Micah Riggan

Thanks for the explanation! Registers are on of the vim things I haven't fully incorporated into my workflow

Collapse
drbearhands profile image
DrBearhands

Well you made me feel like a pleb.

Also:

Terrible because there is no standard

Preach!

I'm curious about MathJax, is this the best option for math in your opinion? I'd like to use MathML, but... compatibility. I'm half tempted to just say "fuck chrome and fuck dev.to, I'm using it".

Collapse
gypsydave5 profile image
David Wickes Author

Well you made me feel like a pleb.

Hahaha - I find that hard to believe!

I'm curious about MathJax

Meh. I have no idea if it's the best idea. It got me through the gates and meant that I didn't need to do any further parsing of the Markdown when it compiled to HTML. So a quick fix.

Ideally it should have more processing on the server side so I would like to try MathML myself.

You wouldn't necessarily have to not use dev.to, unless your experience tells you otherwise - the Markdown should support the HTML if it's getting visited in FireFox.

I've given up supporting legacy browsers like Chrome, but I believe there is a plugin to render MathML.

Collapse
drbearhands profile image
DrBearhands

I might be doing something wrong then. There appears to be quite a lot of HTML that dev.to strips from the post (probably for good reason, can't trust everything and it's better to whitelist than blacklist)

Thread Thread
gypsydave5 profile image
David Wickes Author

Hmmm... well having not tried it thus far I'll trust to your report.

Dev.to is open source - perhaps we should take a poke at the codes to see if there's a quick win?

Thread Thread
drbearhands profile image
DrBearhands

EDIT: Never mind, we've been one-upped: github.com/thepracticaldev/dev.to/...