添加内容

​ 现在你有了一个带有 Docsy 的新 Hugo 站点，是时候添加一些内容了！本页面告诉你如何使用主题来添加和组织站点内容。

内容根目录

​ 你可以在你的 Hugo 站点项目的内容根目录下添加站点内容 - 即 content/ 或语言特定的根目录，比如 content/en/。这里的主要例外是你不想构建到站点中的静态文件：你可以在下面的添加静态内容中了解更多关于添加这些文件的位置。你的内容根目录中的文件通常按照站点章节和模板分组到子目录中，我们将在内容章节和模板中查看这些子目录。

​ 你可以在目录结构解释中了解有关 Hugo 目录结构的更多信息。

内容章节和模板

​ Hugo 使用你提供的内容文件和站点主题提供的任何模板来构建你的站点页面。这些模板（在 Hugo 术语中称为"layouts（布局）"）包括你的页面的页眉、页脚、导航和样式表链接：基本上除了页面的具体内容以外的一切。这些模板又可以由局部组成：用于页面元素（如页眉、搜索框等）的小型可重用 HTML 片段。

​ 因为大多数技术文档站点有不同的章节来存放不同类型的内容，Docsy 主题提供了以下顶级站点章节的模板：

• docs 用于你站点的文档章节的页面。
• blog 用于你站点的博客页面。
• community 用于你站点的社区页面。

​ 它还提供了一种默认的"着陆页"模板类型，带有站点页眉和页脚，但没有左侧导航，你可以用它来作为任何其他章节的模板。在这个站点和我们的示例站点中，它用于站点主页和About页面。

​ 你站点中的每个顶级章节都对应着站点内容根目录中的一个目录。根据内容所在的文件夹，Hugo 自动应用适当的模板来渲染该章节。例如，此页面位于站点内容根目录 content/en/ 的 docs 子目录中，因此 Hugo 自动应用 docs 模板。你可以通过显式指定特定页面的模板或内容类型来覆盖此行为。

​ 如果你复制了示例站点，则已经拥有适当命名的顶级章节目录来使用 Docsy 的模板，每个目录都有一个索引页面（ _index.md 或 index.html）供用户访问。这些顶级章节也会出现在示例站点的顶级菜单中。

自定义章节

​ 如果您复制了示例站点，但并不想使用提供的任何内容章节之一，只需删除相应的内容子目录即可。同样，如果您想添加一个顶级章节，只需添加一个新的子目录，但如果您想使用除默认模板之外的任何现有Docsy模板，则需要在每个页面的frontmatter中明确指定布局或内容类型。例如，如果您创建一个新目录content/en/amazing，并且希望该自定义章节中的一个或多个页面使用Docsy的docs模板，则在每个页面的前置元数据中添加type: docs：

• Front matter:
• toml
• yaml
• json

+++
title = "My amazing new section"
weight = 1
type = "docs"
description = '''
A special section with a docs layout.
'''
+++

---

title: "My amazing new section"
weight: 1
type: docs
description: >
  A special section with a docs layout  
---

{
  "title": "My amazing new section",
  "weight": 1,
  "type": "docs",
  "description": "A special section with a docs layout.\n"
}

​ 或者，根据现有模板，在您项目的layouts目录中为您的新章节创建自己的页面模板。

​ 您可以在Hugo模板中了解更多有关Hugo页面布局的工作原理。本页面的其余部分将告诉您如何添加内容并使用Docsy的每个模板。

替代站点结构

​ 如上所述，默认情况下，您的站点具有主页（使用_default布局），/docs/下的文档章节，/blog/下的博客章节和/community/下的社区章节。每个章节的类型（确定其使用的布局）与其目录名称匹配。

​ 在某些情况下，您可能希望具有不同的目录结构，但仍要利用Docsy的布局。一个常见的例子是"文档站点"，其中大多数页面（包括主页）都使用文档布局，或者您可能更喜欢将/news/目录视为博客布局。

