• #blog
• #markdown

Introduction to markdown

Creating text-based content for the web is an absolute breeze when using markdown. A markdown files is saved with a .md or .mdx file extension. Let’s have a look at the syntax.

Headings and sub-headings

It is good SEO practice to use a main heading with sub-headings. In markdown we do so using the money (or hashtag) symbol. In web terms there are 5 sub-heading levels available.

# Heading 1
## Heading 2
### Heading 3
#### Heading 4
##### Heading 5
###### Heading 6

This markdown results in the following:

Heading 1

Heading 2

Heading 3

Heading 4

Heading 5

Heading 6

↑ Back to links

Paragraphs

Paragraphs are written without any fancy markdown symbols. Paragaphs are seperated by a blank line.

This is the first paragraph written with no symbology.

Here is the second paragraph.

The result is:

This is the first paragraph written with no symbology.

Here is the second paragraph.

If no blank line is used, let’s see what happens.

the sly fox jumped over 
the lazy dog

the sly fox jumped over the lazy dog

↑ Back to links

Bold, italics and strikethrough

For bold double asterix is used and italics is created by single underline.

We can style text with **bold**, _italics_, ~~strikethrough~~ and ==highlight==. 

All this symbology results in:

We can style text with bold, italics, strikethrough and ==highlight==.

Hang on, something is wrong. The highlight markdown has not worked as expected. Let’s try using the HTML mark tag instead.

<mark>highlight</mark>

That works :)

↑ Back to links

Superscript and subscript

Here is the markdown for superscript and subscript:

<sup>superscript</sup> Hello world <sub>subscript</sub>

I haven’t found any markdown for superscript and subscript so using the sup and sub HTML tags will have to suffice.

^superscript Hello world _subscript

↑ Back to links

Horizontal line

The line above is simple created with three dashes.

---

Resulting in this:

↑ Back to links

Lists

An unordered list is created with dashes.

- First
- Second
- Third

Looks like this:

• First
• Second
• Third

An ordered list is created with numbers followed by a dot.

1. First
2. Second
3. Third

Resulting in this:

1. First
2. Second
3. Third

↑ Back to links

Nested lists

You might want a nested list. Use the tab key in your markdown.

- Sparrow
  - House
  - Hedge
- Tit
  - Blue
  - Coal
  - Crested
  - Great
  - Long-tailed

Of course, the styling of the list items can be achieved with Cascading Style Sheets (CSS). This is default styling:

• Sparrow
  • House
  • Hedge
• Tit
  • Blue
  • Coal
  • Crested
  • Great
  • Long-tailed

↑ Back to links

Image

The markdown for an image needs the file source and alternate text.

![A bored fish](/images/bored-fish_4.png)

And this little markdown snippet results in this:

↑ Back to links

Link

For a link, use the same syntax as the image but drop the exclamation mark.

[Awesome web developer](https://www.miketoft.com)

The link looks like this:

Awesome web developer

Internal links on an Astro blog need to include the folder name and do not include the file name extension, like so:

[Rethinking 2048](/posts/rethinking-2048)

↑ Back to links

Unlinked link

But if you just want the URL to be shown, use backticks

`https://www.miketoft.com`

https://www.miketoft.com

or single quotes

'https://www.miketoft.com'

’https://www.miketoft.com’

↑ Back to links

On-page link

[Headings on this page](#headings)

In this Astro blog the markdown above caused the website to crash.

If you are using markdown in an Astro blog, try the folllowing. Add links where you want the links to go to.

<a name="linkToHeadings"></a>

Then add the following link:

[↑ link to headings](#linkToHeadings)

It will look like this:

↑ link to headings

↑ Back to links

Footnote

I left this to the bottom of the page so you can see the footnote below. Here is the markdown for a footnote.

I am creating a nice little footnote [^1]
[^1]: This is the footnote for you to admire.

I am creating a nice little footnote ¹

Notice how a footnotes section has been generated automatically at the bottom of the webpage. The number of the footnote links to the note at the bottom of the page where a return arrow is linked back directly to the footnote.²

↑ Back to links

Table

| table heading | table heading | table heading |
| :--- | :---: | ---: |
| table data | table data | table data |
| left aligned | center aligned | right aligned |

Obviously the table would need to be styled with CSS, but without styling the resultant table looks likes this:

↑ Back to links

Blockquote

This is a blockquote. It needs to be styled with CSS!

↑ Back to links

Thank you for stumbling across this website and for reading my blog post entitled Writing content with Markdown.