添加新内容

现在您已经安装了 Hugo,克隆了 GitHub 存储库并运行了本地服务器,您可以向文档站点添加新内容。如果您是第一次来到这里,并且没有执行这些设置任务,请参阅做出更大贡献,然后再返回此处。

您可以提交新的段落、图像、章节和完整主题,以便纳入文档中。第一步是了解文档的组织方式,以便您可以将信息添加到正确的位置。其次,您需要熟悉或开始熟悉 Markdown 格式的编辑。此处包含了一些基础知识。要了解更多信息,请参阅资源

文档站点结构

您可以通过文件管理器或基于文本的编辑器查看文档站点结构。我们使用 VS Code 来开发文档,但您可以使用您选择的任何文本编辑器。

在 Cumulus Networks 文档站点中有两个目录对于创作新内容尤为重要

  • content/: 包含产品文档目录和文件
  • static/images/: 包含引用的图像

其他目录主要用于生成网站,但如果您有兴趣了解它们包含的内容及其用途,请参阅Hugo 结构

添加新页面

新页面使用 hugo new 添加到 /content 目录中,它依赖于 Hugo 原型;Markdown 模板,其中包含所需的前置信息(元数据)和默认值。它们特定于每个产品,并创建一个新的 .md (Markdown) 文件。

  1. 如果 hugo server 当前正在运行,请按 Ctrl+c 以退出终端窗口中的文档服务器。

  2. 添加页面

    • 要向 Cumulus Linux 4.1 添加一个名为 test_post 的新页面,请运行 hugo new cumulus-linux-41/test_post.md
    • 要向 Cumulus NetQ 3.0 添加一个名为 test_post 的新页面,请运行 hugo new cumulus-netq-30/test_post.md
    • 要在子主题中添加文件,请包含到该位置的完整路径。例如,运行 hugo new cumulus-linux-41/Layer-2/test_post.md

    不要忘记使用 .md 文件扩展名。

  3. 更改前置信息的 title 以反映新内容。

    有关前置信息参数的更多详细信息,请参阅Hugo 结构

  4. 更改 weight 值以确定页面在左侧菜单中的顺序。值越小,在节列表中排名越高。

  5. 更改 toc 值以匹配文件目录深度。您页面的 toc 值应比同一目录中 _index.md 文件的 toc 值大 1。

  6. 添加您的内容。

您还可以通过从某些编辑器中复制和粘贴现有文件来创建新页面。只需确保为文件提供新名称和新标题。某些编辑器允许您在目录树中拖放新创建的页面,以防您放置错误。

需要唯一的页面 title,以确保 link shortcode 正常工作。

添加新章节

在 Hugo 术语中,章节与文件夹相同。Hugo 根据章节在 /content 文件夹中的位置以及 .md 文件的名称来定义章节。添加章节就像添加一个新的子目录,并在该子目录中创建一个 _index.md 文件一样简单。这可以使用 hugo new 命令完成。

例如,要在 /content/cumulus-linux-41/ 中创建一个名为“Test Section”的新章节,请运行 hugo new cumulus-linux-41/Test_Section/_index.md

要在另一个章节下创建章节(嵌套章节),请包含到该位置的完整路径。例如,运行 hugo new cumulus-linux-41/Layer-2/Test_Section/_index.md

您还可以通过从某些编辑器中复制和粘贴现有文件夹来创建新章节。只需确保为章节提供新名称。某些编辑器允许您在目录树中拖放新创建的章节,以防您放置错误。

编辑内容

这些指南涵盖了您在创建新内容期间将遇到的大多数常见格式化任务。有关这些项目和其他格式化问题的更多详细信息,请参阅“Markdown 指南”。

添加文本

要在现有文件中添加或修改文本

  1. 在您的文本编辑器中打开文档目录。

    此示例显示了 VS Code 中的文档目录

  2. 展开 content 目录以查找感兴趣的产品。

  3. 展开产品目录和任何子目录,以查找包含您要更改的文本或要添加其他文本的文件。

  4. 打开相关文件并添加或修改所需的文本。

添加标题

