Hugo - 简单，高效地搭建博客。

Notice! 注意事项。

本文最初使用的是 hugo-theme-itheme 主题。
现在本站转用新的Hugo主题 hugo-theme-Blowfish 。
Blowfish 主题，相比 iTheme 主题更复杂和精致。
本文属于入门的经验总结，并非详尽的技术教程。 HUGO Blowfish 主题需要一定使用经验，初级用户建议先学习使用 iTheme 主题。
建议直接参考 Blowfish 安装教程。
更新：部署到GitHub Pages请参考 Hugo - Github Pages博客的自动化部署进阶篇

欢迎来到小站

本站使用 Hugo 和 hugo-theme-itheme 主题，并部署在GitHub Pages上面。

主题的开源项目 hugo-theme-itheme & https://github.com/floyd-li/hugo-theme-itheme

更新：在文章最后，写了一个简化版的配置流程。

在 Windows 创建本地的 HUGO 博客。

前言：

Hugo是一款博客生成器，其生成的静态网页能够在Github Pages等平台上轻松部署。
优点：Hugo支持Markdown编写文章。Hugo拥有丰富的主题，能够简单定制和个性化。Hugo不需要复杂的组件支持，能够简单高效地生成和升级网站内容。
思路：Windows部署Hugo本地博客（前期的本地调试和网站制作）。然后上传项目到GitHub，利用GitHub的Actions功能，自动将博客网站部署到GitHub Pages。
GitHub与Hugo的教程有多。相对地，GitLab的教程就比较少，最主要是GitLab平台的部署方法有点复杂，其实GitLab部署的原理更简单。（以后有时间再探讨其它平台的部署经验。）
最初参照网上的 Windows教程，很快就能生成本地网站，但是一直无法正常打开，浏览器一直显示Page Not Found信息，不是网络问题导致的那种错误信息，而是Hugo生成的错误信息。
几乎找遍中文教程，都没有提及这个问题。折腾很长时间才能够解决。因此，才有了这篇经验总结。
文章写得有点繁琐，请见谅。文章内容是部署的思路和解释，具体流程直接使用“精简版”的命令行即可。（更新，最底有“简化版”配置流程。）

一、 First

Hugo官网 https://gohugo.io/installation/windows/
下载 HUGO 链接 Github
解压文件到，例如 C:\Program Files\hugo
Windows 系统变量里添加 PATH 变量，直接找到该路径。

1.精简版：下载Hugo，配置环境变量。

二、 Second

以下的命令直接使用 cmd.exe 。
如果上一步成功设置“系统变量”,输入 hugo version, 显示Hugo版本信息。
找一个合适位置创建Hugo文件夹，例如 C:\Downloads\Hugo\ 。输入命令 cd C:\Downloads\Hugo\。如果放在D盘，cmd里先直接输入d:，然后再cd D:\Hugo\进入路径。
输入命令，创建一个Hugo新博客 hugo new site blog。这个blog名字随便改。
Hugo新建的博客文件存放在此路径 C:\Downloads\Hugo\blog。blog文件夹内通常包含一些文件，例如 archetypes, layouts, static, themes, config.toml。

2.精简版：分别输入以下三行命令。

hugo version
cd C:\Downloads\Hugo\
hugo new site blog

三、 Third

进入项目。命令 cd C:\Downloads\Hugo\blog
新建post文件夹和文章一文档。命令 hugo new post/first.md
编辑文档first.md，随便输入 Hello World!等任意内容。文件的路径为 C:\Downloads\Hugo\blog\content\post\first.md
新建关于页面文件。命令 hugo new about.md
编辑文本about.md，随便输入 Hello World!等任意内容。文件的路径为 C:\Downloads\Hugo\blog\content\about.md
具体如何修改博客内容和写博文，请查看Hugo相关教程。
注意：这一步所创建的.md文件，都存放于“blog”之下的content文件夹中。C:\Downloads\Hugo\blog\content

3.精简版：分别输入以下三行命令。

cd C:\Downloads\Hugo\blog
hugo new post/first.md
hugo new about.md

四、 Fourth

