**A Complete Workflow for “Hugo + GitHub + Two Branches (source/main) + Automatic Deployment”**

Conventions:

• source branch: Stores Hugo source code
• main branch: Stores the static files generated by Hugo (for GitHub Pages)

I. Preparation

hugo version

• Install Hugo according to your operating system and verify the version.

1. Create a GitHub Repository
   • Create a new repo, for example: my-blog
   • It comes with a default main branch, keep it (this will later store static files)

II. Initialize Hugo Locally and Push to the `source` Branch

git clone git@github.com:your-username/my-blog.git
cd my-blog

1. Create and switch to the source branch:

git checkout -b source

1. Initialize a Hugo project in the current directory:

hugo new site .

1. Add a theme (e.g., Ananke):

git submodule add https://github.com/theNewDynamic/gohugo-theme-ananke.git themes/ananke

Add the following to config.toml:

theme = "ananke"
baseURL = "https://your-username.github.io/"

1. Create a test post:

hugo new posts/hello-world.md

Then edit content/posts/hello-world.md and change draft: true to false.

1. Commit to the source branch:

git add .
git commit -m "init hugo site"
git push origin source

III. Make the `main` Branch Contain Only Static Files

GitHub requires two things:

1. A GitHub Actions workflow (automatic build)
2. GitHub Pages configuration (deploy from main)

IV. Create a GitHub Actions Workflow

1. Automatically pull the code
2. Install Hugo
3. Run hugo to generate static files into public/
4. Push the content of public/ to the main branch
5. Create the workflow folder inside the source branch:

mkdir -p .github/workflows

1. Create the file .github/workflows/gh-pages.yml with the following:

name: GitHub Pages

on:
  push:
    branches:
      - source  # Trigger when source branch is updated

jobs:
  build-deploy:
    runs-on: ubuntu-20.04
    concurrency:
      group: ${{ github.workflow }}-${{ github.ref }}
    steps:
      - name: Checkout
        uses: actions/checkout@v3
        with:
          submodules: true
          fetch-depth: 0

      - name: Setup Hugo
        uses: peaceiris/actions-hugo@v2
        with:
          hugo-version: "latest"

      - name: Build
        run: hugo --minify

      - name: Deploy
        uses: peaceiris/actions-gh-pages@v3
        with:
          github_token: ${{ secrets.HUGO_BLOG }}  # Your GitHub token
          publish_branch: main  # Push output to main branch
          publish_dir: ./public  # Public directory is the Hugo output

1. Commit the workflow:

git add .github/workflows/gh-pages.yml
git commit -m "add github actions for hugo deploy"
git push origin source

1. Go to your GitHub repo → Actions, and you should see the workflow running.
   • If successful, the main branch will be created/updated with pure static files (index.html, etc.).

V. Configure GitHub Pages to Use the `main` Branch

GitHub will give you a site URL, usually:

• https://your-username.github.io/
  or
• https://your-username.github.io/repo-name/

Your Hugo blog should appear in a few minutes.

VI. Daily Blogging Workflow (Only Use the `source` Branch)

git checkout source

1. Create a new post:

hugo new posts/xxx.md

Edit the file and change draft: true to false.

1. Local preview (optional):

hugo server -D

Visit http://localhost:1313 to preview.

1. Commit and push:

git add .
git commit -m "add new post"
git push origin source

GitHub Actions will automatically build and deploy to main.
GitHub Pages updates automatically.

VII. Common Issues & Tips

If your repository is notyour-username.github.io but a normal repo (e.g., my-blog),
then the baseURL in config.toml must be:

baseURL = "https://your-username.github.io/my-blog/"

1. Do not edit the **main** branch manually
   • It will be overwritten by every workflow run
   • All content must be changed through the source branch only
2. Actions Permissions
   • The default GITHUB_TOKEN works for pushing to main
   • If errors occur, go to:
     Settings → Actions → General → Workflow permissions
     and enable:
     • Read and write permissions