​ 自Hugo 0.76以来，通过使用目标特定级联前置元数据，而不需要复制布局到您的站点或在每个页面上都指定type: blog，这已经变得可行。

​ 例如，对于/news/章节，您可以在index 页面中指定以下前置元数据，这将更改该章节及其以下所有内容的类型为"blog"：

• Front matter:
• toml
• yaml
• json

+++
title = "Latest News"
linkTitle = "News"

[menu.main]
weight = 30

[[cascade]]
type = "blog"
+++

---

title: "Latest News"
linkTitle: "News"
menu:
  main:
    weight: 30

cascade:

- type: "blog"

---

{
  "title": "Latest News",
  "linkTitle": "News",
  "menu": {
    "main": {
      "weight": 30
    }
  },
  "cascade": [
    {
      "type": "blog"
    }
  ]
}

​ 如果您想创建一个"docs"站点，则在顶级_index.md中指定类似以下内容将使所有顶级章节都被视为"文档"，除了"news"：

• Front matter:
• toml
• yaml
• json

+++
title = "My Wonderful Site"

[[cascade]]
type = "blog"
toc_root = true

  [cascade._target]
  path = "/news/**"

[[cascade]]
type = "docs"

[cascade._target]
  path = "/**"
+++

---

title: "My Wonderful Site"

cascade:

- type: "blog"
    toc_root: true
    _target:
    path: "/news/**"
- type: "docs"
    _target:
    path: "/**"

---

{
  "title": "My Wonderful Site",
  "cascade": [
    {
      "type": "blog",
      "toc_root": true,
      "_target": {
        "path": "/news/**"
      }
    },
    {
      "type": "docs",
      "_target": {
        "path": "/**"
      }
    }
  ]
}

请注意，这里增加了toc_root。将其设置为true，可以使其被视为站点的单独部分，具有自己的左侧导航菜单。

​ 使用此技术的示例基于文档的站点可在mostly docs repo中找到。

页面前置元数据

​ Hugo站点中的每个页面文件都有元数据前置元数据，告诉Hugo有关页面的信息。您可以在TOML、YAML或JSON中指定页面前置元数据（我们的示例站点和此站点使用YAML）。使用前置元数据指定页面标题、描述、创建日期、链接标题、模板、菜单权重，甚至包括页面使用的任何资源，如图像。您可以在前置元数据中查看可能的页面前置元数据的完整列表。

例如，这是本页面的前置元数据：

• Front matter:
• toml
• yaml
• json

+++
title = "Adding Content"
linkTitle = "Adding Content"
weight = 1
description = '''
Add different types of content to your Docsy site.
'''
+++

---

title: "Adding Content"
linkTitle: "Adding Content"
weight: 1
description: >
  Add different types of content to your Docsy site  
---

{
  "title": "Adding Content",
  "linkTitle": "Adding Content",
  "weight": 1,
  "description": "Add different types of content to your Docsy site.\n"
}

​ 你需要提供的最基本的前置元数据是title（标题）：其他的内容都由你决定！然而，如果你没有设置页面weight（权重），你的导航可能会有点混乱。你可能还想包括description，因为 Docsy 使用它来生成搜索引擎使用的mata description 标签。详见Search Engine Optimization (SEO) meta tags。

页面内容和标记

​ 默认情况下，你可以像编写普通的 Markdown 或 HTML 文件一样，在 Docsy 站点上创建页面并添加frontmatter，就像上面描述的那样。从 0.100 版本开始，Goldmark是 Hugo 唯一支持的 Markdown 解析器。

• Configuration file:
• hugo.toml
• hugo.yaml
• hugo.json

[markup]
  [markup.goldmark]
    [markup.goldmark.renderer]
      unsafe = true

markup:
  goldmark:
    renderer:
      unsafe: true

{
  "markup": {
    "goldmark": {
      "renderer": {
        "unsafe": true
      }
    }
  }
}

