Start Writing: Markdown Basics and Multilingual Posts

Sun, 12 Apr 2026 00:00:00 +0000

Create Your First Post

Option 1: Using Commands (Recommended)

# Create an English post
hugo new content post/my-first-post/index.en.md

# Create the corresponding Chinese version
hugo new content post/my-first-post/index.zh.md

Hugo will automatically populate initial content based on the archetypes/default.md template.

Option 2: Manual Creation

Create a new folder under content/post/, and then create index.en.md inside it:

content/
└── post/
 └── my-first-post/ ← Post directory (Name becomes the URL)
 ├── index.en.md ← English body
 ├── index.zh.md ← Chinese body (Optional)
 └── cover.jpg ← Cover image (Optional)

Front Matter Explanation

The section between the --- at the top of each article is called Front Matter, used to define article metadata:

---
title: "Post Title"
description: "Post summary, displayed on the list page and in SEO descriptions"
date: 2026-04-12 # Publish date
lastmod: 2026-04-23 # Last modified date (optional)
draft: false # true = draft, will not be published
categories:
 - Technology  # Category (recommended to pick only one)
tags:
 - Hugo  # Tags (can have multiple)
 - Markdown
image: cover.jpg  # Cover image (relative to the post directory)
---

Tip: The date determines the sort order of posts in lists. Posts with future dates require hugo server -F to be visible during local preview.

Basic Markdown Syntax

Headings

## Heading 2
### Heading 3
#### Heading 4

Avoid using Heading 1 (# H1) in the article body because the title field is already an H1.

Text Formatting

**Bold** Bold text
*Italic* Italic text
~~Strikethrough~~ Strikethrough
`Inline code` Code

Result: Bold, Italic, ~~Strikethrough~~, Inline code

Links and Images

[Link text](https://example.com)
[Internal link](/post/hello-world/)

![Image description](image.jpg) # Relative path (same directory)
![Image description](/img/photo.jpg) # Absolute path (in static directory)

Lists

- Unordered list item
- Second item
 - Nested item

1. Ordered list
2. Second item
3. Third item

Code Blocks

```python
def hello():
 print("Hello, World!")
```

Supports syntax highlighting for: python, go, javascript, bash, toml, yaml, markdown, etc.

Blockquotes

> This is a blockquote.
> It can span multiple lines.

Result:

This is a blockquote.

Tables

| Column 1 | Column 2 | Column 3 |
|----------|----------|----------|
| Content 1| Content 2| Content 3|
| Content 4| Content 5| Content 6|

Horizontal Rule

---

Multilingual Writing

This template has built-in support for Chinese and English.

File Naming Convention

Filename	Language
`index.en.md`	English
`index.zh.md`	Chinese

Place both files in the same directory, and Hugo will automatically link them as different language versions of the same post.

Writing Only in English

If you don’t want to write a Chinese version, just create index.en.md.

Adding a Chinese Version

Create index.zh.md in the same directory.
Translate the article content (also translate title and description in the Front Matter).
Images and other resources are shared between both language versions; no need to duplicate them.

Example:

index.en.md:

---
title: "My First Post"
description: "This is my first blog post"
date: 2026-04-12
---
Content...

index.zh.md:

---
title: "我的第一篇文章"
description: "这是我的第一篇博客文章"
date: 2026-04-12
---
内容...

Inserting Images

Using Images from the Post Directory (Recommended)

Place the image in the post directory, and reference it using a relative path:

content/post/my-post/
├── index.en.md
├── cover.jpg ← Cover image
└── screenshot.png ← Image inside the post

In Markdown:

![Screenshot description](screenshot.png)

Specify the cover image in the Front Matter:

image: cover.jpg

Using Images from the static Directory

Place the image in static/img/, and reference it using an absolute path:

![Image](img/photo.jpg)

Using Template Shortcodes

Title Divider

Suitable for separating paragraphs in diary-style posts:

{{< title "Morning Run" "green" >}}

Ran 5 km today, feeling great.

{{< title "Afternoon Reading" "blue" >}}

Read two chapters of "Deep Work".

Timeline

Suitable for showing experiences and growth trajectories:

{{< timeline >}}
{{< timeline-item date="2024-01" >}}
Started learning programming
{{< /timeline-item >}}
{{< timeline-item date="2024-06" >}}
Completed first project
{{< /timeline-item >}}
{{< /timeline >}}

Writing Tips

The post directory name becomes the URL. It is recommended to use lowercase English letters and hyphens, like my-first-post.
Cover images are recommended to be 1200×630px, which is the optimal size for social sharing.
Keep the description under 160 characters for SEO friendliness.
Use hugo server -D during local preview to view draft posts.

Happy writing! ✍️

Multilingual on wangcl's blog