Hugo 不完美教程 - II: Hugo 目錄組織

前言

shot.jpg

本靜態(tài)站點(diǎn)用于演示之用，使用 Hugo 構(gòu)建，以及 Markdown 供應(yīng)內(nèi)容。

流行的靜態(tài)站點(diǎn)框架有以下幾個(gè)：

演示站點(diǎn)有兩個(gè)訪問入口：

此站點(diǎn)提供了一篇關(guān)于 Hugo 靜態(tài)站點(diǎn)生成框架的入門教程。

代碼倉(cāng)庫地址如下，查看 hugo-project 分支是原文件，master 分支是發(fā)布的靜態(tài)站點(diǎn)文件：

title: "II: Hugo 目錄組織"
description: "堅(jiān)果的 Hugo 教程"
date: 2020-08-06T20:14:08-04:00
featured_image_: "/assets/IMG_20181016_130158.jpg"
thumb_image_: "/assets/micro_s.png"
summary: Hugo 倉(cāng)庫提供的文檔項(xiàng)目本身就是一個(gè)很好的示范，理解 Hogo 工程的目錄結(jié)構(gòu)是為了更好地利用 Hugo 的靜態(tài)站點(diǎn)生成能力，比如語言支持與目錄結(jié)構(gòu)的關(guān)系、頁面模板與 Markdown 文件的關(guān)系與文件的組織方式。
tags: ["hugo", "menu"]

目錄：

[TOC]

Hugo 倉(cāng)庫提供的文檔項(xiàng)目本身就是一個(gè)很好的示范，以下內(nèi)容摘自下面文檔：

hugo\docs\content\en\getting-started\quick-start.md

使用 hugo new site 生成的項(xiàng)目模板目錄結(jié)構(gòu)：

.
├── archetypes 
├── config.toml
├── content
├── data
├── layouts
├── static
└── themes

archetypes 目錄

默認(rèn)，通過 hugo new 創(chuàng)建的內(nèi)容會(huì)添加 date, title, draft = true 等扉頁 front matter 設(shè)置信息，它們就是從 archetypes 模板文件中拷貝的。這可以節(jié)省時(shí)間，同時(shí)保證統(tǒng)一性。

Archetypes 作為內(nèi)容模板，Hugo 官方建議靜態(tài)站點(diǎn)源碼文件按 section 組織，每個(gè) section 使用相應(yīng)同名的 archetypes，這樣 section 下面的 .md 就會(huì)自動(dòng)使用響應(yīng) type 的 meta data。

當(dāng)執(zhí)行 hugo new posts/dmeo.md，Hugo 會(huì)到 archetypes 目錄下搜索 posts.md 文件，找到哪個(gè)則使用哪個(gè)內(nèi)容模板：

  • archetypes/posts.md
  • archetypes/default.md
  • themes/my-theme/archetypes/posts.md
  • themes/my-theme/archetypes/default.md

要明確一點(diǎn)，Hugo 中 MD 文件一般是作為內(nèi)容文件使用的，只有特殊位置中的 MD 文件才是內(nèi)容模板，而 layouts 目錄才是模板存放的專用位置。

assets 目錄

不是默認(rèn)創(chuàng)建的資源目錄，保存所有需要通過 Hugo Pipes 處理的資源，只有那些 .Permalink 和 .RelPermalink 引用的文件會(huì)發(fā)布到 public 目錄中，參考 Hugo 管道處理。

config 目錄

配置目錄，非默認(rèn)創(chuàng)建，Hugo 有大量的配置指令，此目錄用于保存 JSON, YAML, TOML 等配置文件。最簡(jiǎn)單的項(xiàng)目只需要一個(gè)根目錄下的配置文件 config.toml。 Every root setting object can stand as its own file and structured by environments.

  • 每個(gè)配置文件代表一個(gè)配置根對(duì)象 configuration root object，如 Params, Menus, Languages 等等。
  • 每個(gè)目錄保存一組配置文件，針對(duì)獨(dú)一的環(huán)境提供設(shè)置。
  • 文件可以本地化為特定語言。

參考以下的配置文件目錄結(jié)構(gòu)：

├── config
│   ├── _default
│   │   ├── config.toml
│   │   ├── languages.toml
│   │   ├── menus.en.toml
│   │   ├── menus.zh.toml
│   │   └── params.toml
│   ├── production
│   │   ├── config.toml
│   │   └── params.toml
│   └── staging
│       ├── config.toml
│       └── params.toml

當(dāng)運(yùn)行 hugo --environment staging，Hugo 會(huì)將 config/_default 合并到 staging。

開發(fā)中默認(rèn)環(huán)境為 development 即對(duì)應(yīng) hugo serve 運(yùn)行命令，而編譯生成時(shí)的環(huán)境為 production 對(duì)應(yīng) hugo 命令，參考 configuration.md 文檔。

內(nèi)容目錄可以根據(jù)語言設(shè)置來調(diào)整，以下是 Hugo 文檔中的 _default\languages.toml 配置：

  [en]
    contentDir = "content/en"
    languageName = "English"
    weight = 1
  
  [zh]
    contentDir = "content/zh"
    languageName = "中文"
    weight = 2

多語言支持參考 multilingual.md 文檔。

content 目錄

參考內(nèi)容管理 types.md, organization 文檔。

所有內(nèi)容頁面存放目錄，content 下的一級(jí)子目錄看作一個(gè)對(duì)應(yīng)的 section 內(nèi)容分類區(qū) content section。比如，為博客設(shè)置一個(gè) blog 目錄，為文章設(shè)置一個(gè) articles 目錄，為教程設(shè)置一個(gè) tutorials 目錄等，Hugo 使用內(nèi)容分類區(qū)分作為默認(rèn)內(nèi)容類型 content type，如果在扉頁 front matter 設(shè)置了 type 則以具體設(shè)置的類型為準(zhǔn)。

內(nèi)容目錄結(jié)構(gòu)與 URL 對(duì)應(yīng)關(guān)系參考：

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

每個(gè)目錄下的 _index.md 和 index.md 是特殊的索引頁面，二選一使用?？梢栽谄潇轫?front matter 為模板提供元數(shù)據(jù)，如 list templates, section templates, taxonomy templates, taxonomy terms templates, homepage template 等等。

在模板文件中，可以使用 .Site.GetPage 函數(shù)來獲取數(shù)據(jù)。

而 index.md 頁面呈現(xiàn)是較特殊的一個(gè)，假設(shè)在 section 目錄下無其它 md 文件時(shí)，默認(rèn)就展現(xiàn) index.md 頁面。如果，包含其它頁面，那么就會(huì)在列表中展示 index.md，但默認(rèn)它就是鏈接到列表本身。

例如，Hugo 文檔中的 _index.md 示范，title 和 description 這些數(shù)據(jù)就會(huì)在列表頁面模板中呈現(xiàn)出來：

---
title: Get Started
linktitle: Get Started Overview
description: Quick start and guides for installing Hugo on your preferred operating system.
date: 2017-02-01
publishdate: 2017-02-01
lastmod: 2017-02-01
categories: [getting started]
keywords: [usage,docs]
menu:
  docs:
    parent: "getting-started"
    weight: 1
weight: 0001    #rem
draft: false
aliases: [/overview/introduction/]
toc: false
---

If this is your first time using Hugo and you've [already installed Hugo on your machine][installed], we recommend the [quick start][]. You can also use [external learning resources][] to learn Hugo.

[installed]: /getting-started/installing/
[quick start]: /getting-started/quick-start/
[external learning resources]: /getting-started/external-learning-resources/

參考各種列表模板文件的使用：

  • 分類術(shù)語頁 Taxonomy terms pages
  • 分類列表頁 Taxonomy list pages
  • 分區(qū)列表頁 Section list pages
  • 簡(jiǎn)易信息聚合 RSS - Really Simple Syndication

data 目錄

數(shù)據(jù)模板目錄，Hugo 靜態(tài)網(wǎng)站不會(huì)連接像 MySQL 這樣的數(shù)據(jù)庫，而此目錄保存的數(shù)據(jù)相當(dāng)于 Hugo 使用的數(shù)據(jù)庫，生成過程用到的配置數(shù)據(jù)，可以用 YAML, JSON, TOML 等格式文件。數(shù)據(jù)模板除了在此的文件定義，還可以從動(dòng)態(tài)內(nèi)容中生成。通過 getJSON 和 getCSV 兩個(gè)函數(shù)是模板函數(shù)加載外部數(shù)據(jù)，或者訪問數(shù)據(jù)接口，在外部數(shù)據(jù)加載完成以前，Hugo 會(huì)暫停渲染模板文件。

{{ $dataJ := getJSON "url" }}
{{ $dataC := getCSV "separator" "url" }}
{{ $dataJ := getJSON "url prefix" "arg1" "arg2" "arg n" }}
{{ $dataC := getCSV  "separator" "url prefix" "arg1" "arg2" "arg n" }}

假設(shè) data/jazz/bass/jacopastorius.toml 數(shù)據(jù)模板文件包含如下貝斯手?jǐn)?shù)據(jù)：

