文档教程【免费下载链接】nightWeekly Go Online Meetup via BilibiliGo 夜读通过 bilibili 在线直播的方式分享 Go 相关的技术话题每天大家在微信/telegram/Slack 上及时沟通交流编程技术话题。项目地址https://gitcode.com/gh_mirrors/ni/night点击查看免费下载本篇指南以仓库内themes/hugo-material-docs主题自带的 Getting Started 文档为主线系统讲解基于 Hugo 的 Material Design 风格文档站点的安装、初始化与全量配置项。当前项目Go 夜读 / night 仓库正是使用该主题构建站点的真实案例因此文中所有配置项都将对照仓库根目录的 config.toml 与主题源码给出可验证的落地参考。读完本文你将掌握从零搭建、主题参数调优到侧边栏菜单、Markdown 渲染定制的一整套实操方案。一、主题与文档背景hugo-material-docs是一个基于 Hugo 可以看到名称Material Docs协议MIT最低 Hugo 版本要求min_version 0.20标签material、documentation、docs、google analytics、responsive。本文对应的原版指南位于 themes/hugo-material-docs/exampleSite/content/getting-started/index.md它是exampleSite示例站点的一部分与示例配置文件 themes/hugo-material-docs/exampleSite/config.toml 配套用于演示一套完整的文档站点初始配置。值得一提的是当前 night 仓库的站点正是由该主题驱动仓库根目录的 config.toml 声明了theme hugo-material-docs。因此本文不仅讲解主题通用配置还会结合本仓库真实配置与主题模板源码说明每个参数最终是如何被消费的。二、安装 Hugo 与主题2.1 安装 HugoHugo 本身是一个单一二进制文件不依赖 Ruby、Python、PHP 等昂贵运行时也不需要任何数据库。只需下载最新版本并放入PATH即可使用具体安装方式可参考 Hugo 官方安装指南。安装完成后先用hugo version确认环境就绪终端中应显示类似如下的版本号hugo version # Hugo Static Site Generator v0.15 BuildDate: 2016-01-03T12:47:4701:00说明示例文档展示的是主题开发早期的 Hugo v0.15 输出当前仓库使用的主题在 theme.toml 中声明min_version 0.20因此实际运行时请确保 Hugo 版本不低于 0.20现代 Hugo 版本均满足。2.2 安装 Material Docs 主题在 Hugo 就绪后通过git将hugo-material-docs主题安装到站点的themes/目录# 创建一个新的 Hugo 站点 hugo new site my-awesome-docs # 进入站点的 themes 目录 cd my-awesome-docs/themes/ # 下载主题 git clone gitgithub.com:digitalcraftsman/hugo-material-docs.git对当前 night 仓库而言主题已经以子目录形式内置在仓库中即 themes/hugo-material-docs无需重复 clone。整个主题的布局骨架位于 themes/hugo-material-docs/layouts含_default、partials、shortcodes静态资源位于 themes/hugo-material-docs/static后续配置项的源码佐证都会指向这些文件。三、基于 exampleSite 快速起步安装完成后查看themes/hugo-material-docs/下的exampleSite目录即 themes/hugo-material-docs/exampleSite。该目录包含一份示例配置文件以及你正在阅读的这份内容本身它作为文档站点的示例配置存在。其中示例内容目录结构如下来自本仓库实际文件themes/hugo-material-docs/exampleSite/content/ ├── adding-content/ │ └── index.md # 如何添加内容 ├── getting-started/ │ └── index.md # 本文对应的快速上手指南 ├── license/ │ └── index.md # 许可证页 ├── roadmap/ │ └── index.md # 路线图页 └── index.md # 示例首页起步步骤至少将exampleSite中的config.toml复制到你的站点根目录必要时覆盖已有配置文件Hugo 自带开发服务器可以边改边看。在站点根目录启动hugo server打开localhost:1313Material 主题即可呈现之后即可开始撰写文档或继续阅读本文通过配置项定制主题外观与功能。四、config.toml 基础配置在部署站点之前应花几分钟调整config.toml中的站点信息。打开该文件基础部分如下baseurl https://example.com/ languageCode en-us title Material Docs [params] # General information author Digitalcraftsman description A material design theme for documentations. copyright Released under the MIT license各字段含义字段作用baseurl站点部署后的基础 URL所有相对资源都将以此解析languageCode站点语言代码如en-us、zh-cntitle站点标题显示在浏览器标题与页面顶部params.author作者信息主题会在文章页展示见 single.htmlparams.description站点描述主题会写入meta namedescription见 head.htmlparams.copyright页脚版权声明主题渲染为© 年份 copyright见 single.html对比本仓库根目录 config.toml 的真实用法baseurl https://talkgo.org/ title Go 夜读 theme hugo-material-docs metadataformat yaml canonifyurls true sectionPagesMenu main [params] author Go 夜读 SIG 小组 description Talk Go - Go source reading and offline technical discussion every Thursday night. copyright Released under the Apache 2.0 license可以看到仓库还额外声明了theme hugo-material-docs指定使用该主题以及sectionPagesMenu main让内容区块自动汇入主菜单。示例配置中使用的metadataformat yaml与canonifyurls true也在本仓库中得到沿用。五、主题选项Options逐项详解5.1 GitHub 集成如果项目托管在 GitHub可以在配置中加入仓库链接。当provider等于GitHub时主题会在侧边抽屉drawer中添加Download下载和Stars星标按钮并展示 star 数量[params] # Repository provider GitHub repo_url https://github.com/digitalcraftsman/hugo-material-docs该行为的源码实现在 drawer.html条件判断eq (trim .Site.Params.provider | lower) github且配置了repo_url时渲染下载与星标两个链接下载链接指向${repo_url}/archive/master.zip星标链接指向${repo_url}/stargazers页面顶部的仓库标识repo_id由 single.html 从repo_url中去除https://github.com/前缀后提取并注入 footer_js.html 中的base_url与repo_id变量供前端脚本统计 star 数使用。本仓库根配置即采用了该方案provider GitHub、repo_url https://github.com/talkgo/night见 config.toml。5.2 添加版本号若希望在抽屉的项目横幅旁显示当前版本可设置version[params] version 1.0.0这同时会改变下载按钮链接指向 GitHub 上对应版本标签的归档包前提是存在该精确版本号的 release tag。源码方面版本号由 drawer.html 渲染在站点标题旁strong{{ .Site.Title }} {{ with .Site.Params.version }}span classversion{{ . }}/span{{ end }}/strong。5.3 添加 Logo如果项目有 Logo可以通过logo变量添加到抽屉/导航中。理想情况下Logo 图片应为矩形最小分辨率 128×128且边缘留有一定空白。Logo 同时会被用作 iOS 上的 Web 应用图标。可以将 Logo 存放在站点的static/目录下并以相对该目录的路径引用也可以使用外部 URL[params] logo images/logo.png源码佐证drawer.html 在配置了logo时于横幅左侧渲染img src{{ $.Site.BaseURL }}{{ . }}head.html 同时将logo用作og:imagemeta propertyog:image并作为apple-mobile-web-app-title的关联图标。本仓库实际将 Logo 指向images/2018-12-11-night-reading-go.jpg对应仓库中的 static/images/2018-12-11-night-reading-go.jpg。5.4 添加自定义 FaviconFavicon 是显示在浏览器标签页中、页面标题旁的小图标。与 Logo 类似需要将 favicon 存放在static/中并以相对该目录的路径引用或使用外部 URL[params] favicon favicon.ico在 head.html 中favicon同时用于link relshortcut icon与link relicon且带默认值兜底若未配置则回退到images/favicon.ico。本仓库将其配置为images/favicon.ico见 config.toml。5.5 Google Analytics将UA-XXXXXXXX-X替换为你自己的跟踪代码即可启用 Google AnalyticsgoogleAnalytics UA-XXXXXXXX-X该参数在 footer_js.html 中被消费主题注入标准的ga(create/set/send)初始化代码并额外跟踪两类行为——站外链接点击记录outbound事件和搜索框失焦事件记录带查询词?q的 pageview。5.6 小规模微调自定义 CSS / JS主题提供了进行小调整的简单方式如修改外边距、文本居中。custom_css和custom_js选项允许你添加额外的 CSS 与 JS 文件。这些文件既可以位于本地/static目录也可以位于外部服务器如 CDN两种情况分别使用相对/static的路径或资源的绝对 URL[params] # Custom assets custom_css [ foo.css, bar.css ] custom_js [buzz.js]消费位置同样可以在主题模板中确认head.html 用{{ range .Site.Params.custom_css }}循环输出link relstylesheetfooter_js.html 用{{ range .Site.Params.custom_js }}循环输出script src。5.7 更换配色Google Material Design 的色板为每个主色primary和强调色accent定义了默认色相这使得改变主题整体外观非常容易。只需将palette.primary与palette.accent设置为色板中的任意颜色[params.palette] primary red accent light-green颜色名可大写或小写但必须与 Material Design 色板中的名称一致。合法取值包括red、pink、purple、deep-purple、indigo、blue、light-blue、cyan、teal、green、light-green、lime、yellow、amber、orange、deep-orange、brown、grey、blue-grey。其中最后三种brown、grey、blue-grey只能用作主色。当通过配置设置颜色后主题会额外引入一个名为palettes.css的 CSS 文件来定义这些配色。源码层面head.html 始终加载stylesheets/palettes.css并在body标签上输出palette-primary-primary与palette-accent-accent两个类名配合 static/stylesheets/palettes.css 中的规则完成着色。本仓库使用的配色为primary indigo、accent deep-purple见 config.toml。5.8 更换字体主题默认使用 Ubuntu 字体家族正文使用常规 sans-serif 字体代码使用等宽字体。两种字体均从 Google Fonts 加载可方便地替换为其他字体例如 Google 自家的 Roboto[params.font] text Roboto code Roboto Mono正文字体以字重 400 和 700 加载等宽字体以常规字重加载。该逻辑在 head.html 中实现{{ $text : or .Site.Params.font.text Roboto }} {{ $code : or .Site.Params.font.code Roboto Mono }} link relstylesheet href//fonts.googleapis.com/css?family{{ $text }}:400,700|{{ replace $code | safeURL }}注意模板中的默认值是 Roboto / Roboto Mono而本仓库在 config.toml 中显式配置为text Ubuntu、code Ubuntu Mono。5.9 语法高亮主题使用流行的 Highlight.js 库对代码示例着色默认主题名为Github并做了少量微调。如果你希望换用自己的主题可像前面一样将样式表放入static/目录并在配置中设置相对路径[params] # Syntax highlighting theme highlight_css path/to/theme.cssHighlight.js 本身由 footer_js.html 在页面底部引入并通过hljs.initHighlightingOnLoad()自动为代码块着色。另外本仓库根配置还通过 Hugo 内置的 Chroma 高亮器增强了代码块渲染pygmentscodefences true、pygmentsStyle tango见 config.toml二者按需配合使用。5.10 添加 GitHub / Twitter 账号如果拥有 GitHub 和/或 Twitter 账号可以通过设置github与twitter变量在抽屉中添加对应账号链接[social] twitter github digitalcraftsman对应模板在 drawer.html 的「关于作者」区块中配置了Site.Social.twitter时渲染 Twitter 链接配置了Site.Social.github时渲染 GitHub 链接配置了Site.Social.email时渲染邮件联系链接。本仓库在 config.toml 的[social]中声明了 GitHub、YouTube、Twitter、Facebook、Telegram、Slack 等多项社区入口。5.11 添加菜单项创建了第一批内容文件后可以在左侧侧边栏手动链接它们。一个菜单项的 schema 如下[[menu.main]] name Material url / weight 0 pre 参数说明name菜单中显示的标题url指向内容的相对 URLweight用于修改菜单项的顺序weight 越大菜单项越靠下pre可选允许在菜单链接前预置元素如一个图标。pre的渲染逻辑在 nav_link.html 中a ... href{{ $currentMenuEntry.URL | relURL}}{{ $currentMenuEntry.Pre }} {{ $currentMenuEntry.Name }}/a且当前页面匹配时会附加current类以高亮。5.12 嵌套菜单子菜单除了链接单个文件还可以通过嵌套菜单增强侧边栏把某个区块下的所有页面一次性列出而无需逐个手动链接。为此需要稍微扩展区块内每个内容文件的 frontmatter。下面的片段将该内容文件注册为某个已存在菜单项的「子项」menu: main: parent: Material identifier: link name weight: 0字段说明main指定内容文件加入哪个菜单。默认情况下main是主题唯一的菜单parent将内容文件注册到某个已存在的菜单项下本例为Material链接。注意frontmatter 中的parent必须与config.toml中对应菜单项的name完全一致identifier菜单中显示的链接文本理想情况下应与页面title同名weight调整嵌套链接在区块内的排列顺序。嵌套菜单的渲染由 nav.html 完成主题按Site.Menus.main.ByWeight遍历若菜单项有子项.HasChildren则输出一个span classsection分组标题并递归渲染其子项否则直接渲染nav_link。六、Markdown 渲染扩展BlackfridayHugo 使用 Blackfriday 处理内容。完整的选项说明可查阅 Hugo 官方文档的 Blackfriday 配置章节这里给出主题示例配置中启用的常用选项[blackfriday] smartypants true fractions true smartDashes true plainIDAnchors true各选项含义选项作用smartypants启用智能标点转换如将直引号转换为弯引号fractions将分数写法转换为 Unicode 分数符号smartDashes智能处理连字符与破折号plainIDAnchors生成不含文件名的纯锚点 ID本仓库根目录 config.toml 同样沿用了这组 Blackfriday 配置且将其放置在 Hugo 0.20 对应的[blackfriday]顶层配置段中。对于使用较新 Hugo 版本的项目这一能力已逐步被 Goldmark 渲染器取代可在升级站点时按 Hugo 官方迁移说明处理。七、在本仓库中的完整配置对照最后将本仓库根目录 config.toml 与主题示例配置做一次完整对照便于理解一个真实项目是如何组合运用上述所有选项的配置项exampleSite 示例值night 仓库实际值baseurlhttps://example.org/https://talkgo.org/titleMaterial DocsGo 夜读themehugo-material-docshugo-material-docsmetadataformatyamlyamlcanonifyurlstruetrueparams.authorDigitalcraftsmanGo 夜读 SIG 小组params.providerGitHubGitHubparams.repo_urlhttps://github.com/digitalcraftsman/hugo-material-docshttps://github.com/talkgo/nightparams.version1.0.0未启用params.logoimages/logo.pngimages/2018-12-11-night-reading-go.jpgparams.faviconimages/favicon.icoparams.palette.primaryredindigoparams.palette.accenttealdeep-purpleparams.fontUbuntu/Ubuntu MonoUbuntu/Ubuntu Mono[social]twitter/github/emailGitHub/YouTube/Twitter/Facebook/Telegram/Slack[blackfriday]四项全开四项全开其余在示例中声明但仓库未使用的选项如custom_css、custom_js、highlight_css、googleAnalytics等均保留为空值属于可随时启用的预留能力。至此从 Hugo 与主题的安装、exampleSite的快速起步、基础配置到 GitHub 集成、版本号、Logo、Favicon、Google Analytics、自定义资源、配色、字体、语法高亮、社交账号、菜单与嵌套菜单再到 Blackfriday 渲染选项一条完整且可复用的 Material Docs 主题配置链路已经打通。若需要继续深入可进一步阅读示例站点中的 adding-content 指南了解内容结构与 frontmatter 的写法。赞分享文档教程【免费下载链接】nightWeekly Go Online Meetup via BilibiliGo 夜读通过 bilibili 在线直播的方式分享 Go 相关的技术话题每天大家在微信/telegram/Slack 上及时沟通交流编程技术话题。项目地址https://gitcode.com/gh_mirrors/ni/night点击查看免费下载相关推荐Go 夜读站点主题实践Hugo Material Docs 主题的安装、配置与源码解析Go 夜读站点主题实践Hugo Material Docs 主题的安装、配置与源码解析 本指南以当前仓库 Go 夜读talkgo/night https:文档教程MXNet 文档站点的 Sphinx Material Design 主题 mxtheme安装、配置与二次构建指南MXNet 文档站点的 Sphinx Material Design 主题 mxtheme安装、配置与二次构建指南 本指南以 docs/python_docs人工智能深度学习机器学习Metallb文档网站搭建Hugo主题定制与内容管理Metallb文档网站搭建Hugo主题定制与内容管理 Metallb文档网站基于Hugo静态站点生成器构建采用hugo theme relearn主题框架云原生网络上一篇如何轻松上手Qwen大模型从入门到微调完整指南下一篇如何永久保存微信聊天记录WeChatMsg终极解决方案指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考