​ 除了标记文本，你还可以使用 Hugo 和 Docsy 的 shortcodes（简码）：可重用的 HTML 片段，可以快速构建你的页面。在 Docsy Shortcodes 中了解更多关于简码的内容。

处理链接

​ Hugo 允许你使用普通的 Markdown 语法指定链接，但请记住，你需要将链接相对于你站点的根 URL 指定，而相对 URL 在你站点生成的 HTML 中不会被 Hugo 更改。

​ 或者，你可以使用 Hugo 的 helper ref 和 relref 简码来创建解析为正确 URL 的内部链接。但是，请注意，如果用户在你生成的站点之外查看你的页面，例如在 GitHub 的 Web UI 中使用渲染的 Markdown 功能，那么你的链接将根本不会出现为链接。

​ 你可以在 Hugo Tips 中找到（或添加！）有关处理 Hugo 链接的技巧和提示。

内容样式

​ 我们不强制要求您的页面内容采用任何特定的风格。然而，如果您需要一些关于如何编写和格式化清晰、简洁的技术文档的指导，我们推荐使用Google开发者文档风格指南，特别是其中的风格指南要点。

页面 bundles

​ 您可以将站点页面创建为其所在章节或子章节目录中的独立文件，或者作为包含内容的文件夹，其中内容在文件夹的index页中。为您的页面创建一个文件夹可以让您将图像和其他资源与内容捆绑（bundle）在一起。

​ 您可以在本站点和我们的示例站点中看到这两种方法的示例。例如，本页面的源代码只是一个独立的文件/content/en/docs/adding-content.md。然而，在本站点中，Docsy简码的源代码位于Docsy Shortcodes，该页面使用的图像资源位于同一个/shortcodes/目录中。在Hugo术语中，这被称为叶子bundle，因为它是一个文件夹，包含了单个站点页面的所有数据，没有任何子页面（并且使用了不带下划线的index.md）。

​ 您可以在页面Bundles中找到更多有关使用Hugo捆绑管理资源的信息。

Adding docs and blog posts

​ 您最常使用的模板可能是docs模板（如本页面所使用的）或非常相似的blog 模板。这两个模板都包括：

• a left nav
• GitHub链接（从您的站点配置中获取）供读者编辑页面或创建问题
• a page menu

以及所有站点页面都使用的常见页头和页脚。应用哪个模板取决于您是否将内容添加到blog或docs内容目录中。您可以在导航和搜索中了解有关如何创建导航和页面菜单的更多信息。

组织您的文档

​ 虽然Docsy的顶级章节允许您为不同类型的内容创建站点章节，但您可能还希望在docs章节内组织您的文档内容。例如，本站点的docs章节目录有多个子目录，用于入门、内容和自定义等。每个子目录都有一个_index.md（也可以是_index.html），它作为一个章节索引页，告诉Hugo相关目录是您的文档的子章节。

​ Docsy的docs布局为您提供了一个左侧导航窗格，其中包含根据您的文档文件结构自动生成的嵌套菜单。在docs/目录中的每个独立页面或子章节_index.md或_index.html页面都会获得一个顶级菜单项，使用页面或index中的链接名称和weight元数据。

​ 要向子章节添加文档，只需将页面文件添加到相应的子目录中。除子章节索引页面外，您添加到子章节的任何页面都将出现在子菜单中（请查看左侧以查看实际效果！），并按页面weight排序。在导航和搜索中了解有关添加Docsy导航元数据的更多信息。

​ 如果您已经复制了示例站点，则在您的docs目录中已经有一些建议的子目录，并提供了放置何种类型内容以及一些示例Markdown页面的指导。您可以在组织您的内容中了解更多关于使用Docsy组织内容的信息。

文档章节着陆页面

​ 默认情况下，文档章节着陆页（位于章节目录中的_index.md或_index.html）使用一种布局，该布局添加了一个格式化的链接列表，其中包含章节中的页面及其前置元数据描述。本站点中的内容和自定义着陆页面是一个很好的例子。

