HUGO+Github+Onedrive在Windows下搭建Blog

2019年了,还是第一次写Blog,可能是年纪大了,更加注重对生活和工作的记录了吧。 所以选择什么的平台来写Blog也成了一个问题,研究了两三天,最终还是选择了Hugo+Github,折腾完以后就专心生产内容。 本文不定期更新。

选择与比较

Blog平台选择

写Blog三阶段:

  1. 刚接触Blog,试着选择一个Blog平台来写。这个国内有新浪、网易、CSDN、博客园、简书、Segmentfault、掘金、知乎等,国外有blogger、wordpress等。Blog平台的好处是简单和SEO,只需要输出内容而无需关注其他,利用平台自身的功能可以很容易被搜索引擎搜索到。坏处是不安全,内容审核、被删图删文章删账号、甚至网站倒闭,辛辛苦苦写的东西一夜消失。Blog平台适合绝大多数人,门槛很低。
  2. 发现Blog平台限制太多,就自己购买域名和空间,或者自己在家独立建站。好处是完全可以设计自己的网站,包括设计、页面、元素等等,充分满足个性需求。坏处是门槛很高,要通盘考虑价格、网站安全、架构等等事项。如果是用国内的域名和空间需要备案,用国外的域名和空间速度慢,或者说很可能被墙。这个方式适合动手能力强、对Blog要求高的Geek。
  3. 独立建站太麻烦、Blog平台限制多,折中采用Blog托管的方式。

最终选择了Github Pages来搭建个人博客,理由:

  • 最重要的,内容不能被审核,虽然绝大部分内容不会涉及政治,但更不能谈个熊都会被抓,所以只能选择国外的服务
  • 国外的Blog平台,因为你懂的原因,99%都404。只剩下Github,虽然慢,但至少国内还能访问。不过我相信Github在不久的将来也会Blocked
  • 已经有很多人在用,经验丰富有案例。不想花太多时间在维护网站本身这件事上。
  • 所有的内容都在本地有备份,即使Github倒了,换个地方建站也是分分钟的事。
  • 免费

关于利用Github写博客的,不仅仅只有Github Pages一种方法,有兴趣的可以看看利用GitHub写博客的几种方式

静态网页生成器选择

在确定了要用Github Pages来搭建个人Blog之后,就是选择用哪种静态网页生成器了。 - Jekyll有Github官方支持,需要有Ruby环境,速度慢 - Hexo是台湾出品,搭建简单,但内容多了以后速度特别慢 - Hugo基于GO,只有一个二进制文件,安装方便,最重要的是文章多了速度依然很快

图床选择

  • 选择专门的图床网站,如新浪微博(已经不支持外链)、sm.ms、imgur等,好处是传图方便、访问速度快;坏处是图片随时消失
  • 在家自建图床,要考虑到安全性和上传带宽的问题
  • VPS自建图床,要考虑价格和审查的问题
  • 直接上传Github,好处是图片直接放在网站同一目录下,可以同时备份和引用;坏处是Github访问速度不够,加载过慢且空间也有限制
  • 使用onedrive的外链功能,好处是还没听说onedrive有被删文件的历史,且基于微软的信用,暂时不用考虑倒闭的问题,图片也没有流量限制;坏处是onedrive的网页版是被墙的,而分享功能必须基于网页操作,且图片需要一张一张操作有些烦琐,最后onedrive在国内某些地区和运营商的访问速度很慢。

快速建站

Hugo配置

安装Hugo

  • 前往 https://github.com/gohugoio/hugo/releases,下载 hugo_X.XX_Windows-64bit.zip,解压得到 hugo.exe。将 hugo.exe 所在目录添加至系统环境变量,之后CMD下用hugo命令即可。

  • 或者直接将hugo.exe放在你想要放的目录,然后在该目录下shift+右键,调出CMD或者Powershell,执行时 用.hugo.exe执行

  • 建站命令

hugo new site Blog

提示成功,并在目录下生成一个Blog文件夹

目录结构

