Version main of the documentation is no longer actively maintained. The site that you are currently viewing is an archived snapshot. For up-to-date documentation, see the latest version.

代码库链接及其页面信息

帮助您的用户与您的源代码库进行交互。

Docsy 文档和博客布局包括让读者可以通过您的网站源代码仓库编辑页面或为您的文档或项目创建问题的链接。当前生成的每个文档或博客页面的链接如下：

View page source：将用户带到您的文档存储库中的页面源代码。
Edit this page：将用户带到页面内容的可编辑版本，位于他们的文档库复刻中（如果有的话）。如果用户没有您的文档库的当前 fork，则在进行编辑之前，将邀请他们创建一个 fork。然后，用户可以为您的文档创建拉取请求。
Create child page：将用户带到在他们的文档库 fork 中创建新文件的表单中。新文件将作为他们单击链接页面的子级位置。该表单将使用一个模板进行预填，用户可以编辑此模板以创建自己的页面。您可以通过将 assets/stubs/new-page-template.md 添加到您自己的项目中来更改此设置。
Create documentation issue：将用户带到一个新的 issue 表单，在其中，当前页面的名称为该问题的标题。
Create project issue（可选）：将用户带到项目仓库中的一个新的issue 表单。如果您有单独的项目和文档存储库，并且您的用户想要针对正在讨论的项目功能提交问题，而不是针对您的文档，那么这可能很有用。

此页面向您展示了如何配置这些链接。

目前，Docsy仅支持GitHub存储库链接。由于GitLab可以处理相同的链接方案，因此也应该有效。如果您正在使用其他存储库（例如Bitbucket）并希望生成存储库链接，请随时 add a feature request or update our theme。

链接配置

在 hugo.toml/hugo.yaml/hugo.json 文件中，有四个变量可以配置以设置链接，同时在您的页面元数据中也有一个变量可以配置。

`github_repo`

您站点的源代码仓库的URL。此链接用于生成Edit this page、Create child page和Create documentation issue等链接。

[params]
github_repo = "https://github.com/google/docsy"

params:
  github_repo: https://github.com/google/docsy

{
  "params": {
    "github_repo": "https://github.com/google/docsy"
  }
}

`github_subdir` (可选)

如果您的内容目录不在仓库的根目录中，请在此指定一个值。例如，此站点位于其仓库的 userguide 子目录中。设置此值意味着您的编辑链接将指向正确的页面。

[params]
github_subdir = "userguide"

params:
  github_subdir: userguide

{
  "params": {
    "github_subdir": "userguide"
  }
}

`github_project_repo` (可选)

如果您有一个单独的项目仓库，希望您的用户能够从相关的文档中创建项目issues，请在此指定一个值。只有在设置了此项后，Create project issue链接才会显示。

[params]
github_project_repo = "https://github.com/google/docsy"

params:
  github_project_repo: https://github.com/google/docsy

{
  "params": {
    "github_project_repo": "https://github.com/google/docsy"
  }
}

`github_branch` (可选)

如果您希望引用其他的 github 设置（如 Edit this page或 Create project issue）的不同分支，请在此指定一个值。

[params]
github_branch = "release"

params:
  github_branch: release

{
  "params": {
    "github_branch": "release"
  }
}

`path_base_for_github_subdir` (可选)

假设 content/some-section 下的所有页面的源文件来自另一个仓库，例如git 子模块。在该章节的索引页中添加以下设置，以便该章节中的所有页面的存储库链接均指向源仓库：

+++
title = "Some super section"
[cascade]
github_repo = "https://github.com/some-username/another-repo/"
github_subdir = "docs"
path_base_for_github_subdir = "content/some-section"
…
+++

---
title: Some super section
cascade:
  github_repo: https://github.com/some-username/another-repo/
  github_subdir: docs
  path_base_for_github_subdir: content/some-section
…
---

{
  "title": "Some super section",
  "cascade": {
    "github_repo": "https://github.com/some-username/another-repo/",
    "github_subdir": "docs",
    "path_base_for_github_subdir": "content/some-section"
  }
}

例如，考虑一个位于路径 content/some-section/subpath/some-page.md 的页面，全局 github_branch 设置为 main。上面的索引页面设置将为 some-page.md 生成以下编辑链接：

https://github.com/some-username/another-repo/edit/main/docs/subpath/some-page.md

如果您只有一个来自另一个仓库的页面，请省略 cascade 键，并编写与上面所示相同的顶级设置。

