Hi there! Internet Explorer is no longer supported.

Please use a modern web browser such as Firefox, Chromium or Edge. Thank you!

Markdown Syntax Guide

Sample article showcasing basic Markdown syntax and formatting.

1076 Wörter6 Minuten
Hinweis

Diese Seite wurde noch nicht übersetzt, daher wird stattdessen die englische Version verwendet. Möchtest du mithelfen? Mitwirken

Hugo supports Markdown syntax for formatting text, creating lists, and more.

This article offers a sample of basic Markdown syntax that can be used in Hugo content files and its rendered output with the current theme.

Headings

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

### Heading with custom style {style="color: purple; background: coral; padding: 0.5rem; border-radius: var(--radius);"}

### Heading with a custom id {#custom-id}

How it renders:

Heading 1

Heading 2

Heading 3

Heading 4

Heading 5
Heading 6

Heading with custom style

Heading with a custom id

Emphasis

Markdown
*This text will be italic*
_This will also be italic_

**This text will be bold**
__This will also be bold__

_You **can** combine them_

How it renders:

This text will be italic

This will also be italic

This text will be bold

This will also be bold

You can combine them

Lists

Unordered

Markdown
- Item 1
- Item 2
  - Item 2a
  - Item 2b

How it renders:

Ordered

Markdown
1. Item 1
2. Item 2
3. Item 3
   1. Item 3a
   2. Item 3b

How it renders:

  1. Item 1
  2. Item 2
  3. Item 3
    1. Item 3a
    2. Item 3b

Task list

Markdown
- [x] Write documentation
- [ ] Review code
- [ ] Deploy changes

How it renders:

Definition list

Markdown
First Term
: This is the definition of the first term.

Second Term
: This is the definition of the second term.

How it renders:

First Term
Lorem est tota propiore conpellat pectoribus de pectora summo. Redit teque digerit hominumque toris verebor lumina non cervice subde tollit usus habet Arctonque, furores quas nec ferunt. Quoque montibus nunc caluere tempus inhospita parcite confusaque translucet patri vestro qui optatis lumine cognoscere flos nubis! Fronde ipsamque patulos Dryopen deorum.
Second Term
This is the definition of the second term.

Images

Markdown
![](FreeCAD-symbol.png)

How it renders:

With caption:

Markdown
![Alternative text](PartDesign.webp "Caption text")

How it renders:

Caption text

For more advanced functionality, use Hugo’s built-in Figure shortcode.

