Underutilized Markdown Syntax
Half of Being a Great Engineer is Quality Documentation
The ability to convey your thought process, assumptions, approach, and solution to a given problem is a fundamental skill in engineering. There are numerous tools available for documentation but one used often in the world of software engineering is Markdown. Markdown is a lightweight markup language for creating formatted text using a plain-text editor. Unlike other popular markup languages such as HTML, Markdown is designed to be easily human readable. I find myself using Markdown on a daily basis via Github for pull requests, comments, READMEs, etc and I have found the following syntax useful. Note that I will not be covering basic Markdown syntax.
Code
As a software engineer it's obvious that I want communicated code. Most people know how to use use inline code via a single backtick ` or code blocks via code fencing with three backticks ``` but most people do not know that code fencing also supports syntax highlight. This can be done for most languages by simply adding the name of language at the beginning of the code fence as shown in Figure 1.
Tables
Tables are often the best way to display some datasets and can easily be formatted in Markdown using the pipe | followed by at least three hyphens on the following line ---. This specifies the headers of your table and data rows can be add using more pipes |. Another neat trick is that you can change the justification of each column by adding colons : to the three hyphens --- as seen in Figure 2.
Footnotes
I almost never see footnotes but Markdown makes them really easy. To insert them all you have to do is put in a carrot in some square brackets [^]with a footnote identifier such as x. Markdown will gather all the footnotes to the bottom of the document and put links between them on the page. Also the footnotes are numbered automatically in the order they appear so the identifier can be anything.
Additional Resources
- Documentation on all vanilla Markdown Syntax via the Markdown Guide.
- All the screenshots in this article were pulled from the Markdown playground Markdown-it.
- Github has its own flavor of Markdown that make linking pull requests, issues, and mentioning teammates easy. See Github Markdown documentation for details.
