There are some breaking changes for Markdown between Ghost LTS versions and Ghost 1.0 and beyond.

Overview

Ghost 1.0 and onwards uses a fully compliant CommonMark parser/renderer. If you notice any of your content not displaying correctly, ensure any Markdown adheres to the following rules.


HTML inside markdown

If you want to add an HTML block to your markdown content, it's essential that it's surrounded by blank lines.

Before:

some markdown content...
<figure>
<img src="https://example.com/image.png">
</figure>

More markdown content...

After:

some markdown content...

<figure>
<img src="https://example.com/image.png">
</figure>

More markdown content...

Markdown inside HTML

If you want to use Markdown inside of an HTML block it now needs to be separated by blank lines.

Before:

<figure>
![](https://example.com/image.png)
</figure>

After:

<figure>

![](https://example.com/image.png)

</figure>

In Ghost LTS versions, a bug in the Markdown parsing could be exploited to add attributes to links which no longer works. Ensure to use HTML if you want to add attributes that are not supported under the CommonMark spec.

Before:

[an external link](http://example.com" target="_blank")

After:

<a href="http://example.com" target="_blank">an external link</a>

Spaces in URLs

Spaces in link URLs aren’t supported. Use urlencoded links.

Before:

[my file](https://mysite.com/my file.pdf)

After:

[my file](https://mysite.com/my%20file.pdf)

Automatic footnote numbering

Automatic footnote numbering is no longer supported in 1.0. If you have [^n] style footnotes in any of your posts you’ll need to manually update them to be fully identified with a number [^1] or a label [^my-footnote].

Before:

Here is a footnote reference [^n], and another [^n].

[^n]: Here is the first footnote
[^n]: Here is the second footnote

After, highlighting multiple paragraph footnote support:

Here is a footnote reference [^1], and another [^longnote].

[^1]: Here is the footnote.

[^longnote]: Here's one with multiple blocks.

    Subsequent paragraphs are indented to show that they
belong to the previous footnote.