github pages：使用 Hugo 搭建个人网站、网上商城
使用 Github、Hugo 搭建个人博客
关键字：开源 博客 框架
1、GitHub Pages
GitHub Pages 文档(英文)：https://docs.github.com/en/pages
GitHub Pages 文档(中文)：https://docs.github.com/zh/pages
GitHub Pages 是通过 GitHub 托管和发布的公共网站，本质上是一个静态网站托管系统，可以用来搭建个人主页、博客 等。
- 搭建简单而且免费；
- 支持静态脚本；
- 可以绑定你的域名；
- DIY自由发挥，动手实践一些有意思的东西 git，markdown，bootstrap，jekyll
- 理想写博客环境，git + github + markdown + jekyll
Git、GitHub、GitHub Pages
- Git 是一个开源的分布式版本控制系统。
- GitHub 是托管各种 git 库的站点。
- GitHub Pages 是免费的静态站点。可以免费托管、自带主题、支持自制页面和Jekyll。
Github Pages 教程
- 什么是 GitHub Pages
- 创建GitHub Pages网站
- GitHub Pages 限制
- 使用自定义工作流
- 配置发布源
- 删除GitHub Pages 站点
- 取消发布 GitHub Pages 站点
- 创建自定义 404 页面
- 使用 HTTPS 保护
- 子模块与 GitHub Pages 配合使用
- 排查 404 错误
配置 自定义 域
示例：创建 Github Pages
首先需要 github 账号，没有就注册一个，然后创建一个新的仓库。在任何页面的右上角选择 + ，单击 新建仓库。输入仓库名，仓库名格式必须是 username.github.io 形式。
然后勾选 "添加 README.txt"
进入新建的仓库，点击 设置，按要求修改，修改完成后等几分钟就可以看到发布的域名。
更改标题和说明。单击仓库的 “代码” 选项卡，添加 _config.yml文件，编辑_config.yml 添加如下内容，编辑完文件后，单击“提交更改”
theme: jekyll-theme-minimal
title: xxx 的 github pages 主页
description: xxx 的 github pages 主页
站点添加主题：使用 Jekyll 向 GitHub Pages 站点添加主题 - GitHub 文档
网站的 2种 pages 模式
两种 pages 模式
- 个人/公司 站点：User/Organization Pages。
使用自己的用户名，每个用户名下面只能建立一个；主干上内容被用来构建和发布页面 - 项目 站点：Project Pages。gh-pages 分支 用于构建和发布；
如果user/org pages使用了独立域名，那么托管在账户下的所有project pages将使用相同的域名进行重定向，除非project pages使用了自己的独立域名；
如果没有使用独立域名，project pages将通过子路径的形式提供服务http://username.github.com/projectname；
自定义404页面只能在独立域名下使用，否则会使用User Pages 404；
创建网站步骤：
命令：git clone https://github.com/username/project.git project
命令：git checkout --orphan gh-pages // 通过 --orphan 参数创建无历史记录无父提交的空白分支
命令：git rm -rf .
命令：git add . //添加远程不存在的git文件
命令：git status //查看本地自己修改了多少文件
命令：git commit -a -m "第一个页面" // -a 参数直接提交所有已追踪的修改（跳过 git add）
命令：git push origin gh-pages //把本地的 gh-pages 分支同步到远程 GitHub
推送成功后，GitHub 会自动启用 Pages 服务
主站、二级页面
可以通过 User/Organization Pages 建立主站，而通过 Project Pages 挂载二级应用页面。
2、搭建 "个人主页、博客"
使用 Github Pages 创建并部署网站。
安装 git 工具：https://git-scm.com/downloads
github 桌面版：https://desktop.github.com/
搭建静态页面网站的技术有很多，目前有三种主流技术选型，这三个都是静态网站生成器。
- Hugo 是使用 Go 语言编写的静态网站生成器。生成速度秒级（几千页也瞬间生成），主题超多，一键安装，不用配置复杂环境，一个二进制文件就能跑。适合：博客、文档、作品集、公司官网。
- jekyll 是使用 Ruby 语言编写的静态网站生成器。GitHub 官方默认。插件生态成熟，适合写博客、文档。
- VuePress / VitePress（文档类最强）。界面清爽现代，专门做文档网站，基于 Vue，易定制。适合：项目文档、教程站、知识库
- Hexo 基于 nodejs，国内最流行。中文教程最多，主题多、插件多。适合：个人博客。
方法 1：使用 Jekyll 搭建网站
官网
Jekyll 是一个简单的博客形态的静态站点生产机器。它有一个模版目录，其中包含原始文本格式的文档，通过一个转换器（如 Markdown）和 Liquid 渲染器转化成一个完整的可发布的静态网站，你可以发布在任何你喜爱的服务器上。Jekyll 也可以运行在 GitHub Page 上，也就是说，你可以使用 GitHub 的服务来搭建你的项目页面、博客或者网站，而且是完全免费的。说白了就是，只要安装Jekyll的规范和结构，不用写html，就可以生成网站。
jekyll 与 github 的关系：GitHub Pages一个由 GitHub 提供的用于托管项目主页或博客的服务，jekyll 是后台所运行的引擎。
GitHub Pages 建立个人网站详细教程：https://zhuanlan.zhihu.com/p/58229299
使用 Jekyll 设置站点
- GitHub Pages 和 Jekyll
- 用 Jekyll 创建网站
- 本地测试你的 GitHub Pages 网站
- 使用 Jekyll 向你的 GitHub Pages 网站添加内容
- 使用 Jekyll 为你的 GitHub Pages 网站设置 Markdown 处理器
- 使用 Jekyll 向你的 GitHub Pages 网站添加主题
- 排查 Jekyll 构建错误
方法 2：使用 Hugo (雨果) 部署
Hugo 官网描述说是世界上最快的、最受欢迎的开源静态网站生成器。hugo 是用Go语言编写的静态网页生成器，只需要一个命令 hugo 就可以在几秒钟内生成一个静态的博客页面。
学习曲线
hugo 文档
Hugo 静态网站构建实战手册：https://jimmysong.io/zh/book/hugo-handbook/
hugo-handbook：https://rootsongjc.gitbooks.io/hugo-handbook/content/
HUGO 中文文档：https://hugo.opendocs.io/
- hugo 文档：https://gohugo.io/documentation/
- hugo 主题：https://themes.gohugo.io/
- hugo github：https://github.com/gohugoio/hugo
hugo 官网文档：
- hugo 关于：https://gohugo.io/about/
- hugo 命令行：https://gohugo.io/commands/
- hugo 配置：https://gohugo.io/configuration/
- hugo 的 content 管理：https://gohugo.io/configuration/
- hugo 的 功能：https://gohugo.io/functions/
- hugo 快速入门：https://gohugo.io/getting-started/
- hugo 开发者工具：https://gohugo.io/tools/
- 主机和部署：https://gohugo.io/host-and-deploy/
- 使用 asset pipelines 来转换和优化 images, stylesheets, JavaScript.
- hugo 的 模块：https://gohugo.io/hugo-modules/
- hugo 的 模板：https://gohugo.io/templates/
- 短代码 (嵌入 视频，图片)：https://gohugo.io/shortcodes/
- hugo 快速参考：https://gohugo.io/quick-reference/
- 使用 HTML 代替 markdown：https://gohugo.io/render-hooks/
- 故障排除：https://gohugo.io/troubleshooting/
快速入门
创建一个 项目(网站)。示例：创建带有 Ananke 主题的 Hugo 项目。
ananke 从 v2.12.1 开始移除了 exampleSite 文件夹，取而代之的是 site 文件夹，内容页变成了 anaanke 主题的说明和安装文档，不再是：https://ananke-theme.netlify.app/ 。后面会下载 2.12.0 版本演示这个效果。。。
hugo new project hugo_project // 创建 项目(网站) 骨架。
cd hugo_project
git init -b main // 初始化目录为一个空的 Git 仓库
// 将 Ananke主题克隆到 themes 目录中，并将其作为Git子模块添加到项目中。
git submodule add https://github.com/theNewDynamic/gohugo-theme-ananke.git themes/ananke
创建示例内容：把 网站根目录/themes/ananke/site/ 目录下的内容复制到网站根目录下
把 网站根目录/themes/ananke/doc目录 页复制到网站根目录下
修改 网站根目录/hugo.toml，添加一行 theme = 'ananke'
修改 网站根目录/config/_default/hugo.toml，修改 contentDir = "docs"
hugo server //启动 Hugo 开发服务器。按 Ctrl + C 可停止。
效果如下：
从 github 下载 gohugo-theme-ananke-2.11.2.zip 版本，解压到 网站根目录/themes/ 目录下
再把 exampleSite 下示例内容复制到网站的根目录下
把 config.toml 复制到 hugo.toml 中，并删除重复配置，修改使用的主题
然后执行：hugo server 执行后打开网站如下：
添加 内容
执行：hugo new content content/en/post/my-first-post.md
Hugo 会在 content/en/post/ 目录中创建 my-first-post.md 文件。
可以在帖子正文中添加一些 markdown，注意：不要更改
draft的值(默认是 true)。+++
title = 'My First Post'
date = 2024-01-14T07:07:07+01:00
draft = true
+++
## Introduction测试测试测试测试测试
测试测试测试测试测试
测试测试测试测试测试
测试测试测试测试测试
测试测试测试测试测试This is **bold** text, and this is *emphasized* text.
Visit the [Hugo](https://gohugo.io) website!
保存文件后，启动 Hugo 的开发服务器。可以运行以下任一命令来包含草稿内容。
hugo server --buildDrafts
hugo server -D
可以不断的添加和更改内容，当对新内容满意后，将
draft参数的值设置为 false
配置 项目(网站)
在项目的根目录打开 项目(网站) 配置文件（hugo.toml）。注意：baseURL 必须以 / 结尾。
启动 Hugo 的开发服务器查看更改：hugo server -D
发布 项目(网站)
执行命令：hugo
执行完成后，Hugo 会将所有构建工件渲染到项目根目录中的 public 目录。这包括每个网站的 HTML 文件，以及图片、CSS 和 JavaScript 等资源。
使用 phpstudy 启动网站，首先 启动 nginx
再更改网站根目录
浏览器查看：http://127.0.0.1/
基本用法、目录结构
- 基本用法：https://gohugo.io/getting-started/usage/
- 目录结构：https://gohugo.io/getting-started/directory-structure/
hugo version
hugo help
hugo server --help
hugo build --help
hugo build --buildDrafts # or -D
hugo build --buildExpired # or -E
hugo build --buildFuture # or -F
hugo server --navigateToChanged # 编辑内容后浏览器自动更新页面
准备部署网站时，直接执行：hugo
每个 Hugo 项目都是一个目录，包含子目录，负责内容、结构、行为和展示。Hugo 在创建新项目时会生成一个项目骨架。例如执行命令 hugo new project my-project 创建的目录结构如下：
my-project/
├── archetypes/ // 内容模板。 详情：details。
│ └── default.md
├── assets/ //资源文件夹(图片、CSS、Sass、JavaScript、TypeScript等) 详情 details。
├── config/ <-- 项目配置(会覆盖 根目录下的 hugo.toml 中的配置项) 详情 details。
│ └── _default/ Hugo 会 递归解析 config 目录
│ └── hugo.toml
├── content/ // 页面资源(通常是 Markdown)。即内容(网页)源文件。详情 details.
├── data/ //数据文件，被用来补充内容、配置、本地化和导航。详情 details.
├── i18n/ // 多语言项目的翻译表。详情 details.├── layouts/ // 网站布局。详情 details.
├── public/ <-- 运行hugo build或hugo server命令时生成。目录中是要发布的网站。
├── resources/ <-- 运行hugo build或hugo server命令时生成。包含CSS和图片。
├── static/ <-- 构建项目时会被复制到public目录。例如 .ico、robots.txt、验证网站所有权的文件。├── themes/ // 主题(模块) 目录。每个主题在自己的子目录中。
└── hugo.toml <-- 项目(网站) 根目录下的配置文件
运行 hugo build 或 hugo server 命令时，Hugo 会创建 public、resources 目录：
将两个或更多目录挂载到同一位置。假设你的主目录在一个目录中包含一个 Hugo 项目，另一个目录中包含共享内容：
home/
└── user/
├── my-project/
│ ├── content/
│ │ ├── books/
│ │ │ ├── _index.md
│ │ │ ├── book-1.md
│ │ │ └── book-2.md
│ │ └── _index.md
│ ├── themes/
│ │ └── my-theme/
│ └── hugo.toml
└── shared-content/
└── films/
├── _index.md
├── film-1.md
└── film-2.md
可以用 mounts 来包含 shared-content 目录。在项目配置中添加
toml 格式配置：
[module]
[[module.mounts]]
source = 'content'
target = 'content'
[[module.mounts]]
source = '/home/user/shared-content'
target = 'content'
json 格式配置
{
"module": {
"mounts": [
{
"source": "content",
"target": "content"
},
{
"source": "/home/user/shared-content",
"target": "content"
}
]
}
}
挂载后，统一文件系统具有以下结构：
home/
└── user/
└── my-project/
├── content/
│ ├── books/
│ │ ├── _index.md
│ │ ├── book-1.md
│ │ └── book-2.md
│ ├── films/
│ │ ├── _index.md
│ │ ├── film-1.md
│ │ └── film-2.md
│ └── _index.md
├── themes/
│ └── my-theme/
└── hugo.toml
也可以用 Hugo 模块从 Git 仓库挂载目录。
配置文件
在版本 0.109.0 及更早版本中，项目配置文件名字是 config.toml，虽然仍然可以使用这个名字，但建议切换到较新的命名方式 hugo.toml。如果同时存在这两个文件，Hugo 会优先加载 hugo.toml 文件。如果只有 config.toml 文件存在，则 Hugo 只加载该文件。
如果使用 config.yml 配置文件需要注意：yml 是缩进敏感
在构建项目时使用不同的配置文件，可以使用 --config 标志：hugo build --config other.toml
将两个或多个配置文件合并，顺序从左到右：hugo build --config a.toml,b.yaml,c.json
Hugo 递归解析 config 目录，所以可以将文件组织成子目录。例如：
my-project/
└── config/
├── _default/
│ ├── hugo.toml
│ ├── menus.en.toml
│ ├── menus.de.toml
│ └── params.toml
├── production/
│ ├── hugo.toml
│ └── params.toml
└── staging/
├── hugo.toml
└── params.tomlHugo 完全支持 JSON 格式配置，默认配置文件可以是 hugo.json，直接替换 hugo.toml / hugo.yaml 即可使用。
在 Hugo 项目根目录新建文件 hugo.json 并粘贴以下内容：
{
"baseURL": "https://example.com/",
"languageCode": "zh-CN",
"title": "我的Hugo网站",
"theme": "",
"publishDir": "public"
}完整常用配置（推荐）
{
"baseURL": "https://你的域名.com/",
"languageCode": "zh-CN",
"title": "网站标题",
"theme": "ananke",
"publishDir": "public",
"buildDrafts": false,
"buildFuture": false,
"buildExpired": false,
"enableGitInfo": false,
"disableKinds": [],
"markup": {
"goldmark": {
"renderer": {
"unsafe": true
}
}
},
"server": {
"port": 1313,
"openBrowser": true
}
}baseURL 网站根地址（部署必填）
languageCode 网站语言（中文用 zh-CN）
title 网站标题
theme 使用的主题名称
publishDir 构建输出目录（默认 public）
buildDrafts 是否构建草稿页面
server.port 本地预览端口
markup.goldmark Markdown 渲染配置
在项目根目录运行命令，查看配置是否正常加载：hugo config
- 配置文件名必须是：
hugo.json - 放在项目根目录，直接替代
toml/yaml - 格式严格遵循 JSON，不能有多余逗号
- 运行
hugo config可快速验证生效
术语表：https://gohugo.io/quick-reference/glossary/
关于Hugo的教程和书籍列表
- Hugo In Action Home Page：https://www.manning.com/books/hugo-in-action
- Hugo In Action 主页：https://www.manning.com/books/hugo-in-action
hugo 主题
官网主题：https://themes.gohugo.io/
github 搜索：https://github.com/search?q=hugo+theme&type=repositories
好看的 Hugo 主题：https://www.zhihu.com/question/266175192
官网有好多hugo 主题，也可以在 https://github.com/ 中搜索关键词：hugo theme 或者使用搜索引擎搜索：hugo theme site:github.com
示例： 安装 hugo-theme-stack 主题：https://demo.stack.jimmycai.com/
hugo-theme-stack 主题 文档
通过 中文 文档可知有三种安装方式
- 方式 1：使用 starter template 启动模板可以快速搭建一个使用此主题的 Hugo 网站。该模板已配置好了 GitHub Action，在此基础上您对网站所做的任何更改都会自动构建并推送到 GitHub Pages 上。
- 方式 2：主题作为 Hugo 模块 来使用。注意：使用此方法时 themes 目录下不会有任何文件。将来，如果主题发布了新的大版本，只需要手动更新 path 字段中的版本号即可。
hugo-theme-stack 源码：https://github.com/CaiJimmy/hugo-theme-stack
公共模板：https://github.com/CaiJimmy/hugo-theme-stack-starter在 Hugo 创建的站点的根目录下运行以下命令
首先创建的站点初始化为 Hugo 模块：hugo mod init github.com/me/my-new-blog
然后通过在站点的配置文件中的 module 部分添加以下行来导入主题作为依赖项。：
# hugo.toml
[[module.imports]]
path = "github.com/CaiJimmy/hugo-theme-stack/v4"这会使 Hugo 使用主题最新的稳定 v4 版本（可以在 release 页面上找到）。
要将主题更新到最新版本，则运行以下命令：
hugo mod get -u github.com/CaiJimmy/hugo-theme-stack/v4
hugo mod tidy这时使用 hugo server -D 启动时，网站只是一个空壳，没有示例内容，
需要把公共模板中的 assets、config、content 文件夹复制到 站点跟目录下。
然后再启动 hugo server -D效果如下：
如果想要修改主题，则需要将想要修改的文件复制到 layouts 目录下对应的目录中。
例如，要修改 themes/hugo-theme-stack/layouts/_partials/header.html 文件，您需要将其复制到 layouts/_partials/header.html 并在那里进行修改（从主题仓库中复制原始代码）。这同样适用于 assets 和 static 目录。方式 3：如果安装有 git，并且已经使用 git 管理创建的站点，可以运行以下命令将主题添加为子模块：git submodule add https://github.com/CaiJimmy/hugo-theme-stack/ themes/hugo-theme-stack
把 demo 目录下的 文件复制到网站的根目录下
修改 网站根目录/config/_default/hugo.toml
修改完保存，然后网站根目录执行命令：hugo server -D 即可看到效果
方式 4：从 release 页面 下载主题并将其解压到
themes/hugo-theme-stack目录中。把 demo 中 文件复制到网站的根目录下。
再修改 网站根目录/config/_default/hugo.toml
方式3 和 方式4 其实是同一种方式。。。
go.mod 文件只有 当主题 作为 hugo 模块使用时才有用，否则后缀mod结尾的文件可以忽略
hugo-theme-jane
网上商城
Hugo、Astro、Next.js 主题：https://themefisher.com/nextjs-templates
- Hugo：纯静态、最快、最简单、适合小商城、博客 + 商品、极简站。追求打开速度极快，不想写复杂代码，用 Markdown 写商品就行。
- Astro：现代、灵活、支持多框架、适合 颜值高、轻量交互的商城。文档：https://docs.astro.js.cn/en/getting-started/
- Next.js（全栈王者）：全功能、动态强、适合 复杂商城、多商品、需要登录 / 会员、优惠券、库存管理，想做真正的完整电商，愿意学习 React。文档：https://www.nextjs.cn/
hugo 电子商务主题：https://gethugothemes.com/categories/e-commerce
Vex (开源免费)
Vex 是一个 GitHub 开源，简洁多用途电商主题，它完全响应式，精心制作，包含产品展示、推荐和邮件订阅部分。
电商功能集成（购物车 + 支付）
Hugo 是静态的，动态功能靠 JS + 第三方 API。
方案 A：Stripe 支付（最简单）
- 注册 Stripe
- 为每个商品生成 Payment Link
- 在商品 markdown 填入
stripe_link - 主题模板中渲染为「立即购买」按钮
方案 B：购物车 + Snipcart（推荐）
Snipcart 是专为静态站设计的购物车 JS 库。
注册 Snipcart → 获取 API Key
方案 C：结合 Shopify（商品多）
- Hugo 做展示页
- Shopify 做后台、库存、支付
- API 同步商品数据
Planty
Planty：https://jamstackthemes.dev/theme/planty/
github (好久没更新)：https://github.com/snipcart/stackbit-theme-planty
Adrian (付费)
完整电商布局、产品列表、购物车、响应式
Adrian - Hugo E-commerce(电子商务) theme ：https://themefisher.com/products/adrian-hugo
示例：使用 Hugo 创建静态网站
Github Pages 是一个静态网站托管系统，可以为每个仓库制作一个静态网页入口。它有两种存在方式：
- 识别 master branch 根目录下的：README.md 或者 index.html
- 识别 master branch 的 /docs 目录下的：README.md 或者 index.html
也就是说：可以把我们的静态网页直接存在 master branch，并在 Github Repository 的 Setting 页中打开 Github Pages 选项，就可以通过一个域名访问到我们的想要的网站了。
将 Hugo 部署为 GitHub Pages 项目或个人/组织站点，并使用 GitHub Actions 自动执行整个过程
- Prerequisites 先决条件
- Types of sites 网站类型
- Procedure 程序
- Customize the workflow 自定义工作流
- Additional resources 其他资源
安装 Hugo
安装：https://gohugo.io/installation/
- Windows：https://gohugo.io/installation/windows/
- Linux：https://gohugo.io/installation/linux/
- macOS：https://gohugo.io/installation/macos/
Hugo 有多个版本。
| Feature 特色 | 标准版 | 部署（1） | 扩展版 | 扩展 / 部署 |
|---|---|---|---|---|
| Core features 核心功能 | ✔️ | ✔️ | ✔️ | ✔️ |
| Direct cloud deployment (2) 直接云部署（2） |
❌ | ✔️ | ❌ | ✔️ |
| LibSass support (3) LibSass 支持（3） | ❌ | ❌ | ✔️ | ✔️ |
推荐安装 extended 或 extended/deploy 版本，
hugo 版本下载：https://github.com/gohugoio/hugo/releases
这里以 windows 版本为例，下载 扩展/部署 版本 hugo_extended_withdeploy_0.160.1_windows-amd64.zip，解压后，添加到 系统环境变量 PATH 中，然后 执行 hugo --help 或者 执行 hugo version 验证安装是否成功
使用 "hugo [command] --help" 查看对应命令的帮助。
C:\>hugo --help
hugo 是用于构建 Hugo 项目的主命令。
Hugo 是一款快速、灵活的静态网站生成器，由 spf13 及其好友使用 Go 语言开发。
完整文档可访问：https://gohugo.io/
用法：
hugo [flags]
hugo [command]
可用命令：
build 构建你的项目
completion 为指定的 shell 生成自动补全脚本
config 显示项目配置
convert 将前端格式转换为其他格式
env 显示版本和环境信息
gen 生成文档和语法高亮样式
help 查看任意命令的帮助信息
import 从其他系统导入项目
list 列出内容
mod 管理模块
new 创建新内容
server 启动嵌入式 Web 服务器
version 显示版本信息
参数（Flags）：
-b, --baseURL string 网站根目录的主机名（及路径），例如：https://spf13.com/
-D, --buildDrafts 包含标记为草稿的内容
-b, --buildExpired 包含已过期的内容
-F, --buildFuture 包含未来发布的内容
--cacheDir string 缓存目录的文件系统路径
--cleanDestinationDir 删除目标目录中不在静态目录中的文件
--clock string 设置 Hugo 使用的时钟，例如：--clock 2021-11-06T22:30:00+09:00
--config string 配置文件（默认为 hugo.yaml|json|toml）
--configDir string 配置目录（默认是 "config"）
-c, --contentDir string 内容目录的文件系统路径
-d, --destination string 写入文件的目标文件系统路径
--disableKinds strings 禁用不同类型的页面（home、RSS 等）
--enableGitInfo 向页面添加 Git 修订版本、作者、CODEOWNERS 信息
-e, --environment string 构建环境
--forceSyncStatic 静态文件变更时全部复制
--gc 构建后执行清理任务（删除未使用的缓存文件）
-h, --help 帮助信息
--ignoreCache 忽略缓存目录
--ignoreVendorPaths string 忽略匹配给定 Glob 模式的模块路径的供应商
-l, --layoutDir string 布局目录的文件系统路径
--loglevel string 日志级别（debug|info|warn|error）
--minify 对所有支持的输出格式（HTML、XML 等）进行最小化压缩
--noBuildLock 不创建 .hugo_build.lock 文件
--noChmod 不修改文件权限
--noTimes 不同步文件修改时间
--panicOnWarning 遇到第一个 WARNING 时直接 panic
--poll string 设置轮询间隔，例如 --poll 700ms，使用基于轮询的方式监控文件系统变更
--printI18nWarnings 打印缺失的翻译警告
--printMemoryUsage 按时间间隔打印内存使用情况
--printPathWarnings 打印重复模板路径等警告
--printUnusedTemplates 打印未使用模板的警告
--quiet 安静模式构建
--renderSegments strings 要渲染的分段（在分段配置中配置）
-M, --renderToMemory 渲染到内存（在服务器运行时非常实用）
-s, --source string 相对于文件系统的源文件路径
--templateMetrics 显示模板执行的指标
--templateMetricsHints 结合 --templateMetrics 计算一些改进提示
-t, --theme strings 使用的主题（位于 /themes/THEMENAME/ 目录下）
--themesDir string 主题目录的文件系统路径
--trace file 将跟踪信息写入文件（一般不常用）
-w, --watch 监控文件系统变更，按需重新创建
使用 "hugo [command] --help" 可查看某条命令的更多信息。hugo new site xxx 或者 hugo new project xxx 创建站点
hugo new xxx 创建 站点内容，即 网页内容文件。
安装 Git
- Hugo 项目通常需要 Git 进行版本控制和主题管理
熟悉命令行操作
- Windows 用户推荐使用 "PowerShell" 或 Linux 终端(如WSL或Git Bash) 执行hugo命令。
- 避免使用 命令提示符 或 Windows PowerShell，"PowerShell" 和 "Windows PowerShell" 是不同的应用程序。
创建 网站
hugo new site 命令创建一个新的 Hugo 网站，如果指定的目录不为空会报错。如果想要在非空目录中创建 Hugo 网站，可以先 hugo new site temp-site 创建一个临时的空目录，再将临时文件夹temp-site 中的内容移动到你想要的目标目录中。
- hugo new site 在指定的目录创建一个站点，新站点目前还没有内容和主题。
- 可以使用 hugo new [contentPath] 创建 站点内容(网页文件)
添加 ananke 主题，并启动
在流行框架的基础上搭建网站其实并不是一个技术活，千差万别的网站体验则主要体现在网站主题的设计上。Hugo 提供丰富多样的主题模板，可以在主题库搜索喜欢的主题进行安装：https://themes.gohugo.io/
示例：安装 https://github.com/theNewDynamic/gohugo-theme-ananke 主题
- 方法 1：作为 Hugo 模块（推荐），需要安装Go。
在项目的根目录初始化hugo模块系统：hugo mod init github.com/<your_user>/<your_project>
添加主题仓库到 config.toml 文件：theme = ["github.com/theNewDynamic/gohugo-theme-ananke"]- 方法 2：作为 git 子模块。在Hugo站点根目录中运行：git submodule add https://github.com/theNewDynamic/gohugo-theme-ananke.git themes/ananke
- 方法 3：直接把主题 clone 到 theme 目录下。示例克隆 jane 主题：git clone https://github.com/xianmin/hugo-theme-jane.git --depth=1 themes/jane
- git clone https://github.com/adityatelange/hugo-PaperMod themes/PaperMod --depth=1
git init
git submodule--helper add https://github.com/adityatelange/hugo-PaperMod.git themes/PaperMod --depth=1
hugo server -D 是用于在 Hugo 静态网站生成器中启动本地服务器的命令。
hugo: 是 Hugo 静态网站生成器的可执行命令。server: 是 Hugo 提供的一个子命令，用于启动本地开发服务器。-D（或--buildDrafts）: 是一个可选参数，用于告诉 Hugo 在构建网站时包括草稿（draft）文章。可以在预览网站时渲染未发布的草稿文档。
为了成功运行 hugo server -D 命令，需要先进入 Hugo 项目的根目录，然后再运行该命令。成功运行后将启动一个本地开发服务器，并自动监视你的 Hugo 项目文件夹中的更改。这意味着每当你编辑或添加新的内容时，服务器都会重新加载并显示最新的更改。在浏览器中打开 http://localhost:1313 即可访问 Hugo 生成的网站。
启动：hugo server 后访问效果如下。
添加 博文，并启动
进入web 站点根目录，执行命令 hugo new post/test.md 或者 hugo new post/2021/test.md 创建博文。创建的文章会自动生成一部分文本。
如果嫌弃手动添加麻烦，目录 themes\ananke\exampleSite 是个样例站点，可以直接把 exampleSite 目录下的 "content目录 和 config.toml文件" 复制到自己创建站点的 根目录下，然后把 config.toml 里面的内容合并到 hugo.toml 里面，然后删除 config.toml
再次启动：hugo server 后访问效果如下
常用 Git 命令速查
git config --global http.proxy http://127.0.0.1:7897
git config --global https.proxy http://127.0.0.1:7897
初始化 & 远程关联
git init # 初始化本地仓库
git init -b main # 初始化并直接创建 main 分支
git remote add origin 地址 # 绑定远程仓库（origin 是默认名）
git remote -v # 查看当前绑定的远程地址
git remote set-url origin 新地址 # 修改远程地址git remote remove origin # 删除远程关联
git remote set-url origin 新地址 # 修改远程地址
查看远程仓库信息
git remote -v // 最常用，显示当前项目绑定的远程仓库地址（fetch = 拉取、push = 推送）
git remote show origin // 查看远程仓库详细信息
git remote // 只看远程仓库名字
查看状态
git status # 查看文件修改状态
git diff # 查看具体修改内容
git log # 查看提交历史
git log --oneline # 简洁版提交历史
提交代码
git add . # 添加当前目录所有修改
git add 文件名 # 只添加某个文件git rm 文件名
git rm -r 文件夹名
只想删除 Git 记录，但保留本地文件（文件还在电脑里，只是不被 Git 管理）
git rm --cached 文件名git commit -m "说明" # 提交到本地仓库
git push origin maingit status # 查看修改状态
git log # 查看提交记录
git log --oneline # 简洁版记录
第一次推送 / 绑定分支
git push -u origin main # 第一次推送并绑定分支，以后直接
git push即可。git push # 推送到远程
git push -f origin main # 强制推送，覆盖远程
git stash # 暂存当前修改
git stash pop # 恢复暂存
拉取代码
git pull # 拉取远程最新代码并合并
git pull origin main --allow-unrelated-histories // 拉取远程 main 分支
git fetch # 只拉取不合并（更安全）
分支操作
git branch # 查看 本地 都有哪些分支
git branch -r # 查看 远程 都有哪些分支
git checkout gh-pages 或 git checkout origin/gh-pages # 把远程gh-pages分支拉到本地
git branch -M main # 把本地分支改名为 main
git branch 新分支名 # 创建分支git switch gh-pages # 新版 git 使用 switch 代替 checkout 切换分支
git switch 分支名 # 切换分支
git switch 分支名 # 新版切换分支
git merge 分支名 # 把别的分支合并到当前git clone https://github.com/xxx/xxx.git project
git checkout --orphan gh-pages // 通过 --orphan 参数创建无历史记录无父提交的空白分支git branch -vv # 查看本地分支与远程分支的对应关系
git branch -a -vv # 查看所有（本地 + 远程 + 对应关系）
git remote show origin # 只看 “关联信息” 极简版
撤销 / 回退
git checkout -- 文件名 # 放弃某个文件的修改。示例：git checkout -- index.html
git restore 文件名 # 放弃某个文件的修改。
git reset HEAD 文件名 # 取消 add
git reset --hard HEAD^ # 回退到上一个版本（谨慎）
git reset HEAD 文件名 # 取消 git add
git checkout . # 放弃所有未提交修改
使用 git 把指定目录关联到远程仓库
cd 目标目录
git init // 初始化 git (第一次才需要)，默认主分支是 main。
git init -b main // 初始化 git 仓库并直接创建主分支main。
git remote add origin 远程仓库地址 // 给本地仓库关联一个远程仓库
示例：git remote add origin https://gitee.com/abc/myproject.git
git remote -v 查看是否关联成功
关联成功后就可以正常提交了
git add .
git commit -m "首次提交"
git push -u origin main //第一次推送 + 永久绑定分支。执行命令后以后直接 git push 就行！
git push -f origin main // -f 强制推送，会直接覆盖远程仓库的全部代码。
重新关联时，需要先删除旧关联，再重新关联。
git remote remove origin
git remote add origin 你的新地址创建 网站 步骤：
hugo new site my_hugo_web_src # 创建名为 my_hugo_web_src 的目录，作为根目录
cd my_hugo_web_src
git init //初始化仓库
git remote add origin https://github.com/xxx/xxx.github.io.git //链接远程仓库
git add . // 添加git rm -rf . // 删除
git status // 查看本地自己修改了多少文件
git commit -m "first commit"git commit -a -m "第一个页面" // -a 参数直接提交所有已追踪的修改（跳过
git add）git push origin gh-pages // 把本地的 gh-pages 分支同步到远程 GitHub
git push -u origin main //第一次推送 + 永久绑定分支。执行命令后以后直接 git push 就行！在此之后更新文章，使用hugo生成新的静态页面，并使用 git push 进行同步
cd my_hugo_web_src
git add .
git status
git commit -m "add blog post"
git push推送成功后，GitHub 会自动启用 Pages 服务
将网站部署到 Github Pages
Hugo 提供非常详尽的 GitHub Pages 部署指引。步骤如下：
- 1. 部署到 Github Pages 时，需要把 hugo.toml 文件中 baseURL 修改为自己博客的网址，譬如 baseURL = "https://caecarxu.github.io/"
- 2. 然后执行 hugo 命令生成静态页面文件，执行成功后出现一个 public 文件夹，里面就是网站的静态页面文件
- 3. 进入 public 目录，把目录中所有文件上传到 xxx.github.io 的仓库中。
进入 public 文件夹，使用 git 上传文件
cd public
git init ##初始化仓库
git remote add origin https://github.com/caecarxu/caecarxu.github.io.git ##链接远程仓库
git add .
git commit -m "first commit"
git push -u origin main
在此之后更新文章，使用hugo生成新的静态页面，并使用 git push 进行同步
cd public
git add .
git status
git commit -m "add blog post"
git push - 4. 每当写完文章，运行
hugo命令，Hugo 将自动生成静态网站到public文件夹中，只需要将该文件夹的内容发布在网络上即可。
部署成功后，网站依然略显简陋，可以通过配置 hugo.toml 中的配置项增加你想要的功能
增加 About 页面
博客默认菜单只有 4 个页面选项：Home, Archives, Tags, Categories，如果想新增 About 页面，仅需以下 2 步：
- 新建 about 文件：hugo new about.md，命令将会创建
contents/about.md文件 - 在 about.md 文件的 Front Matter 中输入以下配置：
---
title: "About"
date: 2021-12-19T13:51:21+08:00
draft: false
menu: "main" # 在 main 新增选项
weight: 50 # About 选项的位置
---
重新部署博客，可以看到新增了 About 选项。
转移目录至侧边栏
添加评论系统
giscus 是一个基于 GitHub Discussions 的评论系统，包含多种主题可供选择。你应该首先跟随 utterances 配置方法了解可选配置项，并根据个人偏好自动生成一份包含个性化配置属性的 HTML 代码：
博客使用 utterances 作为评论系统：https://juejin.cn/post/6844903834712539150
giscus：https://giscus.app/zh-CN
给 hugo 博客添加评论功能：https://segmentfault.com/a/1190000039217582
SEO 优化
写博客不只是为了记录，也是为了更好地去(man)帮(zu)助(xu)别(rong)人(xin)，为了让搜索引擎更好地收录你的博客文章，还需要做一些搜索引擎优化(SEO)，Even 主题已经提供了丰富的 SEO 优化手段，我们只需设置一些配置项。
- 最好在
archtypes/default.md中增加keywords和description配置，便于搜索引擎索引。
keywords: []
description: "" -
网站目录 增加 robots 文件，便于爬虫爬取网页内容。不过 Even 已经提供了 robots 和相关的网页地图设置，因此这里无需操作。
-
提交博客地址到搜索引擎 Google
-
配置 Google Analytics，将获取到的 Tracking ID 配置到
config.toml中。
googleAnalytics = "" # UA-XXXXXXXX-X
使用 GitHub Action 自动发布文章
这里主要参考 搭建个人blog, 使用 master 分支发布文章，使用一个新的 source 分支进行写作，写作完成后上传 source ，GitHub Action 自动将 source 分支的 publish 文件夹拷贝到 master 分支，从而完成文章的发布。
主要步骤如下：
1. 在 GitHub 上的个人网站仓库
xxx.github.io新建source分支
2. 清除文件夹
xxx.github.io中的内容，并将个人网站quickstart中的所有内容 copy 到xxx.github.io：
git clone --branch=source https://github.com/xxx/xxx.github.io.git
rm -rf woot!*
cp -rf quickstart/* http://xxx.github.io
3. 生成
ACTIONS_DEPLOY_KEY
ssh-keygen -t rsa -b 4096 -C "$(git config user.email)" -f gh-pages -N ""
将生成的私钥文件gh-pages(注意不是公钥gh-pages.pub) 中的内容复制填写到 GitHub 仓库设置中，即在xxx.github.io项目主页中，找到 Repository Settings -> Secrets -> 添加这个私钥的内容并命名为ACTIONS_DEPLOY_KEY。
然后在xxx.github.io项目主页中，找到 Repository Settings -> Deploy Keys -> 添加这个公钥的内容，命名为ACTIONS_DEPLOY_KEY，并勾选 Allow write access。
4. 配置 workflow
创建 workflow 文件
mkdir -p .github/workflows/
touch .github/workflows/main.yml
在main.yaml中撰写 workflow，内容如下：
name: github pages
on:
push:
branches:
- source
jobs:
build-deploy:
runs-on: ubuntu-18.04
steps:
- uses: actions/checkout@master
- name: Checkout submodules
shell: bash
run: |
auth_header="$(git config --local --get http.https://github.com/.extraheader)"
git submodule sync --recursive
git -c "http.extraheader=$auth_header" -c protocol.version=2 submodule update --init --force --recursive --depth=1
- name: Setup Hugo
uses: peaceiris/actions-hugo@v2
with:
hugo-version: 'latest'
extended: true
- name: Build
run: hugo --gc --minify --cleanDestinationDir
- name: Deploy
uses: peaceiris/actions-gh-pages@v3
with:
deploy_key: ${{ secrets.ACTIONS_DEPLOY_KEY }}
publish_dir: ./public
publish_branch: main
注意，如果你的仓库是master分支作为主分支，将publish_branch后面的main修改为master;
5. 将 source 分支发送到远程
发送脚本deploy.sh:
#!/bin/bash
git add .
git commit -m "update article"
git push
推送到远程分支：
sh deploy.sh
推送成功后，可以在项目主页中的 action 里面查看自动部署是否成功，即 https://github.com/xxx/xxx.github.io/actions；
自动化 部署
：https://blog.taoluyuan.com/posts/github-workflows/
可以通过 Github workflows CI/CD 自动化部署 Github Pages hugo 免费博客
GitHub Actions 介绍
- GitHub 文档：https://docs.github.com/zh/actions/learn-github-actions/understanding-github-actions
- 官方介绍:
GitHub Actions是一种持续集成和持续交付 (CI/CD) 平台，可用于自动执行生成、测试和部署管道。 可以创建工作流程来构建和测试存储库的每个拉取请求，或将合并的拉取请求部署到生产环境
流程及原理介绍
主要介绍使用GitHub Actions 来实现自动化部署博客网站 ,静态网站生成使用的是Hugo,部署使用的是Github pages,并且使用自定义域名。
- 本地写hugo-blog 博客,hugo-blog 是一个hugo的博客模板,使用
hugo new site hugo-blog命令创建,可以在里面写markdown文件 - 写好后推送到github hugo-blog 仓库,触发github actions ci/cd,执行hugo命令生成静态网站,并且推送到github-pages 仓库
- github-pages 仓库接收到推送后,会自动部署到github pages,公网可以通过 github pages 域名 访问,也可以通过CNAME配置自定义域名访问
Github Pages 介绍
- Github Pages 是一个静态网站托管服务,可以通过github pages 托管静态网站,并且可以通过自定义域名访问
- 创建github pages 仓库,仓库名必须是
username.github.io格式,username是你的github用户名,仓库名必须是这个,否则无法部署成功 访问地址就是 https://username.github.io - 自定义域名访问,例如
www.abc.com,在域名服务商添加CNAME记录,指向username.github.io, 然后在github pages 仓库设置中添加自定义域名, 这样通过www.abc.com 就能访问github pages - 下面的 Actions 部分会介绍如何自动化部署到github pages,并且配置自定义域名
Hugo 介绍
- Hugo 是一个静态网站生成器,可以通过markdown文件生成静态网站,官网:https://gohugo.io/
- 写好markdown文件后,执行hugo命令,在public目录生成静态网站,然后 将public目录推送到github pages 仓库
- github actions工作流 就是通过hugo命令生成静态网站,并且推送到github pages 仓库
使用 Github Actions 自动化部署
创建 Github Actions。在github 仓库中(hugo-blog)创建.github/workflows目录,并且在目录中创建deploy.yml文件,文件名可以自定义,但是后缀必须是yml,例如deploy.yml,这样就创建了一个github actions,并且会自动执行,下面介绍我的deploy.yml文件
name: deploy
on:
push:
workflow_dispatch:
jobs:
build:
runs-on: ubuntu-latest
steps:
- name: Checkout
uses: actions/checkout@v2
with:
submodules: true
fetch-depth: 0
- name: Setup Hugo
uses: peaceiris/actions-hugo@v2
with:
hugo-version: "latest"
- name: Build Web
run: hugo
- name: Deploy Web
uses: peaceiris/actions-gh-pages@v3
with:
PERSONAL_TOKEN: ${{ secrets.BLOG_TOKEN }}
EXTERNAL_REPOSITORY: webws/webws.github.io
PUBLISH_BRANCH: master
PUBLISH_DIR: ./public
commit_message: ${{ github.event.head_commit.message }}
cname: ${{ secrets.DOMAIN }}上面 GitHub Actions配置文件用于自动部署Hugo博客到我的 GitHub Pages。以下是每个步骤的功能和解释：
- 步骤1：Checkout。此步骤使用
actions/checkout插件来检出 GitHub 仓库,具体使用文档地址是 checkoutsubmodules: true参数用于同时检出子模块，fetch-depth: 0用于完整地检出所有历史记录。 - 步骤2：Setup Hugo。此步骤使用
peaceiris/actions-hugo插件来安装最新版本的 Hugo。- name: Setup Hugo uses: peaceiris/actions-hugo@v2 with: hugo-version: "latest" - 步骤3：Build Web。此步骤在运行时调用 Hugo 构建静态网站，并在
public目录中生成静态html 文件- name: Build Web run: hugo - 步骤4：Deploy Web。此步骤使用
peaceiris/actions-gh-pages插件将静态网站部署到 GitHub Pages 上。- name: Deploy Web uses: peaceiris/actions-gh-pages@v3 with: PERSONAL_TOKEN: ${{ secrets.BLOG_TOKEN }} EXTERNAL_REPOSITORY: webws/webws.github.io PUBLISH_BRANCH: master PUBLISH_DIR: ./public commit_message: ${{ github.event.head_commit.message }} cname: ${{ secrets.DOMAIN }}
参数的含义：
PERSONAL_TOKEN: GitHub Personal Access Tokens 用于访问 GitHub 仓库，需要到github Personal access tokens设置添加权限，并将Token存储在仓库的Secrets中供Workflow使用EXTERNAL_REPOSITORY: 部署到的 GitHub Pages 仓库,webws/webws.github.io 是我的github pages 仓库,需要修改为你的github pages 仓库PUBLISH_BRANCH: 要在其上部署站点的分支名称（通常为master）。PUBLISH_DIR: hugo 静态html文件目录。（在此例中，Hugo 输出位于./public目录中）。commit_message: 提交更改时使用的提交消息，从上游分支获取。cname: 自定义域名,CNAME记录,我自己的是 blog.taoluyuan.com,需要修改为你的自定义域名,如果没有,可以删除这个参数,使用默认的github pages域名也访问 webws.github.io
设置 Secrets 变量,对应 yml 文件中的 PERSONAL_TOKEN 和 DOMAIN ,具体设置 在 仓库中(hugo-blog) 的 Settings -> secrets and variables->actions 中,hugo-blog 要换成你自己的仓库名
BLOG_TOKEN: GitHub Personal Access Token。DOMAIN: 你的自定义域名。
触发 Github Actions
- 在github 仓库中(hugo-blog)创建.md文件,并且提交到github,这样就会触发github actions,自动部署到github pages 仓库,并且可以通过自定义域名访问了
- 可以通过 仓库中 Actions 标签查看部署状态
访问 Github Pages
- 通过github pages域名访问, https://webws.github.io，因为我设置了自定义域名,所以这个域名会自动跳转到 https://blog.taoluyuan.com
- 通过自定义域名访问, https://blog.taoluyuan.com
搭建个人主页or博客网站
腾讯云面向开发者汇聚海量精品云计算使用和开发经验，营造开放的云计算技术生态圈。
更多推荐
21
0- 0
已为社区贡献8条内容
所有评论(0)