Hugo+docsy静态网站构建生成命令及配置备忘

常用命令

• 新建站点：hugo new site /path/tp/your/site；
• 启动hugo并开启调试：hugo server，浏览器输入 http://localhost:1313 可实时生成预览；
• 生成静态网页：hugo

docsy模板配置文件

文件名：hugo.toml，这是整个站点的配置文件。

前段时间因为升级docsy把这个文件覆盖了，导致整个网站的设置全部重置。

因此在这里记录一些基本的设置项，作为备份。

# 根目录的路径
baseURL = "https://t.imsail.com/"
# 站点title
title = "网站标题"

# 是否生成robots文件
enableRobotsTXT = true

# 主题选择，支持组合，优先级从左到右.
theme = ["docsy"]

# 页面上提供类似"最后修改"的信息（如果不用github貌似这个显示出不来）
enableGitInfo = true

# 国际化相关设置
# 默认语言的的站点内容路径
contentDir = "content/zh-cn"
# 默认语言
defaultContentLanguage = "zh-cn"
# 是否开启根路径重定位到"/content"上
defaultContentLanguageInSubdir = false
# 国际化翻译中，如果有缺失是否用占位符显示
# 若出现缺失，可以在根目录下的i18n文件夹对某种语言进行配置
enableMissingTranslationPlaceholders = true

# 注释后，可以关闭标签分类功能
disableKinds = ["taxonomy", "taxonomyTerm"]
[taxonomies]
# 生成的网页中，自定义标签、类别文件夹名称
tag = "tag"
category = "category"
[params.taxonomy]
# set taxonomyCloud = [] to hide taxonomy clouds
# 这个暂时没有研究出来是什么意思
taxonomyCloud = []
# 页面右侧通栏显示的标签、类别模块的标题
taxonomyCloudTitle = ["标签云", "类别"]
# 页面上方标题处显示的标签、类别对应的标签，留空则不显示
taxonomyPageHeader = ["本文标签", "本文分类"]

# 代码块高亮配置
pygmentsCodeFences = true
pygmentsUseClasses = false
# Use the new Chroma Go highlighter in Hugo.
pygmentsUseClassic = false
#pygmentsOptions = "linenos=table"
# See https://help.farbox.com/pygments.html
pygmentsStyle = "emacs"

# 配置各个分类所生成网页的路径
# 下面分别表示：小节、年、月、日、标题
[permalinks]
blog = "/:section/:year/:month/:day/:slug/"

# markdown渲染引擎配置: https://github.com/russross/blackfriday
# [blackfriday]
# plainIDAnchors = true
# hrefTargetBlank = true
# angledQuotes = false
# latexDashes = true

# 图片引擎处理: https://github.com/disintegration/imaging
[imaging]
resampleFilter = "CatmullRom"
quality = 75
anchor = "smart"

[services]
[services.googleAnalytics]
# 填写 Google Analytics (GA) 的id
# 若注释掉，则GA统计和页面底部的反馈[params.ui.feedback]都不会生效。
id = "UA-00000000-0"

# 语言配置
[languages]
[languages.zh-cn]
languageName ="中文"
# 用于多语言排序，越小越靠上。
weight = 1
[languages.zh-cn.params]
title = "XXX(中文文档)"
description = "xxx项目中文文档"
# 对应的日期表示方式，注意01表示月、02表示日
time_format_default = "2006.01.02"
time_format_blog = "2006年01月02日"

# 可继续增加其它语言（配置多语言后，菜单处可切换语言）
# [languages.en]
# languageName ="English"
# weight = 2
# [languages.en.params]
# title = "Goldydocs"
# description = "A Docsy example site"

# markdown的解析设置，抄的k8s的...
[markup]
  [markup.goldmark]
   [markup.goldmark.extensions]
     definitionList = true
     table = true
     typographer = false
   [markup.goldmark.parser]
     attribute = true
     autoHeadingID = true
     autoHeadingIDType = "blackfriday"
   [markup.goldmark.renderer]
     unsafe = true
  [markup.highlight]
    codeFences = true
    guessSyntax = false
    hl_Lines = ""
    lineNoStart = 1
    lineNos = false
    lineNumbersInTable = true
    noClasses = true
    style = "emacs"
    tabWidth = 4
  [markup.tableOfContents]
    endLevel = 3
    ordered = false
    startLevel = 2

# 下面的都是默认的站点配置，未做修改
# 对应右侧通栏上方的部分菜单，注释后，对应菜单会隐藏。
# Comment out if you don't want the "print entire section" link enabled.
[outputs]
section = ["HTML", "print", "RSS"]

[params]
# First one is picked as the Twitter card image if not set on page.
# images = ["images/project-illustration.png"]

# Menu title if your navbar has a versions selector to access old versions of your site.
# This menu appears only if you have at least one [params.versions] set.
version_menu = "Releases"

# Flag used in the "version-banner" partial to decide whether to display a 
# banner on every page indicating that this is an archived version of the docs.
# Set this flag to "true" if you want to display the banner.
archived_version = false

# The version number for the version of the docs represented in this doc set.
# Used in the "version-banner" partial to display a version number for the 
# current doc set.
version = "0.0"

# A link to latest version of the docs. Used in the "version-banner" partial to
# point people to the main doc site.
url_latest_version = "https://example.com"

# 方便用户反馈，提交技术文章问题的仓库地址
github_repo = "https://github.com/google/docsy-example"
# 技术站点背后的项目issue地址
github_project_repo = "https://github.com/google/docsy"

# 以下三个是设置远程文档位置的，目前用不上
# Specify a value here if your content directory is not in your repo's root directory
# github_subdir = ""

# Uncomment this if you have a newer GitHub repo with "main" as the default branch,
# or specify a new value if you want to reference another branch in your GitHub links
# github_branch= "main"

# 谷歌搜索的ID
# gcs_engine_id = "d72aa9b2712488cc3"

# Enable Algolia DocSearch(开启文档搜索?）
algolia_docsearch = true

# 是否开启离线搜索（貌似这个是与谷歌搜索二选一）
offlineSearch = true

# Enable syntax highlighting and copy buttons on code blocks with Prism
prism_syntax_highlighting = false

# 前段UI设置
[params.ui]
#  是否开启面包屑导航.
breadcrumb_disable = false
# 是否禁用底部About链接
footer_about_disable = true
# 是否展示项目logo，位置必须放置在 assets/icons/logo.svg
navbar_logo = true
# 在首页，上下滑动页面，顶部导航是否开启半透明
navbar_translucent_over_cover_disable = false
# 左侧章节树形目录是否默认折叠状态
sidebar_menu_compact = true
# 左侧章节树形目录上是否显示搜索框
sidebar_search_disable = false

# 如果关闭service的googleAnalytics分析，那么下面的选项会失效
[params.ui.feedback]
# 是否开启反馈功能
enable = true
# 点击“有帮助”或者“没有帮助”后显示的反馈文字
yes = '谢谢您的反馈！如有其它建议，<a href="https://p.imsail.com/page/contact">请点击这里留言</a>。'
no = '抱歉没能帮助到您！<a href="https://p.imsail.com/page/contact">请点击这里</a>，留下您宝贵的意见！'

# 在文章上面显示“阅读时长：x分钟”
[params.ui.readingtime]
enable = false

# 版权信息
[params.copyright]
  authors = "搏浪号博客</br>[联系站长](https://p.imsail.com/page/contact) | [京ICP备2023019113号](https://beian.miit.gov.cn/)"
  from_year = 2007

# 页面底部显示的图标及链接
[params.links]
# 底部左侧图标，可配置多个
[[params.links.user]]
  name = "联系站长"
  url = "https://p.imsail.com/page/contact"
  icon = "fa fa-envelope"
  desc = "点击此处联系本站站长"
[[params.links.user]]
  name ="逐浪吧"
  url = "https://t.imsail.com/"
  icon = "fas fa-blog"
  desc = "站长的个人博客"
# 底部右侧图标，可配置多个
[[params.links.developer]]
  name = "羊毛线报"
  url = "https://u.imsail.com/z"
  icon = "fa-solid fa-hand-holding-dollar"
  desc = "检索大额优惠券，实时更新优惠产品，羊毛薅到爽！"
[[params.links.developer]]
  name = "券多多 购实惠"
  url = "https://u.imsail.com/"
  icon = "fa-solid fa-store"
  desc = "最实惠的产品，最贴心的价格！"
  

参考网站

• hugo官网：https://gohugo.io/
• hugo中文文档：https://hugo.opendocs.io/
• docsy主题官网：https://github.com/google/docsy
• docsy主题文档：https://www.docsy.dev/docs/
• hugo学习笔记：https://skyao.io/learning-hugo/
• 基于Hugo构建的技术文档wiki站点：https://zhuanlan.zhihu.com/p/456747444