如果您想在文档中添加新章节,则可以添加新标题,然后输入文本。要创建正确的标题级别,请使用两个井号 (#) 表示二级标题(文件标题是唯一的一级标题),或使用三个井号表示三级标题。

例如: ## 新主题### 新子主题

如果可能,请不要在标题中使用特殊字符,例如破折号和括号,因为这些字符可能会在创建链接或引用这些主题时引起问题。

有关使用 Markdown 写作的更多详细信息,请参阅本指南“资源”部分中的“Markdown 指南”。

向文本添加内联样式

通常需要强调重要文本,例如 UI 中的字段名称(粗体)、目录或文件名(斜体)和命令(计算机字体)。这些处理方式如下

  • 在单词或短语两侧使用单个星号 (*) 使文本变为斜体。
  • 在单词或短语两侧使用两个星号 (**) 使文本变为粗体。
  • 在命令两侧使用一个反引号 (`) 以计算机字体显示命令。

例如,此 markdown 将呈现以下格式化文本。

此文本将在渲染的站点中显示为斜体。

单词 italics 将在渲染的站点中显示为斜体。

此文本将在渲染的站点中显示为粗体。

单词 bold 将在渲染的站点中显示为粗体。

net show bgp 命令将以特殊字体渲染,并突出显示。

添加注释

您可以使用 notice shortcodes 向文件添加注释。我们支持四种类型的注释:提示 (Tip)、注意 (Note)、信息 (Info) 和警告 (Warning)。有关何时使用每种类型以及放置位置的更多详细信息,请参阅“Markdown 指南”。

此示例显示如何添加注释

  1. 在新行中,输入 notice shortcode。

  2. 在下一行中,输入注释的文本。

  3. 通过在注释文本后的行中添加 end notice 来完成注释。

这显示了一个示例注释

添加列表

项目符号列表是通过在每个项目的开头使用破折号 (-) 创建的。这将渲染为一个实心圆圈作为项目符号。您还可以通过简单地制表符缩进,然后使用破折号来创建二级项目符号。二级项目符号渲染为开放圆圈作为项目符号。

例如,此 markdown 呈现以下项目符号列表。

  • 一级项目符号
  • 一级项目符号
    • 二级项目符号
    • 二级项目符号
  • 一级项目符号

编号列表是通过在每个项目的开头使用数字创建的。您可以增加编号或始终使用一 (1)。您可以通过简单地制表符缩进,然后使用一来创建二级项目。一级项目渲染为 1、2、3 等等。二级项目渲染为 a、b、c 等等。

例如,以下任一 markdown 示例都呈现以下编号列表。

  1. 一级项目或步骤
  2. 一级项目或步骤
  3. 二级项目或子步骤
  4. 二级项目或子步骤
  5. 一级项目或步骤

添加图像

如果您有要添加的图像或图形(以 SVG 或 PNG 文件格式)

  1. 将文件复制或保存到关联产品的 static/images 中。

    例如,如果您正在编辑 Cumulus Linux 文件,请使用 static/images/cumulus-linux。对于 Cumulus NetQ 文件,请使用 static/images/netq/

  2. 在文件文本中,使用 figure 或 img shortcode 添加图像或图形引用

    可以选择通过添加 width 选项来缩放图像。宽度值以像素为单位定义。

    例如

    figure shortcode 将图形放在新行上。img shortcode 将图像与文本内联放置(除非它太宽而无法这样做)。

添加代码块

当您要呈现两行或多行代码时,使用代码块。要创建突出显示的框并相应地设置字体,请在代码之前的单独行中插入三个反引号 (`),并在代码之后的换行符中插入第二组三个反引号。

例如,此 markdown 呈现以下代码块。

cumulus@switch:~$ netq check bgp
bgp check result summary:

Checked nodes       : 8
Total nodes         : 8
Rotten nodes        : 0
Failed nodes        : 0
Warning nodes       : 0

Additional summary:
Total Sessions      : 30
Failed Sessions     : 0

Session Establishment Test   : passed
Address Families Test        : passed
Router ID Test               : passed

对于外部链接,可以使用标准 markdown 链接语法。链接文本放在方括号 [] 中,后跟括号 () 中的完整 URL。例如 [Link to Cumulus](https://www.cumulusnetworks.com) 生成链接 Link to Cumulus

不要在方括号和括号之间放置空格。

跨产品

要在产品之间链接,请将 Hugo 内置的 ref 函数与标准 Markdown 链接一起使用。使用与外部链接相同的语法,带有方括号 [] 和括号 ()。

为了正确生成链接页面的 URL,ref 代码需要链接文件的路径。例如,要链接到关于 NTP 的 Cumulus Linux 4.3 页面

[NTP]({{< ref "/cumulus-linux-43/System-Configuration/Setting-Date-and-Time">}})

要链接到产品的最新版本,例如 /cumulus-linux/cumulus-netq,请不要直接链接,而是使用 kb_link shortcode 并提供参数 latest 以及页面的文件路径。例如,要链接到最新的 Cumulus Linux NTP 页面

{{< kb_link latest="cl" url="System-Configuration/Date-and-Time/Network-Time-Protocol-NTP.md" text="NTP">}}

latest 支持 clnetqsonic。对于根页面 (_index.md),必须包含 _index.md 文件名。

在产品内

为了保持页面的可移植性,Hugo shortcode 用于同一章节中的所有页面。

link shortcode 与 title 参数一起使用。使用要链接页面的前置信息中的 Title 值。例如,要链接到“提供简单反馈”章节,请使用 shortcode {{< link title="Give Simple Feedback" >}}。默认情况下,链接标题是使用的链接文本。可以使用 text 属性指定文本。例如,{{< link title="Give Simple Feedback" text="How to give feedback">}} 生成链接 How to give feedback