.
├── archetypes
├── config.toml
├── content
├── data
├── layouts
├── static
└── themes
  • archetypes: 储存.md的模板文件,类似于hexoscaffolds,该文件夹的优先级高于主题下的/archetypes文件夹
  • config.toml: 配置文件
  • content: 储存网站的所有内容,类似于hexosource
  • data: 储存数据文件供模板调用,类似于hexosource/_data
  • layouts: 储存.html模板,该文件夹的优先级高于主题下的/layouts文件夹
  • static: 储存图片,css,js等静态文件,该目录下的文件会直接拷贝到/public,该文件夹的优先级高于主题下的/static文件夹
  • themes: 储存主题
  • public: 执行hugo命令后,储存生成的静态文件

安装主题

默认新建的站点是没有主题的,而没有主题就无法运行Hugo,所以需要先安装主题。

  • 在官方主题网站 https://themes.gohugo.io/ 查找,或者google到合适的主题,下载下来。
  • 解压后整个文件夹放在themes文件夹下,要注意文件夹名字即为主题名字。
  • 在站点根目录下,编辑config.toml文件,更改主题theme = "ananke"

开始写作

  • 新建一篇文章,建完后就可以用markdown进行编辑,我习惯使用typora

hugo new post/my-first-post.md

hugo server

  • 使用hugo命令可以生成静态网站文件,文件都放在public文件夹中,我们需要把整个public文件夹中的内容同步到github仓库中。

注意:最后每次生成能把public中文件先清空一下,再用命令重新生成,否则会有之前的残留无用文件

hugo

Github配置

  • 注册Github账号

  • 新建一个repo,名字与用户名同名

  • 我们使用的是windows桌面版本,为了不用git命令,下载安装Github Desktop软件。

地址:https://desktop.github.com/

  • 在Github Desktop软件中登陆你的Github账户,选择clone repository,从Github服务器上同步repo到本地

  • 找到本地的repo文件夹,将hugo生成的public文件夹中的所有内容复制进去

  • 可以看到左侧文件导航栏中有很多文件有更改。然后在summary中填写一些注释,点击Commit to master

  • 最后用Pull/Push/Fetch origin按钮同步本地与服务器中的文件

使用onedrive当图床

  • 使用onedrive当图床需要打开onedrive的网页,需要翻墙

https://onedrive.live.com/

  • 在网页版onedrive中,找到图片。右键图片,选择 嵌入,在浏览器右边即可看到生成的链接,在md文件中按markdown语法插入图片即可

进阶配置

配置 config.toml

编辑你的config.toml文件以配置你的站点。以下节选了部分有趣的参数,完整的配置文件可以参考官方文档

+++
# 主机名 例如: http://spf13.com/
baseURL =                     ""
# 语言编码(中文: zh-CN)
languageCode =                ""
# 默认的内容语言
defaultContentLanguage =      "zh-CN"
# 自动检测是否包含中文/日文/韩文,该参数会影响摘要和字数统计功能,建议设置为true
hasCJKLanguage =              false
# 若为 false,`Getting Started` 这样的英文标签将会被转换为 `getting-started`
preserveTaxonomyNames =       true
# 设置使用的主题名称 (默认储存在 /themes/THEMENAME/)
theme =        
# 分页
paginate =                    10
paginatePath =                "page"
# 启用 Emoji; see emoji-cheat-sheet.com
enableEmoji =                 false
# 创建robots.txt,建议设置为true
enableRobotsTXT =             false
# 定义文章访问路径,详细见下文"URL管理" See "content-management/urls/"
permalinks =                  ""
+++

除了预设的参数外,你也可以通过下面的方式自定义自己的参数。你可以在模板中获取到自定义的参数,通常情况下你使用的主题都会要求你这么做,具体信息可以阅读相关主题的文档。

[params]
  author = "olOwOlo"
  github = "olOwOlo"

至此,你已经掌握了足够的知识,你只需要从主题列表中挑选一个你喜欢的主题,阅读主题的文档并提供主题所需的信息,便可以开始使用hugo来写作了。

阅读下面的内容可以帮你更好的了解到hugo如何管理你的内容,而你又该如何更好的与hugo协作。

以上是对Getting Started的总结,下面是对Content Management的总结

组织content/文件夹

hugo会将content/目录下的结构反映到生成的静态网站中,如下:

