Tutorial on My Blog

Quick Start: Deploy Your Blog with One Click

Thu, 09 Apr 2026 00:00:00 +0000

Welcome to Hugo Theme Stack Starter

This is a ready-to-use blog template based on Hugo Theme Stack v4, featuring enhanced styling, bilingual support, and GitHub Actions auto-deployment. You can get started without installing anything locally.

Option 1: GitHub Template — One Click Deploy (Recommended)

The easiest way — everything happens in your browser.

Step 1: Create your repository from this template

Open this project’s GitHub page
Click the green “Use this template” button → “Create a new repository”
Enter a repository name (e.g., my-blog), select Public (required for free GitHub Pages)
Click “Create repository”

Step 2: Enable GitHub Pages

In your new repository, go to Settings → Pages
Under “Source”, select “GitHub Actions”
Save

Step 3: Update your configuration

Edit config/_default/config.toml directly on GitHub:

# Replace with your GitHub Pages URL
baseurl = "https://your-username.github.io/repo-name/"
title   = "My Blog"

Step 4: Push to trigger auto-deployment

Every commit triggers GitHub Actions to build and deploy automatically. Wait 1–2 minutes, then visit your GitHub Pages URL to see your blog live!

Option 2: Local Development

If you prefer to write and preview locally:

Install Hugo (Extended edition)

# macOS
brew install hugo

# Windows (Scoop)
scoop install hugo-extended

# Linux (apt)
sudo apt install hugo

Verify it’s the extended edition:

hugo version
# Output should include "extended"

Clone and run

git clone https://github.com/your-username/my-blog.git
cd my-blog
hugo server

Visit http://localhost:1313 to preview your blog.

Configuration Guide

All config files are in config/_default/:

File	Purpose
`config.toml`	Site title, base URL, default language
`languages.toml`	Multilingual settings (zh/en)
`params.toml`	Theme parameters (comments, homepage layout)
`params.en.toml`	English-specific parameters (avatar, subtitle)
`menu.en.toml`	English navigation menu

Required changes

1. Site title and URL (config.toml):

baseurl = "https://your-domain.com/"
title   = "My Blog"

2. Your avatar and bio (params.en.toml):

[sidebar]
    subtitle = "Your personal tagline"
    avatar   = "img/avatar.jpg"  # replace assets/img/avatar.jpg

3. Blog launch date (params.toml):

[footer]
    launchDate = "2024-01-01"  # your blog's start date

Project Structure

my-blog/
├── .github/workflows/    # GitHub Actions (no changes needed)
├── assets/scss/          # Style customization
│   ├── custom.scss       # Colors, global styles
│   └── partials/custom-components/  # Component styles
├── config/_default/      # All configuration files
├── content/
│   └── post/             # Blog posts (write here)
├── layouts/              # Custom layouts and Shortcodes
└── static/               # Static assets (images, etc.)

What’s Next

📖 Theme Customizations — What this template changes from the original
💬 Set Up Waline Comments — Add a comment section to your blog
✏️ Start Writing — Learn Markdown and multilingual posts

Happy blogging! 🎉

Theme Customizations: What I Have Changed

Fri, 10 Apr 2026 00:00:00 +0000

This template is developed based on Hugo Theme Stack v4. While maintaining the integrity of the original features, a series of visual and interactive enhancements have been made.

All modifications are implemented using Hugo’s override mechanism (by creating files with the same names in assets/ and layouts/), without modifying the original theme’s source code, making it easy to upgrade the theme version at any time.

1. Global Color System

The entire set of color variables has been redefined, adopting a deep blue + warm off-white color scheme:

Light Mode:

Background color: Warm off-white #f8f7f2 (easier on the eyes than pure white)
Accent color: Deep sea blue #1B365D
Card background: #fdfdfb (slightly warm white)

Dark Mode:

Background color: #101214 (dark grayish-black)
Card background: #1c2128 (GitHub dark style)
In dark mode, images are automatically dimmed, restoring brightness on hover

Modification location: :root variables in assets/scss/custom.scss.

2. Mac-Style Code Blocks

The original theme’s code blocks are quite simple, but this template comprehensively beautifies them:

Top Title Bar

A macOS-style three-color dot decoration (red, yellow, green) has been added to every code block, simulating a terminal window appearance.

Redesigned Copy Button

Changed from an inconspicuous icon button to a text button floating on the right side of the title bar
Light mode: Frosted glass style (backdrop-filter: blur)
Dark mode: Dark translucent background
Clicking the button changes the text to “✓ Copied!”

Auto-Collapse Long Code Blocks

Code blocks taller than 600px automatically collapse, with an “Expand Code” button at the bottom:

When collapsed, a gradient overlay appears at the bottom
After expanding, the button text changes to “Collapse Code”
When collapsing, it automatically scrolls back to the top of the code block, preventing page layout confusion

Beautified Scrollbars

The horizontal scrollbar of code blocks is transparent by default and only appears on hover, keeping the interface clean.

3. Homepage Two-Column Grid Layout

On desktop screens (width ≥ 1024px), the homepage article list changes to a 2-column grid display:

Each article is presented as a card containing a cover image, title, summary, and meta information
Cards have a slight floating animation on hover
Long article titles and summaries are automatically truncated (2 lines)
Automatically reverts to a single-column list on mobile devices

To enable: Set it in params.toml:

[homepage]
    grid = true

The original theme’s mobile navigation is relatively basic. This template completely rewrites the mobile experience:

Fixed to the top (sticky), remaining visible as you scroll down the page
Left side: Avatar + Site name (click to return home)
Right side: Dark mode toggle, language switch, search, and hamburger menu

Clicking expands the side menu with a fade-in animation
The top bar title fades out when the menu expands to prevent overlap
The current page’s menu item is highlighted
Automatically closes when the screen width recovers (e.g., rotating device)

The search box in the desktop sidebar has been redesigned to match the card style.

5. Blog Stats Page

A feature-rich /stats/ statistics page has been added, including:

Summary Cards: Total articles, total words, running days (animated scrolling numbers)
Category Distribution: Category list with progress bars, clickable to enter category pages
Popular Tags: Tag cloud display (top 30 tags)
Writing Habits: Posting habit analysis by day of the week and time of day (based on Git commit times)
Yearly Heatmap: GitHub-style contribution heatmap (publishing record for the past year)

Configuration page entry: Set layout: stats in content/stats/index.en.md.

The footer now displays the blog’s runtime, calculating the days, hours, and minutes since the launch date.

Clicking it navigates to the Stats page.

Configure launch date:

[footer]
    launchDate = "2024-09-09"

7. Custom Shortcodes

Timeline

Suitable for displaying growth history, tech stack evolution, etc.:

{{< timeline >}}
{{< timeline-item date="2024-01" >}}
Started learning Hugo
{{< /timeline-item >}}
{{< timeline-item date="2024-06" >}}
Blog officially launched
{{< /timeline-item >}}
{{< /timeline >}}

Title Divider

Suitable for separating content sections like diaries or fitness logs:

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

Supported colors: red, orange, yellow, green, teal, blue, indigo, purple, pink, gray

How to Customize Colors

Edit assets/scss/custom.scss, modifying the variables in :root:

:root {
    --accent-color: #1B365D;        /* Accent color (buttons, links, etc.) */
    --body-background: #f8f7f2;     /* Page background */
    --card-background: #fdfdfb;     /* Card background */
}

After saving, Hugo will automatically recompile and refresh the browser in real-time.

Set Up Waline Comments

Sat, 11 Apr 2026 00:00:00 +0000

Waline is a safe and concise comment system that supports Markdown, offers free deployment, and allows users to comment without registering.

This template has built-in integration for Waline. You just need to deploy the server-side application and fill in one line of configuration to enable it.

Step 1: Deploy Waline Server

Please refer to the Waline Official Quick Start Guide to complete the server deployment:

👉 https://waline.js.org/en/guide/get-started/

The official documentation provides a free one-click deployment solution on Vercel. The entire process takes about 5 minutes.

Once deployed, you will receive a Waline service address, such as:

https://your-waline-project.vercel.app/ (Default Vercel domain)
Or your bound custom domain

Save this address; you will need it in the next step.

Step 2: Configure in This Template

Edit config/_default/params.toml and fill in your service address:

[comments]
    enabled  = true
    provider = "waline"

[comments.waline]
    serverURL = "https://your-waline-project.vercel.app/"  # ← Fill in your address here
    pageview  = true       # Also enable article pageview statistics

    # Optional: Custom emoji package (default is Weibo emoji)
    emoji = ["https://unpkg.com/@waline/emojis@1.0.1/weibo"]

    # Required fields for comments
    requiredMeta = ["name"]

    [comments.waline.locale]
        admin = "Admin"    # Administrator badge

Save and restart hugo server, and the comment section will appear at the bottom of your article pages.

Features Overview

Pageview Statistics

After setting pageview = true, pageviews will automatically be displayed at the top of the article (Requires Waline server support).

Comment Management Dashboard

Visit https://your-waline-project.vercel.app/ui/ to access the management interface. The first registered account automatically becomes the administrator, who can review and delete comments.

Email Notifications

You can be notified via email when someone replies. This requires configuring SMTP information in Vercel environment variables. See the Official Documentation - Notification for details.

FAQ

Comment section not showing up?
Check if there is a trailing slash / at the end of serverURL, and ensure the Vercel service is running normally (you should see the Waline welcome page when visiting the serverURL directly).

Cookie banner blocking the comment section?
If you have enabled the Cookie consent feature, users must accept “Functional Cookies” before the comment section will appear. You can disable the Cookie prompt in params.toml or instruct users to accept it.

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! ✍️

Shortcodes Guide

Tue, 14 Apr 2026 00:00:00 +0000

Hugo Shortcodes are a way to embed special components within Markdown. This article demonstrates the actual rendering effects of all custom Shortcodes included in this template.

Title Divider (title)

Ideal for content that requires section headings, such as diaries, workout logs, or study notes.

Usage:

{{< title "Heading Text" "color" >}}

Actual Effects — Different Colors:

Green Heading

This is the content under the green divider, suitable for sports or health-related logs.

Blue Heading

This is the content under the blue divider, suitable for tech or study-related logs.

Orange Heading

This is the content under the orange divider, suitable for creative or design-related logs.

Purple Heading

This is the content under the purple divider, suitable for diaries or essays.

Custom Color #E91E63

You can also use hex color codes directly.

All Built-in Colors:

Color Name	Preview
`red`	Red
`orange`	Orange
`yellow`	Yellow
`green`	Green
`teal`	Teal
`blue`	Blue
`indigo`	Indigo
`purple`	Purple
`pink`	Pink
`gray`	Gray

Timeline

Suitable for showcasing personal experiences, project milestones, tech growth trajectories, etc.

Usage:

{{< timeline >}}
{{< timeline-item date="2024-01" >}}
Content...
{{< /timeline-item >}}
{{< /timeline >}}

Actual Effect:

2024-01

Started learning Hugo and understanding the benefits of static blogs.
2024-06

Blog officially launched. Published the first technical article and gained the first batch of readers.
2025-01

Integrated the Waline comment system to interact with readers. The comment section is becoming active.
2025-09

Beautified the blog theme, adding features like Mac-style code blocks and a comprehensive Stats page.

Timeline content supports full Markdown, such as bold, inline code, links, etc.

Code Block Features (Theme Enhancement)

Code blocks are not Shortcodes themselves, but this template has enhanced them:

Copy Button

Every code block has a copy button in the top right corner (inside the macOS title bar):

// Try clicking the copy button in the top right corner
function greet(name) {
    return `Hello, ${name}!`;
}
console.log(greet("Hugo"));

Auto-Collapse Long Code

Code blocks taller than 600px automatically collapse, and an “Expand Code” button appears at the bottom. Here is a long snippet to test the collapse feature:

# This code is long enough to trigger the auto-collapse
import os
import sys
import json
import time
import datetime

