Elements

Links can be added to a markdown file by using the following syntax:

[Link text](http://example.com)

There are also simple links where the URL is used as the link text, these are called autolinks

<http://example.com>

If the link contains spaces, it must be enclosed in angle brackets:

[Link text](<some link with spaces>)

We can also create local links to headings in the same document:

[Link text](#<heading>)

Here, <heading> is the heading text

  • in lowercase,
  • with spaces replaced by hyphens,
  • with all special characters removed,
  • two or more hyphens are replaced by one hyphen,
  • and, in case of a heading with the same text, a number is added at the end.

Images

Images can be added to a markdown file by using the following syntax:

![Alt text](/path/to/image.png)

Standardization

The only standard for markdown is the CommonMark specification. However, this specification was created ten years after the original markdown was introduced and therefore there are many implementations of markdown does not follow the CommonMark specification. The following implementations follow the CommonMark specification:

The following implementations do not follow the CommonMark specification:

Linter

There is a linter for markdown available also as a VSCode extension.

The linter can be configured:

  • in the .markdownlint.jsonc or markdownlint.yaml file in the root of the project
  • a file with the same name in the home directory
  • in the settings of the VSCode extension (markdownlint.config)

By default, the linter will check more than 50 rules. Not all of them are based on the CommonMark specification and therefore it may be useful to disable some of them. We can do this by adding the following to the configuration file:

{
    "MD013": false
}

Handling of special characters

To use backticks (`) in code, use double backticks:

``code with `backticks` inside``