.
└── content
    └── about
    |   └── _index.md  // <- https://example.com/about/
    ├── post
    |   ├── _index.md   // <- https://example.com/post/
    |   ├── firstpost.md   // <- https://example.com/post/firstpost/
    |   ├── happy
    |   |   └── ness.md  // <- https://example.com/post/happy/ness/
    |   └── secondpost.md  // <- https://example.com/post/secondpost/
    └── quote
        ├── first.md       // <- https://example.com/quote/first/
        └── second.md      // <- https://example.com/quote/second/

需要注意的是_index.md是一个比较特殊的文件,如果你只是需要一个about页面,你只需要hugo new about.md即可。关于_index.md的相关信息可以参阅官方文档

Hugo 中的路径分解

                    section
                    ⊢--^--⊣
                               url
                    ⊢-------------^------------⊣

      baseURL             path        slug
⊢--------^--------⊣ ⊢------^-----⊣⊢----^------⊣
                  permalink
⊢----------------------^-----------------------⊣
https://example.com/events/chicago/lollapalooza/

Hugo 中的类型

content/下的内容可能不仅仅只有文章,还可能有照片甚至其他不同形式的内容。hugo通过type属性来标记不同形式的内容,根据不同的type值,hugo会选择合适的模板来渲染内容。

默认情况下type被赋值为section。例如:使用hugo new posts/new-post.md命令得到的新文件会被默认为posts类型。当然你也可以在下文提到的front matter中显式的将文章的type指定为其他值。

Front Matter

Hugo 支持TOML、YAML、JSON格式的Front Matter。

以下列出一份完整的YAML格式的Front Matter,除了必要的datatitle参数外,你可以有选择性的使用其他参数。

---
title: "文章标题"
description: "文章的描述信息"
tags: [ "标签1", "标签2", "标签3" ]
categories: [ "分类1", "分类2" ]
keywords: [ "Hugo", "keyword" ]
date: 2012-04-06
lastmod: 2015-12-23
# CJKLanguage: Chinese, Japanese, Korean
isCJKLanguage: true
# 如果draft为true,除非使用 --buildDrafts 参数,否则不会发布文章
draft: false
# 设置文章的过期时间,如果是已过期的文章则不会发布,除非使用 --buildExpired 参数
expiryDate: 2020-01-01
# 设置文章的发布时间,如果是未来的时间则不会发布,除非使用 --buildFuture 参数
publishDate: 2020-01-01
# 排序你的文章
weight: 40
# 使用这两个参数将会重置permalink,默认使用文件名
url: 
slug: 
# 别名将通过重定向实现
aliases:
  - 别名1
  - /posts/my-original-url/
  - /2010/01/01/another-url.html
# type 与 layout 参数将会改变 Hugo 寻找该文章模板的顺序,将在下一节细述
type: review
layout: reviewarticle
# 三个比较复杂的参数
taxonomies:
linkTitle: 
outputs:
# 实验性的参数
markup: "md"
# 你还可以自定义任何参数,这些参数可以在模板中使用
include_toc: true
show_comments: false
---

模板选择顺序

这是一篇content/posts/下的文章寻找模板的顺序(此时我们未在文章的Front Matter指定typelayout属性):

  1. /layouts/UNSPECIFIED/UNSPECIFIED.html
  2. /layouts/posts/UNSPECIFIED.html
  3. /layouts/UNSPECIFIED/single.html
  4. /layouts/posts/single.html
  5. /layouts/_default/single.html
  6. /themes/<THEME>/layouts/UNSPECIFIED/UNSPECIFIED.html
  7. /themes/<THEME>/layouts/posts/UNSPECIFIED.html
  8. /themes/<THEME>/layouts/UNSPECIFIED/single.html
  9. /themes/<THEME>/layouts/posts/single.html
  10. /themes/<THEME>/layouts/_default/single.html

如果我们在Front Matter中添加以下代码

type: review
layout: reviewarticle

该文章现在的寻找模板顺序为:

  1. /layouts/review/reviewarticle.html
  2. /layouts/posts/reviewarticle.html
  3. /layouts/review/single.html
  4. /layouts/posts/single.html
  5. /layouts/_default/single.html
  6. /themes/<THEME>/layouts/review/reviewarticle.html
  7. /themes/<THEME>/layouts/posts/reviewarticle.html
  8. /themes/<THEME>/layouts/review/single.html
  9. /themes/<THEME>/layouts/posts/single.html
  10. /themes/<THEME>/layouts/_default/single.html