class BlogStats:
    def __init__(self, posts_dir: str):
        self.posts_dir = posts_dir
        self.posts = []
        self.total_words = 0
        self.categories = {}
        self.tags = {}

    def scan_posts(self):
        """Scan all article directories"""
        for root, dirs, files in os.walk(self.posts_dir):
            for file in files:
                if file.endswith('.md'):
                    filepath = os.path.join(root, file)
                    self.parse_post(filepath)

    def parse_post(self, filepath: str):
        """Parse front matter of a single article"""
        with open(filepath, 'r', encoding='utf-8') as f:
            content = f.read()

        # Extract front matter
        if content.startswith('---'):
            end = content.find('---', 3)
            if end > 0:
                front_matter = content[3:end].strip()
                body = content[end+3:].strip()
                self.total_words += len(body.split())
                self.parse_front_matter(front_matter)

    def parse_front_matter(self, front_matter: str):
        """Parse YAML front matter"""
        for line in front_matter.split('\n'):
            if line.startswith('categories:'):
                pass  # Simplified handling
            elif line.startswith('tags:'):
                pass  # Simplified handling
            elif line.startswith('    - '):
                tag = line.strip().lstrip('- ')
                self.tags[tag] = self.tags.get(tag, 0) + 1

    def get_report(self) -> dict:
        """Generate statistical report"""
        return {
            'total_posts': len(self.posts),
            'total_words': self.total_words,
            'categories': sorted(
                self.categories.items(),
                key=lambda x: x[1],
                reverse=True
            ),
            'tags': sorted(
                self.tags.items(),
                key=lambda x: x[1],
                reverse=True
            )[:20],
        }

if __name__ == '__main__':
    stats = BlogStats('./content/post')
    stats.scan_posts()
    report = stats.get_report()
    print(json.dumps(report, ensure_ascii=False, indent=2))

Hugo Built-in Shortcodes

Hugo comes with some very useful Shortcodes:

Figure (Enhanced Images)

{{< figure src="image.jpg" title="Image Title" caption="Image Caption" >}}

This adds titles and captions, which the standard ![](image.jpg) doesn’t support easily.

Gist

{{< gist username gist-id >}}

Embeds a GitHub Gist code snippet directly.

How to Create Your Own Shortcode

Simply create an HTML file under layouts/shortcodes/. For example, create badge.html:

<!-- layouts/shortcodes/badge.html -->
<span style="
  display: inline-block;
  padding: 2px 10px;
  border-radius: 4px;
  font-size: 12px;
  font-weight: 600;
  background: {{ .Get 1 | default `var(--accent-color)` }};
  color: {{ .Get 2 | default `#fff` }};
">{{ .Get 0 }}</span>

Usage: {{< badge "New" "#059669" >}}

Style Customization Guide

Mon, 13 Apr 2026 00:00:00 +0000

The styling system of this template is based on SCSS. All custom styles are located in the assets/scss/ directory, so you do not need to modify the original theme files.

Modify Theme Colors

Open assets/scss/custom.scss and modify the CSS variables inside :root:

:root {
    /* Light Mode */
    --accent-color: #1B365D;           /* Accent color: buttons, links, highlights */
    --accent-color-darker: #202A44;    /* Darker accent: hover states */
    --accent-color-text: #FFF;         /* Text color on top of the accent color */
    --body-background: #f8f7f2;        /* Page background */
    --card-background: #fdfdfb;        /* Card background */
    --body-text-color: #2D3748;        /* Body text color */

    &[data-scheme="dark"] {
        /* Dark Mode Overrides */
        --body-background: #101214;
        --card-background: #1c2128;
        /* ... */
    }
}

After saving, Hugo automatically recompiles and the browser refreshes instantly.

Popular Color Palette References

Purple Scheme:

--accent-color: #7C3AED;
--accent-color-darker: #6D28D9;

Green Scheme:

--accent-color: #059669;
--accent-color-darker: #047857;

Orange Scheme:

--accent-color: #EA580C;
--accent-color-darker: #C2410C;

Modify Code Block Styles

Code block related styles are in assets/scss/partials/custom-components/_code.scss.

