Hugo目录结构

我们先来了解根目录下各个文件夹的作用,可以参考官方目录结构说明 :

.
├── archetypes
│   └── default.md
├── assets
├── content
├── data
├── layouts
├── static
├── resources
├── themes
└── config.toml
文件名称 简要说明
archetypes 该文件夹主要用来存储博客生成的模板文件,初次使用只有一个default.md,可以根据个人的主题配置添加自定义头部信息
assets 该文件夹主要用于保存博客样式cssjs文件
content 保存个人博客所有内容
data 保存生成站点时候所需要的配置文件
layouts 以为.html形式存储模板,将你博客内容呈现为静态页面
static 存储所有静态内容:图片、.css、.js等,当使用Hugo生成静态页面时,所有内容将会被复制
resources 缓存一些文件来加速站点生成
themes 保存主题
config.yml 个人博客主题样式配置文件

编辑 config.yml 文件

config.yml文件是对个人站点的配置文件。它包括站点名称、主题、访问地址等一系列参数,Hugo默认配置文件格式是.toml,但.yml格式更易看懂,因此我们之前在新建站点时候执行的是hugo new site MyBlog -f yml命令,因此生成的文件是.yml格式。

  • 官方提供的PaperMod配置样式:config.yml

  • 参数含义参考主题Wiki:FeaturesVariables 以及Hugo官方文档的相关内容:Configure Hugo

  • 下面使用的是Sulv’s Blog 给出的配置文件。配置文件内容根据个人实际情况自行修改,主要是链接标题的修改。logo.gif要放到网站根目录下的static/img/logo.gif

baseURL: https://www.shaohanyun.top # 绑定的域名
title: Shaohan's Blog
paginate: 10    # 首页每页显示的文章数
theme: PaperMod # 主题名称,和themes文件夹下的一致
languageCode: zh-cn # en-us

hasCJKLanguage: true # 自动检测是否包含中文日文韩文,如果文章中使用了很多中文引号的话可以开启
enableInlineShortcodes: true
enableEmoji: true # 允许使用 Emoji 表情,建议 true
enableRobotsTXT: true
buildDrafts: false
buildFuture: false
buildExpired: false
enableEmoji: true
pygmentsUseClasses: true
# googleAnalytics: UA-123-45


minify:
    disableXML: true
    # minifyOutput: true

permalinks:
  post: "/:title/"
  # post: "/:year/:month/:day/:title/"

defaultContentLanguage: zh # 最顶部首先展示的语言页面
defaultContentLanguageInSubdir: true

languages:
    zh:
      languageName: "Chinese"
      # contentDir: content/english
      weight: 1
      profileMode:
        enabled: true
        title: 独立之精神,自由之思想
        subtitle: "👏🏼欢迎光临寒舍</br>👇联系方式"
        imageUrl: "img/logo.gif"
        imageTitle: 
        imageWidth: 150
        imageHeight: 150
        buttons:
          - name: 👨🏻‍💻技术
            url: posts/tech
          - name: 📕阅读
            url: posts/read
          - name: 🏖生活
            url: posts/life

      menu:
        main:
          - identifier: search
            name: 🔍搜索
            url: search
            weight: 1
          - identifier: home
            name: 🏠主页
            url: /
            weight: 2
          - identifier: posts
            name: 📚文章
            url: /posts
            weight: 3
          - identifier: archives
            name: ⏱时间轴
            url: /archives
            weight: 20
          # - identifier: categories
          #   name: 🧩分类
          #   url: categories
          #   weight: 30
          - identifier: tags
            name: 🔖标签
            url: /tags
            weight: 40
          - identifier: about
            name: 🙋🏻‍♂️关于
            url: /about
            weight: 50
          # - identifier: links
          #   name: 🤝友链
          #   url: links
          #   weight: 60

outputs:
    home:
        - HTML
        - RSS
        - JSON

