Version:

Icon of a magnifying glass.

IN THIS ARTICLE

使用 Hugo 参与 O3DE 文档贡献

Open 3D Engine (O3DE) 文档网站使用 Hugo 静态网站生成器，并通过 Netlify 进行部署。

请参阅 o3de.org 的 README.md 了解构建说明和前提条件，以及 Git 工作流程 获取有关项目运作的更多信息。

添加新页面

  1. 导航到新页面在 /content/docs 下的目录。

  2. 为该页面创建一个新的 markdown 文件：

    • 如果页面是文档的一个新子部分，则为该子部分创建一个目录，然后创建一个名为 _index.md 的文件。
    • 如果页面是添加到文档的现有部分，则创建一个具有适当标题的文件。

    在这两种情况下，markdown 文件名和目录名都是页面 URL 的一部分。

  3. 至少在文件顶部添加以下前置元数据：

    ---
title: 页面标题
toc: true
---

    这会将页面添加到主文档菜单，并在每个页面上生成目录。

    某些部分使用 weight 前置元数据属性来排序页面，以及 description 属性。有关更多信息，请参阅 Hugo 文档 。

添加新指南

只有在维护者批准或您自己就是维护者的情况下，才添加新指南。

  1. 直接在 /content/docs 下添加一个新目录，并在该目录中创建一个 _index.md 文件。

  2. 添加以下前置元数据：

    ---
linktitle: 出现在左侧导航栏中的标题
title: 出现在页面顶部的标题
description: 页面的简短描述
weight: 数值
menu_uuid: example //见下方说明
guide_img: "/images/example/guide_img.svg" //见下方说明
---

    • menu_uuid 字段是指南的简短唯一标识符，不包含空格或特殊字符。该字段用于生成菜单手风琴的 CSS 类。

    • guide_img 字段是 /static 目录中图像的相对 URL，用作指南在学习页面上的图像。

添加重定向

如果您移动或重命名页面，最好添加从旧页面到新页面的重定向。这是通过 /static/_redirects 文件完成的。该文件映射到标准 Apache 重定向文件（.htaccess），并使用相同的语法添加重定向。

要添加重定向，请在 _redirects 文件中添加一行：

/old_url/partial/      /new_url/partial

添加顶部导航菜单项

通过网站仓库根目录中的 config.toml 文件向顶部导航添加一个新项：

[[menu.main]] // menu.main 是主导航菜单
name = "Learn" //菜单项的名称
url = "#" //相对 URL – 例如，`/docs` 链接到文档主页
weight = 4 //菜单排序
identifier = "learn" //用于构建带有子菜单项的菜单的标识符

有关更多信息，请参阅 Hugo 的菜单文档 。

菜单子项

如果您想要一个带有子菜单项下拉的菜单，请将下拉菜单的标签定义为菜单项，然后使用 parent 字段定义其子项，指向它们应显示在其下的项：

[[menu.main]]
name = "Community"
url = "#"
weight = 3 //顶部导航本身的菜单排序
identifier = "community" //与下方的 parent 字段匹配

[[menu.main]]
name = "Community subitem"
url = "#"
weight = 1 //下拉菜单中项目的菜单排序
parent = "community" //与上方的 identifier 匹配

[[menu.main]]
name = "Community subitem 2"
url = "#"
weight = 2 //下拉菜单中项目的菜单排序
parent = "community" //与上方的 identifier 匹配

添加或更新社交媒体帐户

社交媒体帐户作为数据存储在 config.toml 文件中，并通过循环读取到布局中。您可以添加任何您可以找到图标的社交媒体帐户！

[[params.social]]
name = "Discord" //社交媒体帐户的名称
url = "#" //指向的 URL
icon = "fas fa-envelope" //FontAwesome 图标类

社交媒体帐户的图标是 FontAwesome 图标 。社交媒体参数存储用于从 FontAwesome 库获取图标的 CSS 类。要找到这些类：

  1. 导航到特定图标的 FontAwesome 页面。例如， 这是 Discord 。

  2. 找到图标的 HTML 片段。在这种情况下，它如下所示：

    <i class="fab fa-discord"></i>

  3. 提取这两个类 - 例如，fab fa-discord。

  4. 将它们添加到 icon 字段。

更新顶层页面