Disable Mac-Style Title Bar

If you don’t like the macOS three-color dots, comment out the following code:

/* Comment out this before pseudo-element to disable the title bar */
/*
.article-content .highlight:before {
    ...
}
*/

Change Collapse Threshold

In _code.scss and layouts/_partials/footer/custom.html, change 600 to your desired pixel value:

/* _code.scss */
&.collapsed {
    max-height: 400px;  /* Change to your desired height */
}

/* JS in custom.html */
const MAX_HEIGHT = 400;  /* Keep consistent with CSS */

Add Custom Fonts

Add Google Fonts in assets/scss/custom.scss and set the font family:

/* Import font */
@import url('https://fonts.googleapis.com/css2?family=Outfit:wght@400;700&display=swap');

/* Apply to body */
body {
    font-family: 'Outfit', sans-serif;
}

/* Apply to article content */
.article-content {
    font-family: 'Outfit', sans-serif;
    line-height: 1.9;
}

Component Style Files Overview

File	Purpose
`custom.scss`	Global variables, TOC scrollbar
`_code.scss`	All code block styles
`_footer.scss`	Footer runtime button
`_homepage-grid.scss`	Homepage two-column grid
`_mobile-menu.scss`	Mobile top navigation bar
`_timeline.scss`	Timeline Shortcode styles
`_title.scss`	Title divider Shortcode styles

Each file has a single responsibility and can be modified independently without affecting others.

Disable Homepage Grid Layout

If you prefer the traditional single-column list, edit params.toml:

[homepage]
    grid = false

Overriding Theme Layouts

If you need to modify other layout files of the theme, simply create a file with the same name in the layouts/ directory to override it:

For example, to modify the article page layout, view the original file at hugo-theme-stack-v4/layouts/single.html, then copy it to layouts/single.html in your project root and modify it.

Hugo’s override mechanism prioritizes files in the project’s root directory over the theme’s files.

Tutorial on My Blog

Quick Start: Deploy Your Blog with One Click

Welcome to Hugo Theme Stack Starter

Option 1: GitHub Template — One Click Deploy (Recommended)

Step 1: Create your repository from this template

Step 2: Enable GitHub Pages

Step 3: Update your configuration

Step 4: Push to trigger auto-deployment

Option 2: Local Development

Install Hugo (Extended edition)

Clone and run

Configuration Guide

Required changes

Project Structure

What’s Next

Theme Customizations: What I Have Changed

1. Global Color System

2. Mac-Style Code Blocks

Top Title Bar

Redesigned Copy Button

Auto-Collapse Long Code Blocks

Beautified Scrollbars

3. Homepage Two-Column Grid Layout

4. Redesigned Mobile Navigation

Sticky Top Navigation Bar

Hamburger Menu

Search Box

5. Blog Stats Page

6. Footer Runtime

7. Custom Shortcodes

Timeline

Title Divider

How to Customize Colors

Set Up Waline Comments

Step 1: Deploy Waline Server

Step 2: Configure in This Template

Features Overview

Pageview Statistics

Comment Management Dashboard

Email Notifications

FAQ

Start Writing: Markdown Basics and Multilingual Posts

Create Your First Post

Option 1: Using Commands (Recommended)

Option 2: Manual Creation

Front Matter Explanation

Basic Markdown Syntax

Headings

Text Formatting

Links and Images

Lists

Code Blocks

Blockquotes

Tables

Horizontal Rule

Multilingual Writing

File Naming Convention

Writing Only in English

Adding a Chinese Version

Inserting Images

Using Images from the Post Directory (Recommended)

Using Images from the static Directory

Using Template Shortcodes

Title Divider

Timeline

Writing Tips

Shortcodes Guide

Title Divider (title)

Timeline

Code Block Features (Theme Enhancement)

Copy Button

Auto-Collapse Long Code

Hugo Built-in Shortcodes

Figure (Enhanced Images)

Gist

How to Create Your Own Shortcode

Style Customization Guide

Modify Theme Colors

Popular Color Palette References

Modify Code Block Styles