Skip to main content

Using Markdown

To quote Markdownguide.org:

Markdown is a lightweight markup language that you can use to add formatting elements to plaintext text documents.

Why Markdown?​

Because:

  • At The New Institute, we constantly create textual, formatted content;
  • We need to collaborate on this content, ranging from strategic planning documents to publishable articles and newsletters;
  • This content needs to be formatted and structured, with headings, italics / emphasis, ordered lists, links, headings and more;
  • But this formatting needs to be context agnostic – because the content will eventually be transferred to and published in different environments than the one it is being originally drafted;

Ideally, you should be able to write formatted content that you can copy & paste elsewhere, effortlessly, while retaining formatting. That is what Markdown does.

If you write This text has *emphasis* and contains a [link](https://example.com), it will render like this:

This text has emphasis and contains a link

And it will do so in Microsoft Teams, on a Trello card, and also on this documentation website. This means I can write content on a Trello card and re-use it on this website. And because the source material is written in plaintext, it is easily convertible to HTML.

Note: there are some differences in how italics and bold are handled. Single asterisks (like *this*) are sometimes make text italicised, sometimes bold, like Microsoft Teams: