前言

shot.jpg

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

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

• Jekyll (基于 Ruby 容易上手) https://www.jekyll.com.cn/docs/home/
• Hexo (基于 Node.js 容易上手) https://hexo.io/docs/
• Hugo (基于 Go) https://gohugo.io/documentation/

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

• https://jimbowhy.gitee.io/
• https://jimboyeah.github.io/

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

• Hugo 不完美教程 - IX: Menus 菜單組織
• Hugo 不完美教程 - VIII: Functions 內(nèi)置函數(shù)
• Hugo 不完美教程 - VII: Variables 對(duì)象變量
• Hugo 不完美教程 - VI: Multilingual 多語(yǔ)言支持
• Hugo 不完美教程 - V: Templates 模板機(jī)制
• Hugo 不完美教程 - V: Templates 其它模板
• Hugo 不完美教程 - IV: Hugo Pipes 管道處理
• Hugo 不完美教程 - III: Hugo Modules 模塊
• Hugo 不完美教程 - II: Hugo 目錄組織
• Hugo 不完美教程 - I: Hugo Web Framework

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

• https://github.com/jimboyeah/jimboyeah.github.io/tree/hugo-project
• https://gitee.com/jimbowhy/jimbowhy/tree/hugo-project/
  
  shot.jpg

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)庫(kù)提供的文檔項(xiàng)目本身就是一個(gè)很好的示范，理解 Hogo 工程的目錄結(jié)構(gòu)是為了更好地利用 Hugo 的靜態(tài)站點(diǎn)生成能力螺句，比如語(yǔ)言支持與目錄結(jié)構(gòu)的關(guān)系虽惭、頁(yè)面模板與 Markdown 文件的關(guān)系與文件的組織方式。
tags: ["hugo", "menu"]

目錄：

[TOC]

Hugo 倉(cāng)庫(kù)提供的文檔項(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)芽唇，通過(guò) hugo new 創(chuàng)建的內(nèi)容會(huì)添加 date, title, draft = true 等扉頁(yè) 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 目錄才是模板存放的專(zhuān)用位置迅栅。

assets 目錄

不是默認(rèn)創(chuàng)建的資源目錄殊校，保存所有需要通過(guò) 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è)置虫给。
• 文件可以本地化為特定語(yǔ)言。

參考以下的配置文件目錄結(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抹估。

開(kāi)發(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ù)語(yǔ)言設(shè)置來(lái)調(diào)整瓷式，以下是 Hugo 文檔中的 _default\languages.toml 配置：

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

多語(yǔ)言支持參考 multilingual.md 文檔。

content 目錄

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

所有內(nèi)容頁(yè)面存放目錄贸典，content 下的一級(jí)子目錄看作一個(gè)對(duì)應(yīng)的 section 內(nèi)容分類(lèi)區(qū) content section。比如踱卵，為博客設(shè)置一個(gè) blog 目錄廊驼，為文章設(shè)置一個(gè) articles 目錄，為教程設(shè)置一個(gè) tutorials 目錄等惋砂，Hugo 使用內(nèi)容分類(lèi)區(qū)分作為默認(rèn)內(nèi)容類(lèi)型 content type妒挎，如果在扉頁(yè) front matter 設(shè)置了 type 則以具體設(shè)置的類(lèi)型為準(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 是特殊的索引頁(yè)面西饵，二選一使用酝掩。可以在其扉頁(yè) front matter 為模板提供元數(shù)據(jù)眷柔，如 list templates, section templates, taxonomy templates, taxonomy terms templates, homepage template 等等期虾。

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

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

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

---
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/

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

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

data 目錄

數(shù)據(jù)模板目錄，Hugo 靜態(tài)網(wǎng)站不會(huì)連接像 MySQL 這樣的數(shù)據(jù)庫(kù)怠肋，而此目錄保存的數(shù)據(jù)相當(dāng)于 Hugo 使用的數(shù)據(jù)庫(kù)敬鬓，生成過(guò)程用到的配置數(shù)據(jù)，可以用 YAML, JSON, TOML 等格式文件笙各。數(shù)據(jù)模板除了在此的文件定義钉答，還可以從動(dòng)態(tài)內(nèi)容中生成。通過(guò) getJSON 和 getCSV 兩個(gè)函數(shù)是模板函數(shù)加載外部數(shù)據(jù)杈抢，或者訪(fǎng)問(wèn)數(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)"
]

那么右蹦，可以通過(guò) .Site.Data.jazz.bass.jacopastorius 來(lái)使用它诊杆，在模板中將數(shù)據(jù)列表渲染出來(lái)：

{{ 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)的首頁(yè)模板在主題目錄中 layouts/index.html球及，除首頁(yè)外氧骤，Hugo 有兩類(lèi)基本頁(yè)面：

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

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

項(xiàng)目源碼文件的目錄布局影響著最終生成的 HTML 文件的結(jié)構(gòu)布局庐氮，通常分成若干個(gè)部分语稠，每部分都用一個(gè)目錄管理，比如 content 下的 posts 目錄對(duì)應(yīng)所有 post 頁(yè)面弄砍。編譯后生成的 .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 畫(huà)作模塊谐宙，或者 jQuery 工具庫(kù)，或者其它腳本界弧、圖像凡蜻、CSS 等等搭综，就可以將文件放到這里，在 Hugo 編譯生成時(shí)會(huì)自動(dòng)原樣復(fù)制到 public 目錄划栓。注意兑巾，可以有多個(gè)靜態(tài)資源目錄。

resources 目錄

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

public 目錄

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