​ 要显示一个简单的链接条目列表，指定在着陆页面的前置元数据中simple_list: true：

• Front matter:
• toml
• yaml
• json

+++
title = "Simple List Page"
simple_list = true
weight = 20
+++

---

title: "Simple List Page"
simple_list: true
weight: 20
---

{
  "title": "Simple List Page",
  "simple_list": true,
  "weight": 20
}

To display no links at all, specify no_list: true in the landing page’s frontmatter:

• Front matter:
• toml
• yaml
• json

+++
title = "No List Page"
no_list = true
weight = 20
+++

---

title: "No List Page"
no_list: true
weight: 20
---

{
  "title": "No List Page",
  "no_list": true,
  "weight": 20
}

组织您的博客文章

​ Docsy的blog布局也为您提供了一个左侧导航菜单（如docs布局），以及应用于/blog/_index.md的列表类型index 页，自动按反向时间顺序显示所有最新文章的片段。

​ 要创建不同的博客类别以组织您的文章，请在blog/中创建子文件夹。例如，在我们的示例站点中，我们有news和releases。每个类别都需要有自己的_index.md或_index.html着陆页面文件，指定类别标题以使其在左侧导航和顶级博客着陆页面上正确显示。这是releases的index 页面：

• Front matter:
• toml
• yaml
• json

+++
title = "New Releases"
linkTitle = "Releases"
weight = 20
+++

---

title: "New Releases"
linkTitle: "Releases"
weight: 20
---

{
  "title": "New Releases",
  "linkTitle": "Releases",
  "weight": 20
}

To add author and date information to blog posts, add them to the page frontmatter:

• Front matter:
• toml
• yaml
• json

+++
date = 2018-10-06T00:00:00.000Z
title = "Easy documentation with Docsy"
linkTitle = "Announcing Docsy"
description = "The Docsy Hugo theme lets project maintainers and contributors focus on content, not on reinventing a website infrastructure from scratch"
author = "Riona MacNamara"

[[resources]]
src = "**.{png,jpg}"
title = "Image #:counter"

[resources.params]
  byline = "Photo: Riona MacNamara / CC-BY-CA"
+++

---

date: 2018-10-06
title: "Easy documentation with Docsy"
linkTitle: "Announcing Docsy"
description: "The Docsy Hugo theme lets project maintainers and contributors focus on content, not on reinventing a website infrastructure from scratch"
author: Riona MacNamara
resources:

- src: "**.{png,jpg}"
    title: "Image #:counter"
    params:
    byline: "Photo: Riona MacNamara / CC-BY-CA"

---

{
  "date": "2018-10-06T00:00:00.000Z",
  "title": "Easy documentation with Docsy",
  "linkTitle": "Announcing Docsy",
  "description": "The Docsy Hugo theme lets project maintainers and contributors focus on content, not on reinventing a website infrastructure from scratch",
  "author": "Riona MacNamara",
  "resources": [
    {
      "src": "**.{png,jpg}",
      "title": "Image #:counter",
      "params": {
        "byline": "Photo: Riona MacNamara / CC-BY-CA"
      }
    }
  ]
}

​ 如果您已经复制了示例站点，并且不想要blog 章节，或者想链接到外部博客，只需删除blog子目录即可。

使用顶级着陆页面

​ Docsy的默认页面模板没有左侧导航，适用于为您的站点或其他"着陆"类型页面创建主页。

自定义示例站点页面

​ 如果你已经复制了示例站点，那么在 content/en/_index.html 文件中你已经有了一个简单的站点着陆页。它由 Docsy 提供的 Hugo shortcode page blocks组成。

​ 要自定义大的着陆图片（在一个封面（cover）块中），请将项目中的 content/en/featured-background.jpg 文件替换为你自己的图片（文件名中必须包含background），你可以添加或删除尽可能多的块，以及添加你自己的内容。

