基于 Hugo 搭建并部署在 Github Pages

1 安装 Hugo

官网教程

  1. 新建目录C:\programs\hugo
  2. 在官网 下载最新版，本次下载 hugo_extended_0.99.1_Windows-64bit.zip
  3. 解压 zip 文件，并将解压出的hugo.exe移到C:\programs\hugo
  4. 添加环境变量： win+R -> sysdm.cpl -> 高级 -> 环境变量(N)… -> 系统变量(S) -> 双击 Path -> 新建 -> 输入C:\programs\hugo
  5. 打开命令行，输入hugo version，显示版本号即安装成功

升级 Hugo：下载新版覆盖C:\programs\hugo\hugo.exe

2 创建网站

2.1 生成网站

  1. 新建目录C:\code\loyayz\loyayz.github.io用于存放网站源码
  2. 执行命令生成网站
  3. 初始化 git 仓库，未安装 git 请先安装：Git 官网
1
2
3

cd C:\code\loyayz\loyayz.github.io
hugo new site . -f yml
git init

2.2 使用主题

  1. 下载：在官网 挑选主题

22/06/03 updated：如果你喜欢本站的风格，可以使用我的主题 PaperModx

1

git submodule add --depth=1 https://github.com/loyayz/hugo-PaperModx.git themes/PaperModx

本次使用 PaperMod

1

git submodule add --depth=1 https://github.com/adityatelange/hugo-PaperMod.git themes/PaperMod
  1. 修改网站配置：我是直接用示例配置 覆盖后再修改
./config.yml
  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109

baseURL: "https://loyayz.github.io/"
title: loyayz
theme: PaperModx
paginate: 10

enableInlineShortcodes: true
enableRobotsTXT: true
enableEmoji: true
pygmentsUseClasses: true
hasCJKLanguage: true
defaultContentLanguage: zh
timeZone: "Asia/Shanghai"

buildDrafts: false
buildFuture: false
buildExpired: false

minify:
    disableXML: true
    # minifyOutput: true

languages:
    zh:
        languageName: "中文"
        weight: 1
        taxonomies:
            category: categories
            tag: tags

menu:
    main:
        - name: 文章
          url: posts/
          weight: 1
        - name: 分类
          url: categories/
          weight: 2
        - name: 标签
          url: tags/
          weight: 3

outputs:
    home:
        - HTML
        - RSS
        - JSON

params:
    env: production
    title: "loyayz's blog"
    description: "loyayz's blog - https://loyayz.com"
    author: loyayz
    images: ["papermod-cover.png"]
    keywords: [loyayz,ideaworlds,simpleframework]
    DateFormat: "2006-01-02"
    ShowReadingTime: false
    ShowShareButtons: false
    ShowCodeCopyButtons: true
    ShowFullTextinRSS: false
    defaultTheme: auto
    disableThemeToggle: false
    disableSpecial1stPost: true
    disableScrollToTop: false
    disableAnchoredHeadings: false
    hideMeta: false
    hideSummary: false
    showtoc: true
    tocopen: false
    ShowPostNavLinks: true
    ShowBreadCrumbs: true
    ShowWordCount: false
    ShowRssButtonInSectionTermList: false
    comments: false
    hideFooter: true
    
    #homeInfoParams:
    #    Title: ""
    #    Content: 
    socialIcons:
        - name: github
          url: "https://github.com/loyayz"
        - name: email
          url: "mailto:loyayz@foxmail.com"
        - name: RsS
          url: "index.xml"        

markup:
    goldmark:
        renderer:
            unsafe: true
    highlight:
        codeFences: true
        guessSyntax: true
        lineNos: true
        style: monokai

privacy:
    disqus:
        disable: true
    googleAnalytics:
        disable: true
    instagram:
        disable: true
    twitter:
        disable: true
    vimeo:
        disable: true
    youtube:
        disable: true
  1. 拓展：如下新建文件方便拓展custom.css、extend_head.html、extend_footer.html
 1
 2
 3
 4
 5
 6
 7
 8
 9
10

.(loyayz.github.io)
├── config.yml
├── assets/
│   └── css/
│       └── extended/
│          └── custom.css
└── layouts
    └── partials
        ├── extend_footer.html
        └── extend_head.html

2.3 本地调试

命令行内执行命令后，在浏览器打开http://localhost:1313可预览网站

1

hugo server -D

3 部署到 Github Pages

3.1 新建脚本

  • Windows 一键提交脚本
./deploy.bat
1
2
3
4

@echo off
git add .
git commit -m "update"
git push
  • Linux 一键提交脚本
./deploy.sh
1
2
3
4

#!/bin/sh
git add .
git commit -m "update"
git push
  • GitHub Action 自动化部署脚本
./.github/workflows/gh-pages.yml
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32

name: github pages

on:
  push:
    branches:
      - master
  pull_request:

jobs:
  deploy:
    runs-on: ubuntu-20.04
    steps:
      - uses: actions/checkout@v2
        with:
          submodules: true
          fetch-depth: 1

      - name: Setup Hugo
        uses: peaceiris/actions-hugo@v2
        with:
          hugo-version: 'latest'
          # extended: true

      - name: Build
        run: hugo --minify

      - name: Deploy
        uses: peaceiris/actions-gh-pages@v3
        if: github.ref == 'refs/heads/master'
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./public

3.2 创建远程仓库

  1. 创建远程仓库：打开 GitHub 创建仓库，仓库名为loyayz.github.io其他都不选
  2. 新建.gitignore文件避免误操作提交文件
./.gitignore
1
2
3
4
5
6
7

public/
.idea/*
.vscode/*
!.vscode/settings.json
!.vscode/tasks.json
!.vscode/launch.json
!.vscode/extensions.json
  1. 关联本地和远程仓库，提交并推送到 Github
1
2
3
4
5

git add .
git commit -m "init"
git branch -M master
git remote add origin https://github.com/loyayz/loyayz.github.io.git
git push --set-upstream origin master
  1. 新建仓库说明文档
./README.md
1
2
3
4
5
6
7
8
9

本仓库使用 git submodule 引用主题仓库，因此 git clone 本仓库后需要再执行下句命令

git submodule update --init --recursive

后续若要更新主题，执行下句命令

git submodule update --remote --merge

部署：双击`deploy.bat`或执行命令`sh deploy.sh`
  1. 双击deploy.bat推送到 Github 触发自动化部署

3.3 修改 Github Pages

GitHub Action默认生成网站到gh-pages分支，因此需要修改Github Pages来源

  1. 浏览器打开远程仓库，进入设置页面：Settings -> Pages
  2. 将Source 分支中的master换成gh-pages
  3. 浏览器打开链接https://loyayz.github.io即可看到网站

4 创建文章

  1. 执行命令行启动服务，浏览器打开http://localhost:1313预览网站
1

hugo server -D
  1. 打开另一个命令行执行命令创建文章，网站将实时显示新的文章
1

hugo new posts/website/hugo-init.md
  1. 编辑文章
./content/posts/website/hugo-init.md
 1
 2
 3
 4
 5
 6
 7
 8
 9
10

---
title: "Hugo Github Pages 网站搭建"
date: 2022-05-27
draft: false
isCJKLanguage: true
tags: ["hugo"]
categories: ["website"]
---

基于 [Hugo](https://gohugo.io) 搭建并部署在 [Github Pages](https://pages.github.com)

注意：draft需改为false表示该文章不是草稿，否则推送到远程仓库后不会部署该文章

  1. 双击deploy.bat部署，稍等几秒后刷新https://loyayz.github.io即可看到网站新内容