值得注意的是,/layouts/ 目录下模板优先级总是高于 /themes/<THEME>/layouts/ 。同理,若根目录下存在与 /themes/ 文件夹下同名的文件夹,根目录下的文件优先级总是高于 /themes/ 文件夹

因此,在我们只是需要别人提供的主题做一些小修改时,尤其是对于一些静态资源需要进行覆盖时,将新的文件置于根目录的文件夹下而不是直接对主题进行修改,日后需要更新主题时就无需解决 git 冲突的问题了。

当然,如果是需要直接对 /layouts/ 目录下的模板进行修改,还是建议新建一个 git 分支进行更改。

URL管理

正如前文所言,hugo会将content/目录下的结构反映到生成的静态网站中,但config.toml中的permalinks参数允许你自由更改内容的URL。例如:你想从hexo迁移到hugo,你可以将permalinks定义为下面这种形式以适应之前的URL。

[permalinks]
  post = "/:year/:month/:title/"

上面的配置将改变content/post/文件夹下所有文章的URL。

举个栗子,content/post/sample-entry.md的URL将从默认的https://example.com/post/sample-entry/改变为https://example.com/2013/11/sample-entry/

所有可用的属性如下:

/:monthname/:day/:weekday/:weekdayname/:yearday/:section/:title/:slug/:filename/

内容摘要

Hugo会自动提取文章的前70个字符作为摘要。(注意:该功能在中文环境下需要在config.toml中添加hasCJKLanguage = true才能发挥更好的效果。)

当然你也可以在文章内使用<!--more-->针对文章手动进行摘要提取,在<!--more-->之前出现的内容都会作为摘要使用,且能够保持渲染后的结构而不是纯文字版本。

Shortcodes

Shortcodes帮助你在编写markdown时快捷的插入HTML代码,功能上类似于Hexo的标签插件

{{< ref "blog/post.md" >}} => https://example.com/blog/post/
{{< ref "post.md#tldr" >}} => https://example.com/blog/post/#tldr:caffebad
{{< relref "post.md" >}} => /blog/post/
{{< relref "blog/post.md#tldr" >}} => /blog/post/#tldr:caffebad
{{< ref "#tldr" >}} => #tldr:badcaffe
{{< relref "#tldr" >}} => #tldr:badcaffe

上述代码通过内置的relrelref帮助你快速引用站点内的其他文章。

注意: 如果你的 content/ 目录下有多个同名的文件,引用该文章必须使用 blog/post.md 这样的相对路径而不是只提供 post.md 这样的文件名。

hugo还内置了instagramtweetyoutube等Shortcodes,可以阅读官方文档了解更多信息,你使用的主题可能也会提供Shortcodes,当然你也可以定制你自己的Shortcodes

分类系统

默认情况下即tagscategories,通常来说这已经足够我们使用了,但你也可以在config.toml文件中添加下面的代码来添加更多的分类。

[taxonomies]
  tag = "tags"
  category = "categories"
  series = "series"

Custom Output Formats

hugo能够输出多种不同格式的内容,这里简单的举个如何同时输出markdown文件的栗子:

在你的config.toml文件下添加:

[mediaTypes]
  [mediaTypes."text/plain"]
    suffix = "md"

[outputFormats.MarkDown]
  mediaType = "text/plain"
  isPlainText = true
  isHTML = false

为 MarkDown 新建一个 single.md 模板,写入以下代码,并放置在 /layouts/_default/ 文件夹下

{{ .RawContent }}

针对所有内容,在config.toml文件下添加:

[outputs]
  home = ["HTML", "RSS"]
  page = ["HTML", "MarkDown"]
  section = ["HTML", "RSS"]
  taxonomy = ["HTML", "RSS"]
  taxonomyTerm = ["HTML"]

针对某篇文章,在该文章的Front Matter中添加:

outputs:
  - html
  - markdown

在模板中的合适位置添加代码链接到你的.md文件:

{{ with .OutputFormats.Get "markdown" -}}
<a href="{{ .Permalink }}">查看本文 Markdown 版本 »</a>
{{- end }}

参考

Hugo 从入门到会用

0基础的git教程,傻瓜都会用的Github Desktop