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.
e.g.
// 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 item3. 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")
