Skip to content

Commit 53ce269

Browse files
smainzsmainz
committed
Update user guide
1 parent b3145f0 commit 53ce269

File tree

1 file changed

+257
-3
lines changed

1 file changed

+257
-3
lines changed

‎userguide/content/en/docs/adding-content/repository-links.md

+257-3
Original file line numberDiff line numberDiff line change
@@ -15,11 +15,265 @@ The Docsy [docs and blog layouts](/docs/adding-content/content/#adding-docs-and-
1515

1616
This page shows you how to configure these links.
1717

18-
Currently, Docsy supports only GitHub repository links "out of the box". Since GitLab can handle the same link scheme, it should work as well. If you are using another repository such as Bitbucket and would like generated repository links, feel free to [add a feature request or update our theme](/docs/contribution-guidelines/).
18+
Currently, Docsy supports GitHub, Azure DevOps, GitLab and Gitea repository links "out of the box". If you are using another repository such as Bitbucket and would like generated repository links, you can add a custom template to render the links. Feel free to [add a feature request or update our theme](/docs/contribution-guidelines/).
1919

2020
## Link configuration
2121

22-
There are four site variables you can configure in `hugo.toml`/`hugo.yaml`/`hugo.json` to set up links, as well as one in your page metadata.
22+
There are a few site variables you can configure in `hugo.toml`/`hugo.yaml`/`hugo.json` to set up links, as well as in your page metadata.
23+
24+
{{< tabpane >}}
25+
{{< tab header="Configuration file:" disabled=true />}}
26+
{{< tab header="hugo.toml" lang="toml" >}}
27+
[params.repo]
28+
type = "github"
29+
url = "https://github.com/google/docsy"
30+
subdir = "userguide"
31+
branch = "release"
32+
project_url = "https://github.com/google/docsy"
33+
{{< /tab >}}
34+
{{< tab header="hugo.yaml" lang="yaml" >}}
35+
params:
36+
repo:
37+
type: github
38+
url: https://github.com/google/docsy
39+
subdir: "userguide"
40+
branch: "release"
41+
project_url: "https://github.com/google/docsy"
42+
{{< /tab >}}
43+
{{< tab header="hugo.json" lang="json" >}}
44+
{
45+
"params": {
46+
"repo": {
47+
"type": "github",
48+
"url": "https://github.com/google/docsy",
49+
"subdir": "userguide",
50+
"branch"= "release",
51+
"project_url" = "https://github.com/google/docsy"
52+
}
53+
}
54+
}
55+
{{< /tab >}}
56+
{{< /tabpane >}}
57+
58+
### `repo.type`
59+
60+
Repo Links are created differently for different types of git repositories. Currently Docsy supports [GitHub](https://www.github.com), [Azure DevOps](https://azure.microsoft.com/products/devops), [GitLab](https://about.gitlab.com) and [Gitea](https://about.gitea.com). Specify the type of repository you are using, supported values are `github`, `azure`, `gitlab`, `gitea`.
61+
62+
Other repo types:
63+
64+
* [Forgejo](https://forgejo.org) is a fork of gitea and uses the same link schema as gitea, so you can use `type: gitea`.
65+
* To use a **custom repository type**
66+
* define `type: custom` in your configuration and
67+
* place a custom template in your project at `layouts/partials/repo-links-custom.html` which will be used to render the links.
68+
Instead of `custom` you can use any type, you like.
69+
70+
### `repo.url`
71+
72+
The URL for your site's source repository. This is used to generate the *Edit this page*, *Create child page*, and *Create documentation issue* links.
73+
74+
### `repo.subdir` (optional)
75+
76+
Specify a value here if your content directory is not in your repo's root directory. For example, this site is in the userguide subdirectory of its repo. Setting this value means that your edit links will go to the right page.
77+
78+
### `repo.branch` (optional)
79+
80+
Specify a value here if you have would like to reference a different branch than `main` in the links to your repository like *Edit this page*.
81+
82+
### `repo.project_url` (optional)
83+
84+
Specify a value here if you have a separate project repo and you'd like your users to be able to create issues against your project from the relevant docs. The *Create project issue* link appears only if this is set.
85+
86+
It is assumed that the `project_url` points to the same type of git repository as your documentation site.
87+
88+
### `path_base_for_subdir` (optional)
89+
90+
Suppose that the source files for all of the pages under `content/some-section`
91+
come from another repo, such as a [git submodule][]. Add settings like these to
92+
the **section's index page** so that the repository links for all pages in that
93+
section refer to the originating repo:
94+
95+
{{< tabpane >}}
96+
{{< tab header="Front matter:" disabled=true />}}
97+
{{< tab header="toml" lang="toml" >}}
98+
+++
99+
title = "Some super section"
100+
[cascade.repo]
101+
type = "github"
102+
url = "https://github.com/some-username/another-repo/"
103+
subdir = "docs"
104+
path_base_for_subdir = "content/some-section"
105+
…
106+
+++
107+
{{< /tab >}}
108+
{{< tab header="yaml" lang="yaml" >}}
109+
---
110+
title: Some super section
111+
cascade:
112+
repo:
113+
type: github
114+
url: https://github.com/some-username/another-repo/
115+
subdir: docs
116+
path_base_for_subdir: content/some-section
117+
…
118+
---
119+
{{< /tab >}}
120+
{{< tab header="json" lang="json" >}}
121+
{
122+
"title": "Some super section",
123+
"cascade": {
124+
repo: {
125+
"type": "github",
126+
"url": "https://github.com/some-username/another-repo/",
127+
"subdir": "docs",
128+
"path_base_for_subdir": "content/some-section"
129+
}
130+
}
131+
}
132+
{{< /tab >}}
133+
{{< /tabpane >}}
134+
135+
As an example, consider a page at the path
136+
`content/some-section/subpath/some-page.md` with `branch` globally set to
137+
`main`. The index page settings above will generate the following edit link for
138+
`some-page.md`:
139+
140+
```nocode
141+
https://github.com/some-username/another-repo/edit/main/docs/subpath/some-page.md
142+
```
143+
144+
To make it clear, without the settings in the sections index page, the edit link would be:
145+
146+
```nocode
147+
https://github.com/google/docsy/edit/main/userguide/content/some-section/subpath/some-page.md
148+
```
149+
150+
If you only have a single page originating from another repo, then omit the
151+
`cascade` key and write, at the top-level, the same settings as illustrated
152+
above.
153+
154+
If you'd like users to create project issues in the originating project repo as well,
155+
then also set `project_url`, something like this:
156+
157+
{{< tabpane >}}
158+
{{< tab header="Front matter:" disabled=true />}}
159+
{{< tab header="toml" lang="toml" >}}
160+
+++
161+
…
162+
[cascade.repo]
163+
url = "https://github.com/some-username/another-repo/"
164+
project_url = "https://github.com/some-username/another-repo/"
165+
…
166+
+++
167+
{{< /tab >}}
168+
{{< tab header="yaml" lang="yaml" >}}
169+
---
170+
…
171+
cascade:
172+
repo:
173+
url: &repo https://github.com/some-username/another-repo/
174+
project_url: *repo
175+
…
176+
---
177+
{{< /tab >}}
178+
{{< tab header="json" lang="json" >}}
179+
{
180+
…
181+
"cascade": {
182+
"repo": {
183+
"url": "https://github.com/some-username/another-repo/",
184+
"project_url": "https://github.com/some-username/another-repo/"
185+
}
186+
}
187+
…
188+
}
189+
{{< /tab >}}
190+
{{< /tabpane >}}
191+
192+
{{% alert title="Tip" %}}
193+
Please note that the YAML code fragment makes use of [Yaml anchor](https://support.atlassian.com/bitbucket-cloud/docs/yaml-anchors/). Use of Yaml anchors is optional, but it helps keep the settings [DRY](https://en.wikipedia.org/wiki/Don%27t_repeat_yourself).
194+
{{% /alert %}}
195+
196+
The `path_base_for_subdir` setting is a regular expression, so you can
197+
use it even if you have a site with [multiple languages][] for example:
198+
199+
{{< tabpane >}}
200+
{{< tab header="Front matter:" disabled=true />}}
201+
{{< tab header="toml" lang="toml" >}}
202+
+++
203+
…
204+
path_base_for_subdir = "content/\w+/some-section"
205+
…
206+
+++
207+
{{< /tab >}}
208+
{{< tab header="yaml" lang="yaml" >}}
209+
---
210+
…
211+
path_base_for_subdir: content/\w+/some-section
212+
…
213+
---
214+
{{< /tab >}}
215+
{{< tab header="json" lang="json" >}}
216+
{
217+
…
218+
"path_base_for_subdir": "content/\w+/some-section"
219+
…
220+
}
221+
{{< /tab >}}
222+
{{< /tabpane >}}
223+
224+
In situations where a page originates from a file under a different name, you
225+
can specify `from` and `to` path-rename settings. Here's an example where an
226+
index file is named `README.md` in the originating repo:
227+
228+
{{< tabpane >}}
229+
{{< tab header="Front matter:" disabled=true />}}
230+
{{< tab header="toml" lang="toml" >}}
231+
+++
232+
…
233+
[repo]
234+
url = "https://github.com/some-username/another-repo/"
235+
subdir = "docs"
236+
237+
[repo.path_base_for_github_subdir]
238+
from = "content/some-section/(.*?)/_index.md"
239+
to = "$1/README.md"
240+
…
241+
+++
242+
{{< /tab >}}
243+
{{< tab header="yaml" lang="yaml" >}}
244+
---
245+
…
246+
repo:
247+
url: https://github.com/some-username/another-repo/
248+
subdir: docs
249+
path_base_for_github_subdir:
250+
from: content/some-section/(.*?)/_index.md
251+
to: $1/README.md
252+
…
253+
---
254+
{{< /tab >}}
255+
{{< tab header="json" lang="json" >}}
256+
{
257+
…
258+
"repo": {}
259+
"url": "https://github.com/some-username/another-repo/",
260+
"subdir": "docs",
261+
"path_base_for_subdir": {
262+
"from": "content/some-section/(.*?)/_index.md",
263+
"to": "$1/README.md"
264+
}
265+
},
266+
…
267+
}
268+
{{< /tab >}}
269+
{{< /tabpane >}}
270+
## GitHub configuration (deprecated)
271+
272+
{{% alert title="Deprecation note" color="warning" %}}
273+
These setting are deprecated. Use the params described in [Link Configuration][] instead.
274+
275+
[Link Configuration]: #link-configuration
276+
{{% /alert %}}
23277

24278
### `github_repo`
25279

@@ -361,7 +615,7 @@ Class names using the `--KIND` suffix were deprecated as of [v0.9.0].
361615

362616
To have page-source metadata displayed at the bottom of documentation pages and
363617
blog posts, set the `GitInfo` configuration parameter to `true`, and ensure that
364-
`params.github_repo` is defined.
618+
`params.repo.url` is defined.
365619

366620
A last-modified page note looks something like this:
367621

0 commit comments

Comments
 (0)