Hugo 结构

Cumulus 使用 Hugo 为我们的用户文档创建一个静态网站。本主题介绍 Hugo 的一些功能,这些功能会影响我们文档的创建和呈现方式。

如果您想提供反馈或提交新内容以包含在我们的文档中,请参阅本文档中的其他主题。

目录结构

Hugo 使用目录结构来支持多级内容、图像、模板等等。最高级别的目录包括

  • archetypes
  • content
  • data
  • resources
  • static
  • themes

它们的作用和内容在此处描述

目录描述
archetypes包含新内容(.md 文件)的模板文件。填充并添加默认的前言 (front matter)。通过调用 hugo new 来构建 Markdown 文件。
content包含构建到主站点中的所有部分和页面资源。此内容的排列方式决定了最终站点的结构和层次结构。
data包含 JSON 文件,这些文件将图像映射到 Cumulus 文档的先前版本中的页面。这些文件不由用户修改。
resources包含由 Hugo 生成的文件,并用作缓存以加速页面构建。这些文件不由用户修改。
static包含所有静态文件,包括配置文件和用户创建的图像。任何图像文件都应放置在 /static 目录中。
themes包含用于在已发布站点中显示内容的文档主题。Cumulus 使用 Book 主题作为基础主题。一个子目录 layouts 包含 go-html 模板(.html 文件),这些模板从 content 构建页面。

修改任何其他目录中的文件将对站点的整体外观和功能产生重大影响,因此请 提交错误报告 以请求更改站点。

前言 (Front Matter)

Hugo 中的每个页面都包含一个 .YAML 前言 (front matter) 标头。例如。

---
title: 802.1X Interfaces
weight: 101
toc: 3
---

Hugo 在站点生成过程中使用这些参数。Cumulus 文档团队使用这些参数来设置主题内的显示顺序、PDF 中的显示以及将内容放置在正确的产品和版本中。当您创建新的 Markdown 文件时,将提供这些值。在这种情况下,请提供标题,然后让文档团队根据需要修改任何其他参数。

图形内容

Cumulus 通过将静态图像放置在 /static/images/ 目录中来使用图形内容。此目录中的图像可供已发布的站点以及用于在本地显示内容的 Hugo 服务器访问。

Markdown 旨在提高速度和简洁性,因此在创作和自定义渲染内容方面受到限制。Hugo 没有将原始 HTML 插入 Markdown,而是提供了短代码或预定义的模板,可以从 Markdown 内容中调用它们,以满足您需要其他信息或格式化功能的情况。

Hugo 提供了几个内置的短代码,其中一部分对文档很有用。有关参考,所有内置短代码的完整 Hugo 文档位于 此处。我们使用内置的 figure 短代码。

我们不使用 refrelref 短代码进行超链接和引用,而是使用自定义的 link 短代码。

图像短代码

img 或图像短代码是一个自定义短代码。当您想在文本中内联插入图标或小图像时使用它。请注意,您不需要包含文件路径的 static/ 部分。可选地,可以使用 width 和/或 height 参数(以像素为单位指定)缩放图像。仅使用 widthheight 会按比例缩放图像。太宽而无法内联包含的图像会自动在新行上呈现。基本短代码是

{{< img src="/path/" >}}

例如
{{< img src="/images/icons/export-button.png" width="80" >}}

{{< img src="/images/cumulus-linux/evpn-basic-clos.png" width="700" >}}

Figure 短代码

figure 短代码是一个内置的 Hugo 短代码。当您想在新行上插入图像时使用它。此短代码使用 HTML <figure> 元素,包装 <img> 标记,并提供更多可选参数来指定图像的显示方式。基本短代码是

{{< figure src="/path/" >}}

可用的参数包括

参数描述
src要显示的图像的 URL
link超链接目标的 URL
alt如果无法显示图像的替代文本
title图像标题,放置在 figure 上方
caption图像标题说明,放置在 figure 下方
height图像高度,以像素为单位
width图像宽度,以像素为单位

例如

{{< figure src="/images/netq/sch-trace-result-small-card.png" alt="Results of a scheduled trace shown in the small card" caption="Scheduled Trace Result" width="200px" >}}

{{< figure src = “/images/cumulus-linux/evpn-basic-clos.png" width="700" >}}