Hugo 是一个用 Go 语言编写的静态网站生成器，以速度快、易用性和灵活性著称。它能将 Markdown 文件、HTML 模板和其他资源快速转换为静态网站，适合博客、文档网站或作品集等场景。

主要特点

  • 速度快：生成网站只需几秒。
  • 易用性：安装和使用简单，适合新手。
  • 灵活性：支持自定义主题和模板。
  • 跨平台：支持 Windows、macOS 和 Linux。
  • 丰富主题：社区提供大量主题可选。

安装 Hugo

Windows

  1. 从 Hugo GitHub 下载 .zip 文件。
  2. 解压到任意目录（如 C:\Hugo\bin）。
  3. 将路径添加到系统环境变量 Path。
  4. 在命令提示符输入 hugo version 验证。

Linux (Ubuntu/Debian)

  1. 运行 sudo apt-get install git 安装 Git。
  2. 下载 .deb 文件并运行 sudo dpkg -i hugo_X.X.X_Linux-64bit.deb。
  3. 输入 hugo version 验证。

macOS (Homebrew)

  1. 未安装 Homebrew运行：
    /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
  2. 运行 brew install hugo。
  3. 输入 hugo version 验证。

创建新站点

运行以下命令创建一个新站点：

hugo new site my-hugo-site

这会在当前目录生成一个名为 my-hugo-site 的文件夹。

Hugo 文件结构

新站点包含以下主要目录：

  • content/：存放 Markdown 内容文件。

    • 作用：这是网站内容的存储位置，每篇文章或页面通常对应一个 Markdown 文件。
    • 组织方式：可以创建子目录（如 content/posts/、content/projects/）来分类不同类型的内容。
    • 示例：content/posts/my-first-post.md 是一个博客文章，Hugo 会根据其文件名或 Front Matter 生成对应的 URL。
    • 细节：文件中的 Front Matter 定义了元数据（如标题、日期等），正文则是页面内容。

  • static/：存放无需处理的静态文件（如图片）。

    • 作用：这些文件会直接复制到 public/ 目录，不经过 Hugo 的资源管道处理。
    • 示例：图片（static/images/logo.png）、字体（static/fonts/roboto.woff2）、robots.txt 等。
    • 特点：路径保持不变，例如 static/images/logo.png 在生成后位于 public/images/logo.png。

  • assets/：存放需处理的资源（如 CSS、JS）。

    • 作用：用于存储可以通过 Hugo 资源管道（Hugo Pipes）进行处理的资源，如 CSS、JavaScript 和图片。
    • 特点：支持压缩、合并、Sass/SCSS 编译等操作，适合动态管理资源。
    • 示例：assets/styles/main.scss 可以通过 Hugo 编译为 CSS 文件并输出到 public/。
    • 使用方式：在模板中使用 Hugo 函数（如 resources.Get "styles/main.scss" | toCSS）引用和处理这些资源。

  • layouts/：存放自定义 HTML 模板。

    • 作用：定义网站页面的结构和渲染方式，是网站的“骨架”。
    • 文件类型：
      • 默认模板：如 _default/baseof.html（基础模板）、_default/single.html（单页模板）、_default/list.html（列表页模板）。
      • 部分模板：如 partials/header.html、partials/footer.html，用于复用代码。
      • 自定义模板：如 layouts/posts/single.html，针对特定内容类型定制。
    • 优先级：layouts/ 中的模板优先级高于主题中的模板。

  • themes/：存放主题文件。

    • 作用：主题是一个完整的、可重用的设计方案，包含模板、静态资源和配置。
    • 结构：如 themes/my-theme/layouts/（模板）、themes/my-theme/static/（静态文件）。
    • 使用方式：通过在 config.toml 中设置 theme = "my-theme" 启用。

  • config.toml：配置文件。

    • 作用：定义全局设置，如网站标题、语言、URL 结构等。
    • 格式：支持 TOML、YAML 或 JSON，例如：
      baseURL = "https://example.com/"
title = "My Hugo Site"
theme = "my-theme"

  • public/：生成的网站文件。

    • 作用：Hugo 构建完成后，所有静态文件（HTML、CSS、JS 等）输出到此目录。
    • 示例：public/index.html 是首页，public/posts/my-first-post/index.html 是一篇博客文章。

Front Matter

每篇 Markdown 文件顶部需包含 Front Matter，定义文章元数据。常用参数：

  • title：标题
  • date：发布日期（如 2023-10-01）
  • draft：是否为草稿（true/false）
  • tags：标签
  • categories：分类
  • slug：自定义文章 URL 的一部分，覆盖默认的文件名。
    • 作用：简化或更改文章的 URL 路径，常用于 SEO 优化或美化。
    • 示例：
      • 文件：content/posts/my-first-post.md
      • 默认 URL：/posts/my-first-post/
      • 添加 Front Matter：
        ---
