完成Hugo的基本setup後，我們來看看Hugo的project structure吧。

(強烈建議花點時間理解Hugo的整個結構，不然遇上問題會很迷茫)

Overview

執行hugo new site後的專案：

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

1. 基本設定：

config.toml

這是整個project的設定文件，裡面會define各種variables，有些是hugo的設定，有些是被layouts裡的html檔拿來用。

例如ananke主題的config.toml:

# --------- Hugo設定 ---------
title = "Notre-Dame de Paris"
baseURL = "https://example.com"
languageCode = "en-us"
theme = "ananke"

# --------- ananke theme所需的設定 ---------
Paginate = 3
googleAnalytics = ""
enableRobotsTXT = true

[sitemap]
  changefreq = "monthly"
  priority = 0.5
  filename = "sitemap.xml"

[params]
  favicon = ""
  description = "The last theme you'll ever need. Maybe."
  twitter = "https://twitter.com/GoHugoIO"
  github = ""

Hugo的預設config檔是用toml syntax，也可以設置成yaml或json，功能上沒有分別。

• title: 主頁的標題，也有機會用在其他地方
• baseURL: 所有relative path前面都會加上這baseURL (如blog/post.md變成https://example.com/blog/post.md)
• languageCode: 決定網頁語言，對單語言的blog用途不大，主要是讓search engine看
• theme: 使用哪個主題 (在themes/底下)
• 其他...

Hugo設定基本上所有theme都是共通的，但每個theme都會有一些自己的設定，例如在以上config中，github的link會變成.Site.Params.github，
讓負責render的html可以取用。此部份牽涉到 Template Rendering 。

---

2. 網頁模板渲染 (Template Rendering)

Hugo是一個static website generator，主要作用就是把各種動態資料、檔案，根據一早寫好的模板(templates)，渲染(render)成靜態的html檔。

themes/

安裝主題的地方。例如最基本的ananke主題：

themes/
└── ananke
    ├── LICENSE.md
    ├── README.md
    ├── archetypes  # important
    ├── exampleSite  # important
    ├── images
    ├── layouts  # important
    ├── package.json
    ├── src
    ├── static  # important
    └── theme.toml

其實主要的只有：

• archetypes: 下面會提及
• exampleSite: 主題的範例專案，一般安裝theme時會叫你由這裡複製config.toml來開始
• layouts: 一堆用作template的html檔，是整個網頁的基礎
• static: 主題所用的css, js, images等等

layouts/

一個Hugo網頁必須要有主題才能運作，這是因為要取用到layouts/裡面的html檔。例如Home page會用到/themes/ananke/layouts/index.html來render。

可以customize layout，但不建議直接改themes/裡面的東西。Template有look up order，專案中的layouts/index.html會override/themes/ananke/layouts/index.html。

html檔裡有各種render block，例如當hugo見到<h1>{{ .Params.bar }}</h1>，就會自動在render出.Params.bar的value。

Link: theme的必備檔案

---

3. 內容管理

content/

這裡是放置你寫的blog post的地方。官方建議起碼加一個post/的sub-directory，我自己是會用很多sub-directory為文章分類，檔名用日期作prefix方便排序。例如：

content/
└── post
    └── blogging
        └── hugo
            ├── 2017-10-21-choosing-tools.md
            ├── 2017-11-13-set-up-hugo.md
            └── 2017-12-18-hugo-file-structure.md

• 不論開多少個sub-directory，Hugo還是能grab到文章。
• 執行hugo new post/blogging/hugo/xxx.md建立文章，Hugo預設就是新增在content/底下。

archetypes/

要理解 archetypes ，首先要了解 front matter 。

每次執行hugo new建立新post時，hugo會自動幫你在.md檔中加入了必需的 front matter ，類似一篇文章的metadata。

例如：hugo new post/my-first-post.md

---
title: "My First Post" # Hugo自動把檔名format成標題
date: 2017-12-18T21:54:40+08:00
draft: true
---
Your markdown here, blahblahblah...

如果我想post/裡面新增的所有post都有一些特定的tag，我可以新增archetypes/post.md：

---
title: "{{ replace .TranslationBaseName "-" " " | title }}"
date: {{ .Date }}
draft: true
tags: ["web development", "blogging"]
---
Your markdown here, blahblahblah...

• title和date是hugo必需的，不然會有warning
• {{ replace .TranslationBaseName "-" " " | title }}是hugo的rendering block，功能就是把my-first-post.md變成My First Post
• tags是我新增的新attribute

執行hugo new post/xxx.md時，Hugo會按特定次序尋找archetypes檔來建立 front matter ：

1. archetypes/post.md
2. archetypes/default.md
3. themes//archetypes/posts.md
4. themes//archetypes/default.md

（Hugo目前無法支援nested archetypes，所以hugo new post/blog/xxx.md只會找archetypes/post.md）

內部連結

Hugo內置功能，可以產生連結到其他page的link。

例如在此處，我可以用

{{</* ref "post/blogging/hugo/2017-11-13-set-up-hugo.md" */>}}

來render出{{< ref "post/blogging/hugo/2017-11-13-set-up-hugo.md" >}}。

static/

這裡一般是用來放css, js, images。例如：

static/
└── images
    └── abc.png

可以用![alt text](/images/abc.png)來顯示圖片。

data/

此處可放一些網頁的data，例如data/somedata.toml：

food = ["Bread", "Pasta", "Rice"]

然後可以用{{ .Site.Data.somedata.food }}獲取data。

• 可用format: YAML, TOML, JSON
• data的詳細例子