此处记得在cmd进入路径。命令 cd C:\Downloads\Hugo\blog\themes 。如果blog里面没有 themes 文件夹，手动新建一个。
在themes 路径中，输入命令 git clone https://github.com/floyd-li/hugo-theme-itheme.git。使用Git命令要先安装软件 https://git-scm.com/
如果能正常 git clone 下载到主题 hugo-theme-itheme。那么路径应该是 C:\Downloads\Hugo\blog\themes\hugo-theme-itheme
修改项目的 config.toml文件, , 添加参数 theme = 'hugo-theme-itheme'。参考路径为C:\Downloads\Hugo\blog\config.toml
文件 config.toml的参数定义，请参考 GitHub 主题的说明

config.toml参数，仅供参考。

defaultContentLanguage = "en" # only support (en) and (zh-hans)
baseURL = 'xxx.github.io'
enableEmoji = true
title = 'Blog Name'
copyright = 'Author'
theme = 'hugo-theme-itheme'
[params]
  defaultCover = 'https://example.com/cover.jpg' 
  email = '[email protected]' # the email address display in the footer
  [[params.socialMedia]] 
    name = 'Github'
    url = 'https://github.com/floyd-li'
  [[params.socialMedia]]
    name = 'Twitter'
    url = 'https://twitter.com/some-one'
  [[params.blogroll]] 
    name = 'Apple'
    url = 'https://Apple.com/'
  [[params.blogroll]]
    name = 'Google'
    url = 'https://Google.com/'

4.精简版：分别输入以下两行命令。

cd C:\Downloads\Hugo\blog\themes
git clone https://github.com/floyd-li/hugo-theme-itheme.git

五、 Fifth

cmd进入路径，命令 cd C:\Downloads\Hugo\blog
cmd输入命令hugo生成网站文件。网站文件放在public目录下。
cmd启动Hugo本地服务，输入命令 hugo server -D
cmd里显示的 localhost:1313为本地网站链接。直接复制到浏览器打开localhost:1313，如果能正确打开网页，就是成功在Windows上创建Hugo本地网站，到步骤Fifth安装配置结束。后面的请忽略。

5.精简版：分别输入以下三行命令。（配置成功，每次重启只需执行此步骤。步骤Fifth。）

cd C:\Downloads\Hugo\blog
hugo
hugo server -D

六、 Sixth

原因不明。完成上述步骤后。Hugo本地网站在Windows上仍然不能正常启动。浏览器打开http://localhost:1313/ 一直显示 Page Not Found。正常情况应该是显示index的内容，它直接来个大写的Page Not Found。http://localhost:1313/about/等次级页面都一样报错。
难道是这Hugo只能生成出一句大号的Page Not Found？查看了public文件夹的内容，都是成功生成demo内容的，生成的网页文件应该是正确的。排查原因应该是“某些错误导致Hugo服务连接不到public里的文件”。
于是重启电脑，重做前面步骤，更换下载Hugo版本，不使用主题而直接创建Hugo网站，使用不同浏览器，能想到的方法都做了。在网上未搜到有关错误的教程。折腾了很久！
最后，终于找到了这篇问答 https://stackoverflow.com/questions/46216333/why-my-single-page-in-hugo-returns-a-404-http-error。讨论到404的问题，该原因可能是主题未能成功生效吧。
解决办法就是在启动命令后面加上-t 主题名字。
所以，输入命令hugo server -D -t hugo-theme-itheme成功运行。终于打开了这个http://localhost:1313/本地网站。这原本十分钟就能完成的步骤，硬是折腾了两天。
hugo-theme-itheme 代表主题名字，不同主题替换其它名字。blowfish主题的启动命令改为 hugo serve -D -t blowfish
可笑的是，过了一段时间，竟然可以正常使用命令 hugo server -D，服了这Windows，再尝试了不同主题来新建项目，都是hugo server -D一次完成启动，反正搞不懂了。

6.精简版：分别输入以下两行命令。（配置成功，每次重启只需执行此步骤。其实只是步骤Fifth的加强版。）

cd C:\Downloads\Hugo\blog
hugo server -D -t hugo-theme-itheme

