syccxdr's Blog

A minimal personal blog built with Hugo and PaperMod theme, deployed on GitHub Pages.

🌐 Live Site: https://syccxdr.github.io

---

Tech Stack

• Hugo: v0.156.0 (extended)
• Theme: PaperMod
• Fonts:
  • English: Inter
  • Chinese: LXGW WenKai (霞鹜文楷)
  • Code: Fira Code with ligatures
• Deployment: GitHub Actions → GitHub Pages

---

Quick Start (Clone & Run Locally)

Prerequisites

• Homebrew (macOS/Linux)
• Git

Setup Steps

1. Install Hugo

brew install hugo
hugo version  # Should be v0.156.0 or higher

2. Clone the Repository

git clone --recursive git@github.com:syccxdr/syccxdr.github.io.git
cd syccxdr.github.io

⚠️ IMPORTANT: The --recursive flag is required to clone the PaperMod theme submodule. If you forgot it:

git submodule update --init --recursive

3. Preview Locally

hugo server -D

Open http://localhost:1313 in your browser.

---

Project Structure

.
├── .github/workflows/hugo.yaml   # GitHub Actions deployment
├── assets/css/extended/          # Custom CSS overrides
│   └── fonts.css                 # Custom font configuration
├── content/
│   ├── archives.md               # Archives page
│   ├── posts/                    # Blog posts (Markdown)
│   └── search.md                 # Search page
├── themes/PaperMod/              # Theme (git submodule)
├── hugo.yaml                     # Site configuration
├── PUBLISH_GUIDE.md              # How to publish new posts
└── README.md                     # This file

---

Configuration Overview

Key Settings in hugo.yaml

Setting	Value	Purpose
baseURL	https://syccxdr.github.io/	Production URL
languageCode	en-us	English UI
theme	PaperMod	Hugo theme
params.homeInfoParams	Home-Info mode	Welcome banner + post list
params.ShowCodeCopyButtons	true	Copy buttons for code blocks
outputs.home	[HTML, RSS, JSON]	JSON required for search

Git Configuration

This repository uses local git config to separate from work accounts:

# View current repo git identity
git config --local user.name   # syccxdr
git config --local user.email  # 1070211640@qq.com

To set up the same local config after cloning:

cd syccxdr.github.io
git config --local user.name "syccxdr"
git config --local user.email "1070211640@qq.com"

This only affects this repository, your global git config remains unchanged.

---

Deployment

Automatic Deployment (Recommended)

Every push to main branch triggers GitHub Actions automatically:

1. Builds the site with Hugo v0.156.0
2. Deploys to GitHub Pages

View workflow runs: https://github.com/syccxdr/syccxdr.github.io/actions

Manual Deployment

If you need to deploy from a different machine:

# 1. Make changes
git add .
git commit -m "Your commit message"

# 2. Push (triggers GitHub Actions)
git push

GitHub Pages Settings

Important: Ensure GitHub Pages source is set to GitHub Actions:

1. Go to: https://github.com/syccxdr/syccxdr.github.io/settings/pages
2. Source: GitHub Actions
3. Save

---

Publishing New Posts

See PUBLISH_GUIDE.md for detailed instructions.

Quick reference:

# 1. Create new post
hugo new content posts/my-new-post.md

# 2. Edit the file (set draft: false to publish)

# 3. Preview locally
hugo server -D

# 4. Commit and push
git add content/posts/my-new-post.md
git commit -m "New post: My New Post"
git push

---

Customization

Fonts

Custom fonts are defined in assets/css/extended/fonts.css:

• English: Inter (Google Fonts)
• Chinese: LXGW WenKai via CDN
• Code: Fira Code with ligatures

To change fonts, edit this file.

Theme Settings

PaperMod configuration is in hugo.yaml under params:. Key toggles:

• ShowReadingTime: Show estimated reading time
• ShowCodeCopyButtons: Copy buttons for code blocks
• ShowToc: Table of contents for posts
• defaultTheme: auto (respects system dark/light mode)

Full options: https://github.com/adityatelange/hugo-PaperMod/wiki/Variables

Menu

Navigation menu is configured in hugo.yaml under menu.main:

menu:
  main:
    - identifier: posts
      name: Posts
      url: /posts/
      weight: 10

---

Troubleshooting

Issue: hugo: command not found

Solution: Install Hugo with Homebrew:

brew install hugo

Issue: Theme not found / empty site

Solution: Initialize git submodules:

git submodule update --init --recursive

Issue: GitHub Actions build fails

Common causes:

1. Hugo version mismatch (check .github/workflows/hugo.yaml)
2. Theme not cloned (check submodules: recursive in workflow)
3. Pages source not set to "GitHub Actions"

Fix: Ensure Hugo version in CI matches local version (v0.156.0).

Issue: Fonts not loading

Check:

1. assets/css/extended/fonts.css exists
2. CDN links are accessible (Google Fonts, jsDelivr)
3. Clear browser cache

---

Resources

• Hugo Documentation: https://gohugo.io/documentation/
• PaperMod Wiki: https://github.com/adityatelange/hugo-PaperMod/wiki
• GitHub Pages Docs: https://docs.github.com/en/pages

---

License

This blog content is © 2026 syccxdr. The Hugo framework and PaperMod theme have their own licenses.