如果您希望用户也能在源仓库中创建项目问题，则还需设置 github_project_repo，例如：

---
...
cascade:
  github_repo: &repo https://github.com/some-username/another-repo/
  github_project_repo: *repo
...
---

+++
…
[cascade]
github_repo = "https://github.com/some-username/another-repo/"
github_project_repo = "https://github.com/some-username/another-repo/"
…
+++

---
…
cascade:
  github_repo: &repo https://github.com/some-username/another-repo/
  github_project_repo: *repo
…
---

{
  "cascade": {
    "github_repo": "https://github.com/some-username/another-repo/",
    "github_project_repo": "https://github.com/some-username/another-repo/"
  }
}

Tip

请注意，YAML 代码片段使用了 YAML 锚点。使用 YAML 锚点是可选的，但它有助于保持设置的 DRY（不重复自己）。

path_base_for_github_subdir 设置是一个正则表达式，因此即使您的站点包含多个语言，您仍然可以使用它，例如：

+++
…
path_base_for_github_subdir = "content/\w+/some-section"
…
+++

---
…
path_base_for_github_subdir: content/\w+/some-section
…
---

{
…
  "path_base_for_github_subdir": "content/\w+/some-section"
…
}

在某些情况下，页面来源于具有不同名称的文件，您可以指定 from 和 to 路径重命名设置。以下是一个例子，其中一个索引文件在来源仓库中命名为 README.md：

+++
…
github_repo = "https://github.com/some-username/another-repo/"
github_subdir = "docs"

[path_base_for_github_subdir]
from = "content/some-section/(.*?)/_index.md"
to = "$1/README.md"
…
+++

---
…
github_repo: https://github.com/some-username/another-repo/
github_subdir: docs
path_base_for_github_subdir:
  from: content/some-section/(.*?)/_index.md
  to: $1/README.md
…
---

{
  …
  "github_repo": "https://github.com/some-username/another-repo/",
  "github_subdir": "docs",
  "path_base_for_github_subdir": {
    "from": "content/some-section/(.*?)/_index.md",
    "to": "$1/README.md"
  },
  …
}

`github_url` (可选)

Deprecation note

This setting is deprecated. Use path_base_for_github_subdir instead.

在您的页面元数据中指定此值以设置此页面的特定编辑 URL，例如以下示例：

+++
title = "Some page"
github_url = "https://github.com/some-username/another-repo/edit/main/README.md"
…
+++

---
title: Some page
github_url: https://github.com/some-username/another-repo/edit/main/README.md
…
---

{
  "title": "Some page",
  "github_url": "https://github.com/some-username/another-repo/edit/main/README.md",
  …
}

如果您的页面源文件在多个 Git 存储库中，或需要非 GitHub URL，则可以使用此选项。使用此值的页面仅具有 Edit this page 链接。

禁用链接

您可以使用 CSS 有选择性地禁用（隐藏）链接。例如，将以下内容添加到 projects’s _styles_project.scss文件中，以从所有页面中隐藏 Create child page 链接：

.td-page-meta__child { display: none; }

Link kind	Class name
View page source	`.td-page-meta__view`
Edit this page	`.td-page-meta__edit`
Create child page	`.td-page-meta__child`
Create documentation issue	`.td-page-meta__issue`
Create project issue	`.td-page-meta__project-issue`

Of course, you can also use these classes to give repository links unique styles for your project.

Version note

Class names using the --KIND suffix were deprecated as of v0.9.0.

上次修改的页面元数据

将页面源元数据显示在文档页面的底部，以及博客文章中，将“GitInfo”配置参数设置为“true”，并确保定义了“params.github_repo”。

上次修改的页面注释如下所示：

Last modified November 29, 2023: Release v0.8.0 preparation (#1756) (6bb4f99)

Once enabled site-wide, you can selectively hide last-modified notes in a page or section by declaring the following style (optionally with a !important modifier — not shown):

.td-page-meta__lastmod { display: none; }

反馈

当前页面对你有帮助吗？

Glad to hear it!

Sorry to hear that. Please tell us how we can improve.

最后修改 July 6, 2024: Update repository-links.md (9bb5ce5)

代码库链接及其页面信息

链接配置

github_repo

github_subdir (可选)

github_project_repo (可选)

github_branch (可选)

path_base_for_github_subdir (可选)

Tip

github_url (可选)