3 markdown editing tips I wish I knew when I started blogging

Published on June 24, 2021

Tagged: #developer-experience

Follow me on twitter for more posts like this

I write markdown documentation everyday. I use it for documentation at work and I use it for my blog. I love the simplicity of it.

Over the years I’ve learned theses tips and I wish I knew them when I started.

1. draw.io vscode and the .svg format

If you need to create a diagram for your document you should consider draw.io. There is a drawio plugin for vscode that makes it easy to diagram directly in the vscode UI.

After you install the plugin you can just create a new file with a .drawio extension and start drawing. To import a drawio diagram into a markdown document you have to export the diagram to a format that can be used in documents like png.

My tip here is to use the .drawio.svg format instead of .drawio so most markdown viewing tools can read the diagram directly off your diagram. This is really great for GitHub documentation.

So to use, create a new drawio diagram file and add svg at the end. e.g. File > new > myDiagram.drawio.svg.

Then you can reference this in your markdown directly ![My diagram]("./myDiagram.drawio.svg").

2. You don’t have to number your sequential lists properly

If you are creating an ordered list you DON’T have to order it. You can just use 1. for all elements and markdown will figure out the order.

Not specifying the order makes it much easier to change the contents of the list later.


// this is GOOD - markdown will figure out the order when this is viewed.
1. list item
1. list item
1. list item

// this is BAD - we deleted one and broke the order
1. list item
2. list item
4. list item

3. Square peg in a round hole

I always forget the order of the brackets to describe a link or an image in markdown.

An easy way to remember is “square peg in a round hole” - square brackets always come first.

// for an image
![My image]("./this-is-an-image.png")

// for a link
[This is my link]("https://thisismyurl.com")
Darragh ORiordan

Hi! I'm Darragh ORiordan.

I live and work in Sydney, Australia enjoying the mountains and the ocean.

I build and support happy teams that create high quality software for the web.

Contact me on Twitter!

Read more articles like this one...

List of article summaries


Modern shell tooling for devs on MacOS and Windows WSL

Many of the terminal tools that come with unix environments like MacOS and Windows WSL are functionally similar to how they were 20 years ago. But developer tooling has advanced quite a bit since then.

You can replace many of these cli tools with equivalents that support full colour, unicode icons, git and more. Changing OS and git defaults will better match your workflow.

Your prompt can be made git aware and use colour to indicate state so you don’t have to query git so often.

I work on MacOS and Windows machines and I’ll show you how to have the same terminal and experience on both.


How engineers can help deliver software effectively

Delivery managers and team leads have the responsibility to deliver a software system via an engineering team.

Your customer wants every feature to work perfectly and they want it delivered yesterday. Your team wants to learn and grow.

It’s a tough role managing all the stakeholders and creators in a project.

Engineers can help drive great delivery by empathising with and supporting the delivery manager or leads in a project team.


How to identify a great tech organisation before you join

No one wants to waste time working for an organisation that’s a bad fit. But how do you know a good place from a bad place until you actually work there?

It’s important to spend the same amount of time analysing a potential organisation as they spend analysing you!

During an interview process an organisation has personality testing, resumes, tech testing, behavioural testing, reference checks, bank checks, police checks and more.

If it sounds like a very one-sided process that’s because it is! But there are ways you can bring more balance and here are some important things to research before accepting any engineering job offer.


Set vscode as the default for text files on mac

How to set the default text editor to be visual studio code on the mac

Update 29 Jan 2022 - I added this and more to comprehensive instructions for configuring a modern developer shell and MAcOS in another article here. You should check that out.