​ 示例站点还有一个About 页面，在 content/en/about/_index.html 中使用相同的 Docsy 模板。同样，它由page blocks组成，包括 content/en/about/featured-background.jpg 中的另一个背景图片。与站点着陆页一样，你可以替换图片、删除或添加块，或者添加你自己的内容。

构建你自己的着陆页

​ 如果你刚刚使用了这个主题，你仍然可以使用所有 Docsy 提供的 page blocks（或任何其他你想要的内容）在相同的文件位置构建自己的着陆页。

添加community 页面

​ community着陆页模板有样板内容，自动填充项目名称和在 hugo.toml/hugo.yaml/hugo.json 中指定的社区链接，为你的用户提供快速访问资源的链接，帮助他们参与你的项目。同样的链接也默认添加到你的站点页脚。

Configuration file:

• Configuration file:
• hugo.toml
• hugo.yaml
• hugo.json

[params.links]

# End user relevant links. These will show up on left side of footer and in the community page if you have one

[[params.links.user]]
 name = "User mailing list"
 url = "<https://example.org/mail>"
 icon = "fa fa-envelope"
        desc = "Discussion and help from your fellow users"
[[params.links.user]]
 name ="Twitter"
 url = "<https://example.org/twitter>"
 icon = "fab fa-x-twitter"
        desc = "Follow us on Twitter to get the latest news!"
[[params.links.user]]
 name = "Stack Overflow"
 url = "<https://example.org/stack>"
 icon = "fab fa-stack-overflow"
        desc = "Practical questions and curated answers"

# Developer relevant links. These will show up on right side of footer and in the community page if you have one

[[params.links.developer]]
 name = "GitHub"
 url = "<https://github.com/google/docsy>"
 icon = "fab fa-github"
        desc = "Development takes place here!"
[[params.links.developer]]
 name = "Slack"
 url = "<https://example.org/slack>"
 icon = "fab fa-slack"
        desc = "Chat with other project developers"
[[params.links.developer]]
 name = "Developer mailing list"
 url = "<https://example.org/mail>"
 icon = "fa fa-envelope"
        desc = "Discuss development issues around the project"

params:
  links:
    user:
      - name: User mailing list
        url: '<https://example.org/mail>'
        icon: fa fa-envelope
        desc: Discussion and help from your fellow users
      - name: Twitter
        url: '<https://example.org/twitter>'
        icon: fab fa-x-twitter
        desc: Follow us on Twitter to get the latest news!
      - name: Stack Overflow
        url: '<https://example.org/stack>'
        icon: fab fa-stack-overflow
        desc: Practical questions and curated answers
    developer:
      - name: GitHub
        url: '<https://github.com/google/docsy>'
        icon: fab fa-github
        desc: Development takes place here!
      - name: Slack
        url: '<https://example.org/slack>'
        icon: fab fa-slack
        desc: Chat with other project developers
      - name: Developer mailing list
        url: '<https://example.org/mail>'
        icon: fa fa-envelope
        desc: Discuss development issues around the project

{
  "params": {
    "links": {
      "user": [
        {
          "name": "User mailing list",
          "url": "https://example.org/mail",
          "icon": "fa fa-envelope",
          "desc": "Discussion and help from your fellow users"
        },
        {
          "name": "Twitter",
          "url": "https://example.org/twitter",
          "icon": "fa-brands fa-x-twitter",
          "desc": "Follow us on Twitter to get the latest news!"
        },
        {
          "name": "Stack Overflow",
          "url": "https://example.org/stack",
          "icon": "fa-brands fa-stack-overflow",
          "desc": "Practical questions and curated answers"
        }
      ],
      "developer": [
        {
          "name": "GitHub",
          "url": "https://github.com/google/docsy",
          "icon": "fa-brands fa-github",
          "desc": "Development takes place here!"
        },
        {
          "name": "Slack",
          "url": "https://example.org/slack",
          "icon": "fa-brands fa-slack",
          "desc": "Chat with other project developers"
        },
        {
          "name": "Developer mailing list",
          "url": "https://example.org/mail",
          "icon": "fa fa-envelope",
          "desc": "Discuss development issues around the project"
        }
      ]
    }
  }
}