总结

感谢浏览这篇文章，虽然算不上技术教程，希望这折腾的经验能够帮到你。
关于将Hugo部署到GitHub Pages，还是有些经验可以分享，就是实现自动化发布博客。下一篇文章再谈吧。

Screenshot

💎 最新：简化版 - Windows上配置本地的Hugo博客 🎨

下载安装 Hugo ，配置系统环境变量。

# Hugo的exe文件放到C盘某处，例如 `C:\Program Files\hugo`
# 根据相关Hugo路径，配置环境变量的PATH。
# 查看Hugo版本
hugo version

创建Hugo博客

# 进入自建的项目文件路径（只是任意自建的资料路径，不是Hugo的安装目录）
cd C:\Downloads\Hugo\
# 新建博客
hugo new site blog

或者（同一个步骤，只是解释一下细节。）

# 如果自建资料文件夹在D盘，直接输入d：
d:
# 进入自建的Hugo项目路径
cd D:\Downloads\Hugo\
# 新建博客
hugo new site blog

创建博客内容

注意：这一步所创建的.md文件，都存放于“blog”之下的content文件夹中。C:\Downloads\Hugo\blog\content

# 进入步骤2生成的blog路径
cd C:\Downloads\Hugo\blog
# 创建post文件夹和first.md（第一篇测试文章）
hugo new post/first.md
# 创建“关于”页面
hugo new about.md

下载主题，修改博客配置文件。

# 进入themes路径，没有的话，在“blog”目录下自建文件夹
cd C:\Downloads\Hugo\blog\themes
# git克隆主题（需要先安装软件 https://git-scm.com/）
git clone https://github.com/floyd-li/hugo-theme-itheme.git
# 修改“blog”目录下的config.toml参数。添加参数 `theme = 'hugo-theme-itheme'`。
# 'hugo-theme-itheme'`为主题名字，其它主题直接替换这名字。

config.toml参数，仅供参考。

defaultContentLanguage = "en" # only support (en) and (zh-hans)
baseURL = 'xxx.github.io'
enableEmoji = true
title = 'Blog Name'
copyright = 'Author'
theme = 'hugo-theme-itheme'
[params]
  defaultCover = 'https://example.com/cover.jpg' 
  email = '[email protected]' # the email address display in the footer
  [[params.socialMedia]] 
    name = 'Github'
    url = 'https://github.com/floyd-li'
  [[params.socialMedia]]
    name = 'Twitter'
    url = 'https://twitter.com/some-one'
  [[params.blogroll]] 
    name = 'Apple'
    url = 'https://Apple.com/'
  [[params.blogroll]]
    name = 'Google'
    url = 'https://Google.com/'

启动本地博客（若配置成功，每次重启只需执行此步骤。步骤5。）

# 进入“blog”目录路径
cd C:\Downloads\Hugo\blog
# 根据当前配置和内容，生成静态网站文件。文件存放于“blog”目录下的public文件夹。C:\Downloads\Hugo\blog\public
hugo
# 运行本地Hugo博客服务
hugo server -D
# 浏览器打开`localhost:1313`本地博客网站。配置成功的话，此处教程完结。

以下为“纠错”环节。之前成功部署的，请忽略。描述:浏览器打开http://localhost:1313/ 一直显示大写的 Page Not Found信息。反复部署和调试都复现。

# 进入“blog”目录路径
cd C:\Downloads\Hugo\blog
# 在运行Hugo服务命令的后面，加上`-t 主题名字`
hugo server -D -t hugo-theme-itheme
# 浏览器成功打开`localhost:1313`本地博客网站。本教程结束。

总结：

iTheme 主题参数的配置， Hugo 的使用方法，Markdown文章的规范，请参照其官方指导。
感谢浏览本教程，关于Hugo部署到GitHub Pages，下一篇教程再谈。

更新：部署到GitHub Pages

教程请参考 Hugo - Github Pages博客的自动化部署进阶篇

Copyright: Attribution-NonCommercial-ShareAlike 4.0 International (CC BY-NC-SA 4.0)✨