How To Write Markdown

Jul 24, 2022 | O. Wolfson
html markdown

Markdown improves your content creation experience. (The Soi Dev)

Markdown is a plain text formatting syntax. Markdown allows you to write text formatting syntax directly into your documents, without lifting your fingers from the keyboard. Markdown is fast, simple, and easy on the eyes. You can write plain text Markdown documents in any text editor.

From Markdown to HTML

Writing HTML code around your content can be cumbersome. A better solution is to use Markdown. Markdown syntax can 'processed' and converted to HTML, which can be interpreted by a web browser. This blog is written in Markdown (which is interpreted by a node js Markdown processor). If I were to write the word **wolf** here, surrounded by double asterisk symbols, the result would be: wolf in bold text. This is much faster than writing the HTML code <strong>wolf</strong>, or reaching for a mouse, highlighting text and tapping on a bold text formatting button.

Markdown syntax

Some examples of Markdown syntax are as follows:

Headers

# H1
## H2
### H3

H1

H2

H3

Code blocks

```HTML
<div>some HTML code</div>
```

<div>some HTML code</div>

Links

[owolf.com](http://owolf.com)

owolf.com

More

For more syntax examples, here is a Markdown cheatsheet, and another. And one more.

Markdown Preview and Processing

Try Markdown at this online editor: https://dillinger.io/.

There are many tools you can use for Markdown processing, including online editors, ide extensions, cms plugins, and browser extensions. I am using a Markdown package for this blog. Which tool you need depends on your target output format. Depending on the processor that you are using, results may vary slightly.

Markdown in Action

Here is a sample of markdown syntax used to format a pancake recipe.

# American Pancakes
Originally from the [BBC](bbc.co.uk).

Makes: 5 large / 10 mini

## Ingredients

- 135g plain flour
- 1 tsp baking powder
- ½ tsp salt
- 2 tbsp caster sugar
- 140ml milk (cow, soy, almond, whatever)
- 1 large egg, lightly beaten
- 60g melted butter (allowed to cool slightly) or vegetable oil, plus extra for cooking

## Method

1. Sift the flour, baking powder, salt and caster sugar into a large bowl. In a separate bowl or jug, lightly whisk together the milk and egg, then whisk in the melted butter.
2. Pour the milk mixture into the flour mixture and, using a fork, beat until you have a smooth batter. Any lumps will soon disappear with a little mixing. Let the batter stand for a few minutes.
3. Heat a non-stick frying pan over a medium heat and add a knob of butter. When it's melted, wipe with a paper towel to remove the bubbles and add a ladle of batter. It will seem very thick but this is how it should be. Wait until the top of the pancake begins to bubble, then turn it over and cook until both sides are golden brown and the pancake has risen to about 1cm (½in) thick.
4. Repeat until all the batter is used up. You can keep the pancakes warm in a low oven, but they taste best fresh out the pan.
5. Serve with lashings of real maple syrup and extra butter, if you like.

The pancake recipe, as processed from this Markdown document into HTML and rendered by the browser, below:


American Pancakes

Originally from BBC.

Makes: 5 large / 10 mini

Ingredients

  • 135g plain flour
  • 1 tsp baking powder
  • ½ tsp salt
  • 2 tbsp caster sugar
  • 140ml milk (cow, soy, almond, whatever)
  • 1 large egg, lightly beaten
  • 60g melted butter (allowed to cool slightly) or vegetable oil, plus extra for cooking

Method

  1. Sift the flour, baking powder, salt and caster sugar into a large bowl. In a separate bowl or jug, lightly whisk together the milk and egg, then whisk in the melted butter.
  2. Pour the milk mixture into the flour mixture and, using a fork, beat until you have a smooth batter. Any lumps will soon disappear with a little mixing. Let the batter stand for a few minutes.
  3. Heat a non-stick frying pan over a medium heat and add a knob of butter. When it's melted, wipe with a paper towel to remove the bubbles and add a ladle of batter. It will seem very thick but this is how it should be. Wait until the top of the pancake begins to bubble, then turn it over and cook until both sides are golden brown and the pancake has risen to about 1cm (½in) thick.
  4. Repeat until all the batter is used up. You can keep the pancakes warm in a low oven, but they taste best fresh out the pan.
  5. Serve with lashings of real maple syrup and extra butter, if you like.

Pancake recipe doc from Alan Orth

Conclusion

Give Markdown a try if you are interested in improving your content creation experience.