​ 如果你正在创建自己的站点，想要使用这个模板添加页面，请在你的内容根目录中添加一个 /community/_index.md 文件。如果你复制了示例站点，并不想要一个社区页面，请在项目存储库中删除 /content/en/community/ 目录。

添加静态内容

​ 你可能想要将一些非 Hugo 构建的内容与你的站点一起提供：例如，如果你使用 Doxygen、Javadoc 或其他文档生成工具生成参考文档。

​ 要添加静态内容以"原样（as-is）“提供，请在站点的 static 目录中添加文件夹和/或文件。在部署站点时，该目录中的内容将在站点根路径下提供服务。因此，例如，如果你在 /static/reference/cpp/ 添加了内容，用户可以在 http://{server-url}/reference/cpp/ 访问该内容，你可以从其他页面在 /reference/cpp/{file name} 上链接到该目录中的页面。

​ 你还可以在该目录中使用你的项目使用的其他文件，包括图像文件。你可以在静态文件中了解更多关于提供静态文件的信息，包括配置多个静态内容目录。

RSS 订阅

​ Hugo 默认会为主页和任何章节创建一个 RSS 订阅。对于主 RSS 订阅，你可以通过设置 hugo.toml/hugo.yaml/hugo.json 中的站点参数来控制包含哪些章节。这是默认配置：

• Configuration file:
• hugo.toml
• hugo.yaml
• hugo.json

[params]
rss_sections = ["blog"]

params:
  rss_sections: [blog]

{
  "params": {
    "rss_sections": [
      "blog"
      ]
  }
}

To disable all RSS feeds, add the following to your hugo.toml/hugo.yaml/hugo.json:

• Configuration file:
• hugo.toml
• hugo.yaml
• hugo.json

[params]
disableKinds = ["RSS"]

params:
  disableKinds: [RSS]

{
  "params": {
    "disableKinds": [
      "RSS"
      ]
  }
}

[outputs]
section = [ "HTML", "RSS", "print" ]

outputs:
  section:
    - HTML
    - RSS
    - print

{
  "outputs": {
    "section": [
      "HTML",
      "RSS",
      "print"
    ]
  }
}

Sitemap

​ Hugo默认为您的生成站点创建sitemap.xml文件：例如，这是本站的sitemap。

​ 您可以在hugo.toml/hugo.yaml/hugo.json中配置您的sitemap更新频率、sitemap文件名和默认页面优先级：

• Configuration file:
• hugo.toml
• hugo.yaml
• hugo.json

[sitemap]
  changefreq = "monthly"
  filename = "sitemap.xml"
  priority = 0.5

sitemap:
  changefreq: monthly
  filename: sitemap.xml
  priority: 0.5

{
  "sitemap": {
    "changefreq": "monthly",
    "filename": "sitemap.xml",
    "priority": 0.5
  }
}

To override any of these values for a given page, specify it in page frontmatter:

• Front matter:
• toml
• yaml
• json

+++
title = "Adding Content"
linkTitle = "Adding Content"
weight = 1
description = '''
Add different types of content to your Docsy site.
'''
[sitemap]
priority = 1
+++

---

title: "Adding Content"
linkTitle: "Adding Content"
weight: 1
description: >
  Add different types of content to your Docsy site.  
sitemap:
  priority: 1.0
---

{
  "title": "Adding Content",
  "linkTitle": "Adding Content",
  "weight": 1,
  "description": "Add different types of content to your Docsy site.\n",
  "sitemap": {
    "priority": 1
  }
}

​ 要了解有关配置站点地图的更多信息，请参阅Sitemap模板。