Format

A markdown link’s format is:

[Link text](target)

The link text is what will be shown on error or while the image is loading. It can also help with SEO. It can be left blank.

The target should be either a local file path in the repo, or a remote URL. The target should not be blank, otherwise it will just link to the current page.

File

The path is by default relative to the current path.

[link text](bar.txt) - File name.

[link text](./bar.txt) - Equivalent to the above, but more verbose, so not common.

[link text](foo/bar.txt) - Path to file.

You can ascend in the directory, using the double dots.

[link text](../fizz/buzz.txt)

Use a forward slash to indicate a path relative to the root, ignoring the current path.

[link text](/app/file.txt)

Use an encoded space as %20 to escape a space in a path, to avoid an error in rendering markdown. Using a backspace in front of a space does not work.

[link text](/Foo%20Bar/baz.txt)

Additionally, you can use IDs in your target to you can jump to an element with that ID, typically a heading.

## My first heading

Content

## My second heading

More content.

Click to go to [My first heading](#my-first-heading).

The target could go to another page.

[Foo bar](foo#bar)

[Foo bar](https://example.com#bar)

URL

Set the target as a full URL, requiring protocol, domain and optional path.

[link text](https://example.com/foo/bar)

Regarding protocol - the URL must start with http or https, otherwise the link will in invalid.

For example, this will link add /example.com to the current path.

[Bad example](example.com)

Add optional alternative text. You can hover over the link to see the alt text.

Code:

[link text](https://example.com "alt text")

Result:

link text

Use text or a number or reference a link in the next paragraph or at the end of the page.

This helps keep use of links within paragraphs very readable, as you are able to as alias/shortcut to the full link and reuse it across a page.

The full link will not be visible.

Text alias

Use arbitrary case-insensitive reference text in target.

And case-sensitive link alias in the link and in the reference. You might prefer dashes and lowercase for predictabilty. The alias is not seen by the end-user.

Code:

Here is my [Homepage][MichaelCurrin home]

I'm using another link to my site [here][MichaelCurrin home] in case you missed it.

[MichaelCurrin home]: https://michaelcurrin.github.io/

Result:

Here is my Homepage

I’m using another link to my site here in case you missed it.

Use can use number aliases for your links.

Example:

Code:

Here is my [Homepage][1] with a numbered reference.

[1]: https://michaelcurrin.github.io/

Result:

Here is my Homepage with a numbered reference.

Link text

Similar to Text alias but using hard brackets with no text. Or not using hard brackets at all. This then takes on the alias from the link text.

Using hard brackets.

Code:

Here is my [Homepage][].

And here is my [Homepage][] again.

[Homepage]: https://michaelcurrin.github.io/

Result:

Here is my Homepage.

And here is my Homepage again.

Leave out hard brackets.

Code:

Here is my [Homepage].

And here is my [Homepage] again.

[Homepage]: https://michaelcurrin.github.io/

Result:

Here is my Homepage.

And here is my Homepage again.

[<img src="abc.png" width="100px"/>](https://example.com)

Or

[<img src="abc.png" width="100px"/>][hello-world]

[hello-world]: https://example.com