使用Hugo撰写文档

为什额是Hugo

Hugo是一个快速和现代化的静态网站生成工具，使用Go语言编写。为什么要使用静态化网站，是因为随着技术发展，原先需要服务端动态生成页面的工作，很多已经通过JS技术由客户端(浏览器)实现了，静态WEB页面可以提供极高的访问性能，对于大型WEB服务海量用户非常有利。并且静态化网站可以结合CDN技术，使得承载能力成倍提升。此外，静态网站不需要数据库支持，也不需要运行Ruby/Pthon/PHP这样虽然开发迅速但是运行效率较低的语言支持。

Hugo可以用来构建blog，CMS，或者公司/个人的知识库文档：

  • 性能卓越：每个页面小于1ms

  • 跨平台

  • 运行时可以更改渲染器

  • 强大的多样性风格

  • 适合任何主机托管

安装

  • MacOS中安装hugo:

brew install hugo

  • Windows中安装hugo:

choco install hugo -confirm

  • Linux中安装hugo:

snap install hugo

创建新站点

  • 使用以下命令创建新站点，例如 myworks

hugo new site works

上述命令创建了一个基本的 works 目录

不过，要实现美观而独特的Huge页面需要CSS和JS知识，我相信需要更为扎实的学习，来实现 Android 官方文档 简洁美观清晰的书籍。

文档型Hugo

参考 Hugo Document Tag ，其中比较美观的文档类型有:

  • Book - 传统的3列文档网站，配色简洁，可能最接近Android官方文档，或许是定制的基础

  • Hugo-theme-learn - 类似ReadTheDoc风格，比较规范，配色更为美观，可以作为书籍撰写

  • docuapi - 可以作为对外技术型文档选择，三列风格，动态效果出色：注意这个theme会使用所有的pages来构建一个单页面API文档，使用页面素材 weight 来控制页面顺序 （不知道数据量大的情况下是否影响载入，有点类似我以前使用的 Tidlywiki 使用一个页面来完成整个网站）

  • Academic - 完善页面导航和各种风格展示的嵌入，可以构建复杂网站

  • Techdoc - 适合撰写技术文档，这个风格是Hugo的官方文档风格

Blog类型

参考 Hugo Document Tag ，我感觉比较完善的:

  • Hugo Initio - 非常具有现代气息的卡片型

  • Universal - 最具有商业气质的网站，可以用作企业WEB网站，美轮美奂

  • Hugo future imperfect - 经典的blog风格，素雅，我感觉作为个人资料库也可以使用

  • Ananke - Hugo推荐的案例风格，简洁美观

  • Swift - 首页结合了卡片

我的选择

  • 个人文档系统

数据量有限情况下，采用 docuapi 构建

较为复杂的分类，建议采用 Hugo官方网站的风格，提供了良好的文档阅读结构

其中使用饿了asciinema来记录终端操作，非常巧妙

  • 个人blog

如果构建丰富展示个人不同方向的（如果人生比较精彩），可以选择 Universal

如果人生简单明了，则选择 Hugo Initio

Hugo site

使用

  • 初始化仓库

cd works
git init

  • 注意：Hugo必须首先选择一个theme才能使用，你可以从 Hugo themes 一次性下载所有theme

git clone --depth 1 --recursive https://github.com/gohugoio/hugoThemes.git themes

也可以只安装一个theme:

cd themes
git clone URL_TO_THEME

可以定制自己的theme：

hugo new theme THEMENAME

  • 生成第一个post

hugo new posts/my-first-post.md

此时会生成一个 content/posts/my-first-post.md 内容就是当前时间和标题

---
title: "My First Post"
date: 2019-11-11T21:02:51+08:00
draft: true
---

  • 启动 Hugo服务

hugo server -D

源代码安装

Hugo是使用Go编写的开源框架，可以从源代码编译，也可以直接下载可执行程序。

  • 从Github下载源代码安装:

brew install go

git clone https://github.com/gohugoio/hugo

mkdir -p src/github.com/gohugoio
ln -sf $(pwd) src/github.com/gohugoio/hugo

export GOPATH=$(pwd)
go get  #获取依赖包的所有最新版本

go build -o hugo main.go

  • 升级Hugo

  • 安装Pygments (可选)

参考

PreviousHugoNextHexo

Last updated

Was this helpful?