discography = [
"1974 – Modern American Music … Period! The Criteria Sessions",
"1974 – Jaco",
"1976 - Jaco Pastorius",
"1981 - Word of Mouth",
"1981 - The Birthday Concert (released in 1995)",
"1982 - Twins I & II (released in 1999)",
"1983 - Invitation",
"1986 - Broadway Blues (released in 1998)",
"1986 - Honestly Solo Live (released in 1990)",
"1986 - Live In Italy (released in 1991)",
"1986 - Heavy'n Jazz (released in 1992)",
"1991 - Live In New York City, Volumes 1-7.",
"1999 - Rare Collection (compilation)",
"2003 - Punk Jazz: The Jaco Pastorius Anthology (compilation)",
"2007 - The Essential Jaco Pastorius (compilation)"
]

那么，可以通過 .Site.Data.jazz.bass.jacopastorius 來使用它，在模板中將數(shù)據(jù)列表渲染出來：

{{ range $.Site.Data.jazz.bass }}
   {{ partial "artist.html" . }}
{{ end }}

然后在 partials/artist.html:

<ul>
{{ range .discography }}
  <li>{{ . }}</li>
{{ end }}
</ul>

layouts 目錄

布局模板文件目錄，存放 .html 布局模板文件，對(duì)應(yīng)不同的內(nèi)容，模板有多種，data-templates、homepage、lists、menu-templates、partials、section-templates 等等。

站點(diǎn)的首頁模板在主題目錄中 layouts/index.html，除首頁外，Hugo 有兩類基本頁面：

  • Single page 單體頁面，如 hugo new demo.md 創(chuàng)建的 Post 頁面；
  • List page 列表頁面，如 tags 或 categories 頁面；

這兩種頁面的默認(rèn)模板都在主題目錄中 layouts/_default，分別對(duì)應(yīng)著 single.html 和 list.html。參考單頁面內(nèi)容模板 single-page-templates.md 和 lists.md 文檔。

項(xiàng)目源碼文件的目錄布局影響著最終生成的 HTML 文件的結(jié)構(gòu)布局，通常分成若干個(gè)部分，每部分都用一個(gè)目錄管理，比如 content 下的 posts 目錄對(duì)應(yīng)所有 post 頁面。編譯后生成的 .html 文件也會(huì)在 public 的 posts 目錄下，那么這里的 posts 就是一個(gè) section 概念。

Hugo 會(huì)為每個(gè) section 生成 index.html，采用主題布局中的 index.html 模板。

至于是否采用 layouts/_default/list.html，這要看 host 的匹配順序，官方給出的布局模板匹配參考順序：

/layouts/section/SECTION.html
/layouts/_default/section.html
/layouts/_default/list.html
/themes/THEME/layouts/section/SECTION.html
/themes/THEME/layouts/_default/section.html
/themes/THEME/layouts/_default/list.html

這個(gè)例子中 THEME=ananke, SECTION=posts，如果根目錄下的 layouts 是空的，就進(jìn)入主題目錄下搜索 layouts/section/posts.html 模板，如果也不存在，因此用的是主題目錄下的 _default/list.html。

static 目錄

靜態(tài)資源存放目錄，比如想使用 Marmarid 畫作模塊，或者 jQuery 工具庫，或者其它腳本、圖像、CSS 等等，就可以將文件放到這里，在 Hugo 編譯生成時(shí)會(huì)自動(dòng)原樣復(fù)制到 public 目錄。注意，可以有多個(gè)靜態(tài)資源目錄。

resources 目錄

資源緩沖目錄，非默認(rèn)創(chuàng)建，用于加速 Hugo 的生成過程，也可以用給模板作者分發(fā)構(gòu)建好的 SASS 文件，因此不必安裝預(yù)處理器。

public 目錄

生成靜態(tài)站點(diǎn)的文件輸出目錄。

最后編輯于 ：
?著作權(quán)歸作者所有,轉(zhuǎn)載或內(nèi)容合作請(qǐng)聯(lián)系作者
【社區(qū)內(nèi)容提示】社區(qū)部分內(nèi)容疑似由AI輔助生成，瀏覽時(shí)請(qǐng)結(jié)合常識(shí)與多方信息審慎甄別。
平臺(tái)聲明：文章內(nèi)容（如有圖片或視頻亦包括在內(nèi)）由作者上傳并發(fā)布，文章內(nèi)容僅代表作者本人觀點(diǎn)，簡(jiǎn)書系信息發(fā)布平臺(tái)，僅提供信息存儲(chǔ)服務(wù)。

友情鏈接更多精彩內(nèi)容