Why Markdown
Over the years of being technologist, I have come across many commonalities when working at companies we will call these Rules of Wisdom
One such Rule is documentation comes last always last, this is usually not by design but by the pressures placed onto the few that have the knowledge be it technical ability or tribal knowledge, making these few time under great demand, this causes them to drop the vital but time-consuming task of documentation other reasons that can cause this do exist and we are all human we are programmed to do the bare minimal be as efficient as possible.
This leads me to Markdown what is Markdown wiki says “Markdown is a lightweight markup language with plain-text-formatting syntax” put a bit more plainly it standardises the format of documentation this is brilliant you don’t have to mess with formating ever again… but at what cost the cost is learning some syntax to do the formatting for you.
How to get started with markdown.
The easiest way to get started with markdown is to install a text editor (visual studio code is a good chose) that can support markdown, take a copy of the cheat sheet Done…
How to install visual studio code and markdown extensions
Download visual studio code https://code.visualstudio.com/
Run the installer READ the license click Next>Next>Next>Next>Install>Finish
launch the program don’t be scared goto View>Extentions or press Ctrl+Shift+X
You should be able to now search for a Markdown Extension the one i have used and sometimes still use is Markdown all in One
Also grab a spell check when your in the market place if you anything like me you will need one.
So let’s get started with our first markdown document click File>New File or Ctrl+N we should now have a new tab called Untitled-1
With Visual studio code as it supports multiple syntaxes, you have to tell it which one you are going to use you have guessed it… we need to tell it to use markdown to do this at the bottom right of the screen you can change the input language from plain text to markdown or press Ctrl+K then M
now you can start using markdown to create documents there is also a preview button which will show you what it looks like
I hope the above gets you started with using markdown by yourself but has some drawbacks like where to store the docs how to share can you do collaborative docs etc.
CodiMD
This then leads me to a more fun way of using markdown with a platform that stores it and can allow multiple people to use it without end-users having to install a text editor and set it up, this magical land is called codimd link to codimd post here linktobeadded
so we need codimd but how? our old friend docker comes into play, all you need is a docker host linktobeadded to post and then use docker-compose with a docker-compose.yml configuration file and you are there up and running.