Skip to main content
Your Hugo site supports standard Markdown syntax along with extended features provided by Hugo and the Congo theme.

Basic syntax

Headings

Create headings using hash symbols:
# Heading 1
## Heading 2
### Heading 3
#### Heading 4
##### Heading 5
###### Heading 6

Paragraphs

Separate paragraphs with a blank line:
This is the first paragraph.

This is the second paragraph.

Emphasis

Add emphasis with asterisks or underscores:
*Italic text* or _italic text_
**Bold text** or __bold text__
***Bold and italic*** or ___bold and italic___
Rendered as:
  • Italic text
  • Bold text
  • Bold and italic

Lists

Create unordered lists with hyphens, asterisks, or plus signs:
- Item one
- Item two
- Item three
Create ordered lists with numbers:
1. First item
2. Second item
3. Third item
Create links using bracket and parenthesis syntax:
[Link text](https://example.com)
[Link with title](https://example.com "Title text")
Example from the benson.vc site:
[The Economist's OpenFuture Initiative](https://www.economist.com/openfuture)

Images

Insert images using similar syntax to links, with a leading exclamation mark:
![Alt text](image.jpg)
![Alt text with title](image.jpg "Image title")

Extended syntax

Blockquotes

Create blockquotes with the greater-than symbol:
> This is a blockquote.
> It can span multiple lines.
Real example from the benson.vc site:
> **Q: Do the benefits of artificial intelligence outweigh the risks?**

*The late physicist Stephen Hawking warned that artificial intelligence (AI) was "either the best or the worst thing ever to happen to humanity".*
Rendered as:
Q: Do the benefits of artificial intelligence outweigh the risks?
The late physicist Stephen Hawking warned that artificial intelligence (AI) was “either the best or the worst thing ever to happen to humanity”.

Code blocks

Create inline code with backticks:
Use the `code` function to execute.
Create fenced code blocks with triple backticks:
```
Code block without syntax highlighting
```

```javascript
function hello() {
  console.log("Hello, world!");
}
```

Horizontal rules

Create horizontal rules with three or more hyphens, asterisks, or underscores:
---
***
___

Hugo-specific features

Shortcodes

Hugo provides shortcodes for enhanced functionality. The Congo theme includes several built-in shortcodes.

Figure shortcode

{{< figure src="image.jpg" title="Figure title" >}}

YouTube shortcode

{{< youtube VIDEO_ID >}}

Tweet shortcode

{{< tweet user="username" id="tweet_id" >}}

Content summaries

Hugo can automatically generate summaries from your content. Use the <!--more--> comment to manually specify where the summary should end:
This is the summary of your post.

<!--more-->

This is the rest of your post content.

Congo theme features

The Congo theme extends Hugo’s capabilities with additional styling and features.

Automatic table of contents

Congo can automatically generate a table of contents from your headings. This is configured in your site’s configuration files.

Syntax highlighting

Congo supports syntax highlighting for code blocks. Specify the language after the opening backticks:
```python
def hello_world():
    print("Hello, world!")
```
Supported languages include:
  • JavaScript/TypeScript
  • Python
  • Go
  • Rust
  • HTML/CSS
  • Bash/Shell
  • And many more

Responsive images

Images in Congo are automatically optimized and made responsive for different screen sizes.

Best practices

While Hugo supports inline HTML in Markdown files, it’s best to stick with Markdown syntax for portability and simplicity. Use HTML only when you need specific styling or functionality that Markdown doesn’t provide.
Hugo supports attribute lists for Markdown elements. You can add classes and IDs using the syntax {.class #id} after certain elements. However, this feature depends on your Markdown renderer configuration.
Yes! Hugo supports GitHub Flavored Markdown (GFM) tables:
| Column 1 | Column 2 | Column 3 |
|----------|----------|----------|
| Value 1  | Value 2  | Value 3  |
| Value 4  | Value 5  | Value 6  |
Code blocks display code as text content, while shortcodes are processed by Hugo to generate HTML output. Use code blocks to show code examples and shortcodes to embed interactive content like videos or tweets.

Writing tips

  • Use headings hierarchically (don’t skip levels)
  • Keep paragraphs focused on a single idea
  • Use lists to break up dense information
  • Add alt text to images for accessibility
  • Use code blocks for any code or command examples
  • Preview your content locally before publishing

Resources

Build docs developers (and LLMs) love