"Markdown recap", a panorama of Markdown's features

tips & tricks
1

Hi there,

I’ve compiled all the Markdown cheatsheets I found online, tested them with Hugo and added output samples for each feature.

See https://roneo.org/markdown

I’m sharing it here as it may help you discover lesser-known tricks, like Image captions for example.

It can also be used to check if a theme properly renders every formatting possibilities offered by Markdown.

Side note: I’m not a native english speaker, I would love to have your feedback also on the phrasing.

Cheers,
Alice - roneo.org/en

2

The “image caption” example is nothing more than an emphasized string following an image. It has no relationship to the image.

3

The “image caption” example is nothing more than an emphasized string following an image. It has no relationship to the image.

Yes, and the only way I found to make it look like a caption is to target it this way:

img + em {
    display: flex;
    justify-content: center;
}

This method is error-prone as this will affect any em element appearing right after an image.

Still, this is a handy way to add information about an image directly in Markdown.

Do you think of a way to improve it?

Should I open an issue on Hugo’s tracker asking to generate an HTML output more appropriated or is it more an issue related to CommonMark specifications?

4

No.

No.

The HTML <img> element does does not have a caption attribute. If you want to structurally associate a caption with an image, use a <figure> element.

You cannot create a <figure> element with markdown syntax, just as you cannot create <audio>, <video>, or <form> elements with markdown syntax. In these cases use HTML within your markdown, either directly or with a shortcode.

5

Thank you for your insights.

One last question though: is it definitively out of the scope of Hugo to automatically generate a <figure> when a caption is present in the Markdown?

6

Yes, it is.

7

Fantastic guide! I learned some things, too. Thanks for putting this together.

One editing suggestion:

Under the Headings section, you say:

You can use until 6 # for different Titles levels

I’d suggest the following edits (in bold):

You can use up to 6 # symbols for the corresponding Heading levels

I’d also suggest that you use the word Heading instead of Title in this section to keep your terminology consistent.

Overall I think your language is very clear and easy to follow. Great job!

8

Hi @stratofax,

thanks a lot for your feedback and your nice words !

I updated the original page to include each of your precious advices.

9
  1. Nested list can also be created indenting each item in the sublist with 1-4 spaces.
  2. A line break can also be added by adding \ and hitting enter key.
  3. Under Headings section, change # Heading 1 to # Heading 2 in the code block
  4. See also Markdown Tutorial - Introduction.