Markdown
[Hugo](https://gohugo.io)

[News Section](/news)

[Heading ID](#custom-id)

How it renders:

Hugo

News Section NewsBrowse the latest news

Heading ID

Styling Text

Style Syntax Example output
Bold **bold** Some bold text
Italic *italic* Some italic text
Mark ==mark== Some marked text.
Deleted ~~deleted~~ Some deleted text
Inserted ++inserted++ Some inserted text
Subscript ~subscript~ Some subscript text.
Superscript ^superscript^ Some superscript text.

Blockquotes

Markdown
> As Newton said:
>
> If I have seen further it is by standing on the shoulders of Giants.

How it renders:

Quote

As Newton said:

If I have seen further it is by standing on the shoulders of Giants.

Blockquote with attribution

Markdown
> Don't communicate by sharing memory, share memory by communicating.
> — <cite>Rob Pike[^1]</cite>

[^1]: The above quote is excerpted from Rob Pike's [talk](https://www.youtube.com/watch?v=PAAkCSZUG1c) during Gopherfest, November 18, 2015.
Markdown
> Programs must be written for people to read, and only incidentally for machines to execute.
{cite="https://web.mit.edu/6.001/6.037/sicp.pdf" caption="**Harold Abelson & Gerald Jay Sussman**, *Structure and Interpretation of Computer Programs*"}

How it renders:

Quote

Don’t communicate by sharing memory, share memory by communicating.

— Rob Pike1

Quote

Programs must be written for people to read, and only incidentally for machines to execute.

Harold Abelson & Gerald Jay Sussman, Structure and Interpretation of Computer Programs

Inline Code

Markdown
Inline `code` has `back-ticks around` it.

How it renders:

Inline code has back-ticks around it.

Code Blocks

Hugo uses Chroma, a general purpose syntax highlighter in Go.

Language Syntax Highlighting

To set the language, add the language short name after the backticks:

Markdown
```python
def hello():
    print("Hello World!")
```
Markdown
```go
func main() {
    fmt.Println("Hello World!")
}
```

How it renders:

def hello():
    print("Hello World!")
func main() {
    fmt.Println("Hello World!")
}

For a list of supported languages and the names to use, please see the Chroma documentation.

Line numbers

To set line numbers, set the linenos attribute to table and optionally set linenostart to the starting line number:

Markdown
```python {linenos=inline,linenostart=42}
def hello():
    print("Hello World!")
```
Markdown
```html {linenos=inline}
<!DOCTYPE html>
<html lang="en">
    <head>
        <meta charset="utf-8" />
        <title>Example HTML5 Document</title>
        <meta name="description" content="Basic Markdown syntax.">
    </head>
    <body>
        <p>Test</p>
    </body>
</html>
```

How it renders:

42def hello():
43    print("Hello World!")
 1<!DOCTYPE html>
 2<html lang="en">
 3    <head>
 4        <meta charset="utf-8" />
 5        <title>Example HTML5 Document</title>
 6        <meta name="description" content="Basic Markdown syntax.">
 7    </head>
 8    <body>
 9        <p>Test</p>
10    </body>
11</html>

Filename

To add a filename, an url or title to the code block, set the file attribute:

Markdown
```python {file="hello.py"}
def hello():
    print("Hello World!")
```

How it renders:

hello.py
def hello():
    print("Hello World!")

Highlighting Lines

To highlight lines, set the hl_lines attribute to a list of line numbers:

Markdown
```python {linenos=inline,linenostart=1,hl_lines=[2,"4-5"],file="hello.py"}
def hello():
    print("Hello World!")

def main():
    hello()
```

How it renders:

hello.py
1def hello():
2    print("Hello World!")
3
4def main():
5    hello()

Tables

Markdown
| Syntax    | Description |
| --------- | ----------- |
| Header    | Title       |
| Paragraph | Text        |

How it renders:

Syntax Description
Header Title
Paragraph Text

Inline Markdown within tables and alignment

Markdown
| Italics   | Bold     | Code   |
| :-------- | :------: | -----: |
| *italics* | **bold** | `code` |

How it renders:

Italics Bold Code
italics bold code

Alerts

Alerts are a Markdown extension based on the blockquote syntax that you can use to emphasize critical information. GitHub-style alerts are supported.

Please make sure you are using Hugo v0.146.0 or later.

Markdown
> [!NOTE]
> Useful information that users should know, even when skimming content.

> [!TIP]
> Helpful advice for doing things better or more easily.

> [!IMPORTANT]
> Key information users need to know to achieve their goal.

> [!WARNING]
> Urgent info that needs immediate user attention to avoid problems.

> [!CAUTION]
> Advises about risks or negative outcomes of certain actions.

How it renders:

Hinweis

Useful information that users should know, even when skimming content.

Tipp

Helpful advice for doing things better or more easily.

Wichtig

Key information users need to know to achieve their goal.

Warnung

Urgent info that needs immediate user attention to avoid problems.

Achtung

Advises about risks or negative outcomes of certain actions.

Other Elements

HTML is supported in most cases:

Markdown abbreviation
<abbr title="Graphics Interchange Format">GIF</abbr> is a bitmap image format.

GIF is a bitmap image format.

Markdown keyboard
Press <kbd>CTRL</kbd> + <kbd>ALT</kbd> + <kbd>Delete</kbd> to end the session.

Press CTRL + ALT + Delete to end the session.

Configuration

Hugo uses Goldmark for Markdown parsing. Markdown rendering can be configured in hugo.yaml under markup.goldmark. See Hugo documentation on Configure Markup.

Learning Resources

  1. The above quote is excerpted from Rob Pike’s talk during Gopherfest, November 18, 2015. ↩︎