slug: "first"
---
      • 新 URL：/posts/first/
  • url：完全自定义文章的 URL 路径，优先级高于 slug。
    • 作用：允许用户指定完整的 URL 路径，覆盖默认规则。
    • 示例：
      • 文件：content/posts/my-first-post.md
      • 默认 URL：/posts/my-first-post/
      • 添加 Front Matter：
        ---
url: "/custom/path/to-my-first-post"
---
      • 新 URL：/custom/path/to-my-first-post

示例：

---
title: "我的第一篇博客"
date: 2023-10-01
draft: false
tags: ["Hugo", "入门"]
categories: ["博客"]
slug: "my-first-blog"
---

模板和主题

  • layouts/：项目自定义模板，优先级高于主题。

    • 定义：项目特定的 HTML 模板文件，完全由用户控制。
    • 特点：
      • 位于项目根目录的 layouts/ 中，优先级高于主题模板。
      • 适合深度定制化，允许用户从头定义页面结构。
    • 示例：layouts/_default/single.html 定义单篇文章的布局。
    • 适用场景：需要完全控制网站外观或微调现有主题时。

  • themes/：预制设计方案，可通过 themes/ 目录引入。

    • 定义：可复用的完整设计方案，包含模板、静态资源和默认配置。
    • 特点：
      • 存储在 themes/ 目录中，如 themes/my-theme/。
      • 提供预制样式和功能，适合快速搭建网站。
      • 用户可以通过 layouts/ 覆盖主题的部分模板。
    • 示例：themes/my-theme/layouts/_default/single.html 是主题提供的默认单页模板。
    • 适用场景：希望快速应用现成设计或不想从头编写模板时。

使用主题：

  1. 下载主题到 themes/。
  2. 在 config.toml 中设置 theme = "主题名"。
  • 选择的建议：
    • 使用 layouts/：
      • 如果你想从头构建网站，追求完全的自定义控制。
      • 如果你使用主题但需要调整部分页面，使用 layouts/ 覆盖主题模板。
    • 使用 themes/：
      • 如果你是新手或时间有限，希望快速搭建一个功能齐全的网站。
      • 如果你满意某个主题的设计，只需少量调整。

static 和 assets 的区别

  • static/：

    • 作用：存放不需要处理的静态文件，直接复制到 public/。
    • 特点：
      • 不支持 Hugo 资源管道处理。
      • 文件路径保持不变，例如 static/images/logo.png → public/images/logo.png。
    • 适用文件：图片、字体、PDF、robots.txt、favicon.ico 等。
    • 示例：将 robots.txt 放入 static/，生成后直接出现在 public/robots.txt。

  • assets/：

    • 作用：存放需要处理的静态资源，支持 Hugo 资源管道。
    • 特点：
      • 支持压缩、合并、Sass/SCSS 编译等操作。
      • 需要通过模板函数（如 resources.Get）引用。
    • 适用文件：CSS（如 main.scss）、JavaScript、需要优化的图片等。
    • 示例：assets/styles/main.scss 通过 {{ $style := resources.Get "styles/main.scss" | toCSS }} 处理后生成压缩后的 CSS。

  • 区别总结：

    • 处理方式：static/ 不处理，assets/ 支持处理。
    • 使用场景：static/ 适合简单文件，assets/ 适合需要优化的资源。

常用命令

  • hugo new site <name>：创建新站点。

    • 示例：hugo new site my-hugo-site 生成一个新项目目录。

  • hugo new posts/my-post.md：创建新文章。

    • 作用：创建新内容文件，使用 archetypes/ 中的模板。
    • 示例：hugo new posts/my-first-post.md 在 content/posts/ 中生成文件。

  • hugo：生成静态文件到 public/。

    • 作用：构建网站，将内容和模板渲染为静态文件，输出到 public/。
    • 示例：hugo 生成整个网站。

  • hugo server：启动本地预览（默认 localhost:1313）。

    • 作用：启动本地开发服务器，实时预览网站。
    • 示例：hugo server 默认在 http://localhost:1313 上运行。

  • 构建命令参数：

    • -d, --destination <dir>：
      • 作用：指定输出目录，覆盖默认的 public/。
      • 示例：hugo -d docs 将文件生成到 docs/。
    • -b, --baseURL <url>：
      • 作用：指定网站的基础 URL，用于生成绝对路径。
      • 示例：hugo -b https://example.com。
    • --minify：
      • 作用：压缩 HTML、CSS 和 JS 文件，减少文件大小。
      • 示例：hugo --minify。
    • 其他常用参数：
      • --cleanDestinationDir：构建前清空目标目录。
      • -t, --theme <theme-name>：指定使用的主题，覆盖配置文件中的设置。

参考