O3DE 的顶层页面 – /docs、/download 和 /community – 都使用自定义布局。您需要具备 HTML 和 CSS（以及 Bootstrap ）的基本知识才能更新这些页面的外观和感觉。

在所有情况下，以下文件都是关键：

  • /assets/sass/custom.sass：存储布局的所有自定义 SCSS。
  • /assets/js/app.js：存储页面的 Javascript。如果您需要更新下载页面，这很重要，因为下载页面使用 Javascript 来解析浏览器的用户代理。
  • /layouts/partials/javascript.html：向页面添加 Javascript 文件。如果您想向站点添加新脚本，这很重要。

更新顶层页面内容

每个页面的主体内容（自由格式文本）存储在页面的 /content/.../_index.md 文件中。这是常规 markdown 内容，可以随时更新。

更新顶层页面布局结构

本节是 Hugo 布局/模板引擎的非常简要的概述。有关更多信息，请参阅 Hugo 的模板文档 。

理解 Hugo 布局结构

Hugo 布局遵循 查找顺序 。/layouts/_default 目录包含基本布局，如果没有更具体的布局可用，这就是 Hugo 渲染的内容。如果 Hugo 找到一个布局目录，例如 /layouts/download，它与内容目录 /content/download 具有相同的文件路径，它将布局应用于该内容页面及其子页面。如果找不到，它将应用 /layouts/_default 中的布局。

在布局目录中，Hugo 查找 4 种基本类型之一：

  • baseof.html：“基础"模板。除非您知道自己在做什么，否则不要覆盖此文件！
  • section.html：_index.md 文件或章节主页的模板。
  • single.html：目录中不是 _index.md 文件的文件的模板 – 即常规页面。
  • list.html：子页面列表的模板。由于这与 section.html 有些混淆，因此仅将此布局用于博客部分。

O3DE 站点中的大多数顶层页面都是没有子页面的 section.html 页面。

理解 Hugo 布局继承

如上所述，Hugo 查找越来越具体的布局，并应用它能找到的最具体的布局。然而，它也在布局文件内部通过允许您覆盖名为 main 的部分来做到这一点。

例如，让我们看看 /layouts/_default/baseof.html：

{{ $lang := site.LanguageCode }}
<!DOCTYPE html>
<html{{ with $lang }} lang="{{ . }}"{{ end }}>
  <head>
    <title>
      {{ block "title" . }}
        {{ site.Title }}
      {{ end }}
    </title>
    {{ partial "css.html" . }}
    {{ partial "favicon.html" . }}
  </head>

    <body>
      {{ partial "navbar.html" . }}
    <main>
      {{ block "main" . }}
      {{ end }}
    </main>
    {{ partial "javascript.html" }}
  </body>
</html>

接下来，让我们看看 /layouts/_default/section.html：

{{ define "main" }}
  <div class="container">
      <section class="row">
        <section class="col col-8">
          <h1 class="title">{{ .Page.Title | markdownify }}</h1>
          {{ with .Content }}
          <div class="content">
            {{ . }}
          </div>
          {{ end }}
        </section>
      </section>
    </div>
{{ end }}

请注意，section.html 仅定义了 main 块。在没有任何其他块的情况下，Hugo 依靠 baseof.html 来提供页面布局的其余部分。

这在其他子页面上以类似的方式工作，例如 /layouts/download.html：

{{ define "main" }}
{{ partial "download/hero.html" . }}
{{ with .Content }}
<section class="container-xl mt-5 pt-5">
  <div class="row">
    <div class="col-12">
      {{ . }}
    </div>
  </div>
</section>
{{ end }}
{{ partial "footer.html" . }}
{{ end }}

在这种情况下，布局执行以下操作：

  • 覆盖 /layouts/_default/section.html 的 main 部分。
  • 调用 /download/hero.html 部分模板（有关布局部分模板的更多信息，请参阅 Hugo 的部分模板文档 ）
  • 添加一个用于主体内容的 div（{{ with .Content }}）
  • 调用 footer.html 部分模板

因此，如果您想更新下载页面的工作方式，您可以从 /layouts/downloads/section.html 开始。但是，如果您需要在下载页面的 <head> 部分添加某些内容，则需要将 layouts/_default/baseof.html 复制到 /layouts/downloads 目录并在那里覆盖它。