params:
    env: production # to enable google analytics, opengraph, twitter-cards and schema.
    description: "这是一个纯粹的博客......"
    author: Shaohan Tian
    # author: ["Me", "You"] # multiple authors

  
    defaultTheme: auto  # defaultTheme: light or  dark 
    disableThemeToggle: false
    DateFormat: "2006-01-02"
    ShowShareButtons: true
    ShowReadingTime: true
    # disableSpecialistPost: true
    displayFullLangName: true
    ShowPostNavLinks: true
    ShowBreadCrumbs: true
    ShowCodeCopyButtons: true
    hideFooter: false # 隐藏页脚
    ShowWordCounts: true
    VisitCount: true

    ShowLastMod: true #显示文章更新时间

    ShowToc: true # 显示目录
    TocOpen: true # 自动展开目录

    comments: true
    
    socialIcons:
        - name: github
          url: "https://github.com/tianshaohan"
        # - name: twitter
        #   url:  "img/twitter.png"
        - name: bilibili
          url: "https://space.bilibili.com/395280439"
        - name: QQ
          url: "img/qq.jpg"    
        - name: email
          url: "mailto:shaohan.tian@foxmail.com"
        - name: RSS
          url: "index.xml"
        # - name: facebook
        #   url: "https://www.facebook.com/profile.php?id=100027782410997"
        # - name: instagram
        #   url: "img/instagram.png"
        # - name: QQ
        #   url: "img/qq.png"
        # - name: Phone
        #   url: "img/phone.png"


    # editPost:
    #     URL: "https://github.com/adityatelange/hugo-PaperMod/tree/exampleSite/content"
    #     Text: "Suggest Changes" # edit text
    #     appendFilePath: true # to append file path to Edit link

    # label:
    #     text: "Home"
    #     icon: icon.png
    #     iconHeight: 35

    # analytics:
    #     google:
    #         SiteVerificationTag: "XYZabc"

    assets:
        favicon: "img/logo.gif"
        favicon16x16: "img/logo.gif"
        favicon32x32: "img/logo.gif"
        apple_touch_icon: "logo.gif"
        safari_pinned_tab: "logo.gif"

    # cover:
    #     hidden: true # hide everywhere but not in structured data
    #     hiddenInList: true # hide on list pages and home
    #     hiddenInSingle: true # hide on single page

    fuseOpts:
        isCaseSensitive: false
        shouldSort: true
        location: 0
        distance: 1000
        threshold: 1
        minMatchCharLength: 0
        keys: ["title", "permalink", "summary"]

    twikoo:
      version: 1.4.11

taxonomies:
    category: categories
    tag: tags
    series: series

markup:
    goldmark:
        renderer:
            unsafe: true # HUGO 默认转义 Markdown 文件中的 HTML 代码,如需开启的话
    highlight:
        # anchorLineNos: true
        codeFences: true  
        guessSyntax: true
        lineNos: true
        # noClasses: false
        # style: monokai
        style: darcula

        # codeFences:代码围栏功能,这个功能一般都要设为 true 的,不然很难看,就是干巴巴的-代码文字,没有颜色。
        # guessSyntax:猜测语法,这个功能建议设置为 true, 如果你没有设置要显示的语言则会自动匹配。
        # hl_Lines:高亮的行号,一般这个不设置,因为每个代码块我们可能希望让高亮的地方不一样。
        # lineNoStart:行号从编号几开始,一般从 1 开始。
        # lineNos:是否显示行号,我比较喜欢显示,所以我设置的为 true.
        # lineNumbersInTable:使用表来格式化行号和代码,而不是 标签。这个属性一般设置为 true.
        # noClasses:使用 class 标签,而不是内嵌的内联样式

privacy:
    vimeo:
        disabled: false
        simple: true

    twitter:
        disabled: false
        enableDNT: true
        simple: true

    instagram:
        disabled: false
        simple: true

    youtube:
        disabled: false
        privacyEnhanced: true

services:
    instagram:
        disableInlineCSS: true
    twitter:
        disableInlineCSS: true

添加搜索页面

参考官方文档:搜索页面

PaperMod 使用 Fuse.js Basic 作为搜索基础

添加以下配置到config.yml文件(上述配置文件已有,此处不用重复添加)

outputs:
    home:
        - HTML
        - RSS
        - JSON # is necessary

content文件夹中创建search.md并添加以下配置:

---
title: "🔍 搜索" # in any language you want
layout: "search" # is necessary
# url: "/archive"
# description: "Description for Search"
summary: "search"
placeholder: "搜索框内的默认显示"
---

要使得某些特定的不被搜素到,可以在博客开头添加:

---
searchHidden: true

配置时间轴页面

参考官方文档:时间轴页面

content文件夹中创建archive.md并添加以下配置:

---
title: "⏱ 时间轴"
layout: "archives"
url: "/archives/"
summary: archives
---

注意:时间轴原始样式是英文,修改为中文会显得更加协调,参考Hugo博客时间轴中文化

配置标签页面

  • PaperMod主题是支持多语言的,但是标签页不支持,需要修改对应的 html 模板。
  • 主题提供的语言支持文件再themes/PaperMod/il8n里面,其中zh.yaml即简体中文。
  • 为了防止更新主题时还原修改过的文件,需要在网站根目录进行修改,这样可以覆盖主题原有文件的效果。

修改默认翻译

在网站根目录新建i18n/文件夹,复制themes/PaperMod/i18n/zh.yamli18n/zh.yaml,并编辑

- id: prev_page
  translation: "上一页"

- id: next_page
  translation: "下一页"

- id: read_time
  translation:
    one : "1 分钟"
    other: "{{ .Count }} 分钟"

- id: toc
  translation: "目录"

- id: translations
  translation: "语言"

- id: home
  translation: "🏠主页"

- id: edit_post
  translation: "编辑"

- id: code_copy
  translation: "复制"

- id: code_copied
  translation: "已复制!"

注意:旧版本可能需要修改,较新版本 PaperMod 6.0 翻译完善,几乎不用修改!

修改 html 模板

标签页对应的模板文件为themes/PaperMod/layouts/_default/terms.html,同以上步骤:在网站根目录新建layouts/_default/文件夹,复制themes/PaperMod/layouts/_default/terms.htmllayouts/_default/terms.html,并编辑

{{- define "main" }}

{{- if .Title }}
<header class="page-header">
    {{- if eq .Title "Categories" }}
    <h1>🧩{{ .Title }}</h1>
    {{- end }}
    {{- if eq .Title "Tags" }}
        <h1>🔖{{ "标签" }}</h1>
        <!-- <h1>🔖{{ .Title }}</h1> -->
    {{- end }}
    <!-- <h1>{{ .Title }}</h1> -->
    {{- if .Description }}
    <div class="post-description">
        {{ .Description }}
    </div>
    {{- end }}
</header>
{{- end }}

<!-- 原始 -->

<ul class="terms-tags">
    {{- $type := .Type }}
    {{- range $key, $value := .Data.Terms.Alphabetical }}
    {{- $name := .Name }}
    {{- $count := .Count }}
    {{- with $.Site.GetPage (printf "/%s/%s" $type $name) }}
    <li>
        <a href="{{ .Permalink }}">{{ .Name }} <sup><strong><sup>{{ $count }}</sup></strong></sup> </a>
    </li>
    {{- end }}
    {{- end }}
</ul>

{{- end }}{{/* end main */ -}}

自定义头部

  • Hugo提供了一个默认的文章使用模板,位于archetypes/default.md,里面包括一些基本内容标题、日期以及是否为草稿:
---
title: "{{ replace .Name "-" " " | title }}"
date: {{ .Date }}
draft: true
---
  • 为方便写作,我在Sulv博客 提供的模板上做了些许修改,在文件夹 archetypes 中创建post.md 文件,并写入:
---
title: "{{ replace .Name "-" " " | title }}"
date: {{ .Date }}
lastmod: {{ .Date }}
author: ["田少晗"]

categories:
- category 1
- category 2

tags:
- tag 1
- tag 2

keywords:
- word 1
- word 2

description: "" # 文章描述,与搜索优化相关
summary: "" # 文章简单描述,会展示在主页
weight: # 输入1可以顶置文章,用来给文章展示排序,不填就默认按时间排序
slug: ""
draft: false # 是否为草稿
comments: true
showToc: true # 显示目录
TocOpen: true # 自动展开目录
autonumbering: true # 目录自动编号
hidemeta: false # 是否隐藏文章的元信息,如发布日期、作者等
disableShare: true # 底部不显示分享栏
searchHidden: false # 该页面可以被搜索到
showbreadcrumbs: true #顶部显示当前路径
mermaid: true
cover:
    image: ""
    caption: ""
    alt: ""
    relative: false
---

<!-- more --> 

配置关于页面

根据定义好的模板,在此利用该模板生成关于页面,根目录执行执行命令:

hugo new --kind post content/about.md

内容管理

  • 我们写作的内容都是放在content目录下的,因此有必要对其内容有一个基本了解
  • 在官方文档 Content Management 中详尽地介绍了管理博客内容需要了解的所有信息,以下是我的一个目录结构,其中的 about.mdarchive.mdsearch.md 对应博客中的关于、时间轴和搜索:
content
├── posts
│   ├── _index.md
│   ├── life
│   │   └── _index.md
│   ├── read
│   │   └── _index.md
│   └── tech
│       └── _index.md
├── about.md
├── archive.md
└── search.md

以上目录结构看到出现了很多_index.md,官方参考文档在此Index Pages 。简而言之,这个文件是作为自定义索引页存在。这里给出我使用的一个_index.md作为参考:

---
title: "📚 文章"
# description: "学如逆水行舟,不进则退。"
hidemeta: true # 是否隐藏文章的元信息,如发布日期、作者等
---

学如逆水行舟,不进则退。

<!-- more -->

注意:根据个人博客具体分类将其生成到对应路径。

写在最后

到这里,个人博客的搭建配置也就基本完成了,如果想添加类似相册功能,可参考Hugo博客添加相册功能 | Sulv’s Blog ,效果如下,快去开启你的写作之旅! 🌻🌻

香克斯 香克斯 香克斯

参考文献

[1] GitHub | hugo-PaperMod

[2] Sulv’s Blog

[3] 3rd’s Blog