From 39dee41d41130c00e13b41dec201f27ed541ebb7 Mon Sep 17 00:00:00 2001 From: smainz Date: Wed, 24 Apr 2024 15:06:23 +0200 Subject: [PATCH 1/8] Fix wrong prefix in Windows --- layouts/partials/page-meta-links.html | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/layouts/partials/page-meta-links.html b/layouts/partials/page-meta-links.html index bda98e0a5..4e295f721 100644 --- a/layouts/partials/page-meta-links.html +++ b/layouts/partials/page-meta-links.html @@ -2,7 +2,8 @@ {{/* Class names ending with `--KIND` are deprecated in favor of `__KIND`, but we're keeping them for a few releases after 0.9.0 */ -}} {{ if .File -}} -{{ $path := strings.TrimPrefix (add hugo.WorkingDir "/") $.File.Filename -}} +{{ $path := strings.TrimPrefix hugo.WorkingDir $.File.Filename -}} +{{ $path := strings.TrimPrefix "/" $path -}} {{ $gh_repo := $.Param "github_repo" -}} {{ $gh_url := $.Param "github_url" -}} {{ $gh_subdir := $.Param "github_subdir" | default "" -}} From aa925743fb277a77be67d0abf12b9704d8558e79 Mon Sep 17 00:00:00 2001 From: smainz Date: Wed, 24 Apr 2024 15:12:45 +0200 Subject: [PATCH 2/8] Deprecate "github_*" params. Move the old code into 'repo-links-github-deprectaded.html' and call this partial. --- layouts/partials/page-meta-links.html | 44 +------------ .../repo-links-github-deprecated.html | 62 +++++++++++++++++++ 2 files changed, 63 insertions(+), 43 deletions(-) create mode 100644 layouts/partials/repo-links-github-deprecated.html diff --git a/layouts/partials/page-meta-links.html b/layouts/partials/page-meta-links.html index 4e295f721..f534c26b7 100644 --- a/layouts/partials/page-meta-links.html +++ b/layouts/partials/page-meta-links.html @@ -2,50 +2,8 @@ {{/* Class names ending with `--KIND` are deprecated in favor of `__KIND`, but we're keeping them for a few releases after 0.9.0 */ -}} {{ if .File -}} -{{ $path := strings.TrimPrefix hugo.WorkingDir $.File.Filename -}} -{{ $path := strings.TrimPrefix "/" $path -}} -{{ $gh_repo := $.Param "github_repo" -}} -{{ $gh_url := $.Param "github_url" -}} -{{ $gh_subdir := $.Param "github_subdir" | default "" -}} -{{ $gh_project_repo := $.Param "github_project_repo" -}} -{{ $gh_branch := $.Param "github_branch" | default "main" -}}
-{{ if $gh_url -}} - {{ warnf "Warning: use of `github_url` is deprecated. For details, see https://www.docsy.dev/docs/adding-content/repository-links/#github_url-optional" -}} - {{ T "post_edit_this" }} -{{ else if $gh_repo -}} - - {{/* Adjust $path based on path_base_for_github_subdir */ -}} - {{ $ghs_base := $.Param "path_base_for_github_subdir" -}} - {{ $ghs_rename := "" -}} - {{ if reflect.IsMap $ghs_base -}} - {{ $ghs_rename = $ghs_base.to -}} - {{ $ghs_base = $ghs_base.from -}} - {{ end -}} - {{ with $ghs_base -}} - {{ $path = replaceRE . $ghs_rename $path -}} - {{ end -}} - - {{ $gh_repo_path := printf "%s/%s/%s" $gh_branch $gh_subdir $path -}} - {{ $gh_repo_path = replaceRE "//+" "/" $gh_repo_path -}} - - {{ $viewURL := printf "%s/tree/%s" $gh_repo $gh_repo_path -}} - {{ $editURL := printf "%s/edit/%s" $gh_repo $gh_repo_path -}} - {{ $issuesURL := printf "%s/issues/new?title=%s" $gh_repo (safeURL $.Title ) -}} - {{ $newPageStub := resources.Get "stubs/new-page-template.md" -}} - {{ $newPageQS := querify "value" $newPageStub.Content "filename" "change-me.md" | safeURL -}} - {{ $newPageURL := printf "%s/new/%s?%s" $gh_repo (path.Dir $gh_repo_path) $newPageQS -}} - - {{ T "post_view_this" }} - {{ T "post_edit_this" }} - {{ T "post_create_child_page" }} - {{ T "post_create_issue" }} - {{ with $gh_project_repo -}} - {{ $project_issueURL := printf "%s/issues/new" . -}} - {{ T "post_create_project_issue" }} - {{ end -}} - -{{ end -}} + {{ partial "repo-links-github-deprecated.html" . -}} {{ with .CurrentSection.AlternativeOutputFormats.Get "print" -}} {{ T "print_entire_section" }} {{ end }} diff --git a/layouts/partials/repo-links-github-deprecated.html b/layouts/partials/repo-links-github-deprecated.html new file mode 100644 index 000000000..90c738b46 --- /dev/null +++ b/layouts/partials/repo-links-github-deprecated.html @@ -0,0 +1,62 @@ +{{/* cSpell:ignore querify subdir */ -}} +{{/* Class names ending with `--KIND` are deprecated in favor of `__KIND`, but we're keeping them for a few releases after 0.9.0 */ -}} + +{{ $path := strings.TrimPrefix hugo.WorkingDir $.File.Filename -}} +{{ $path := strings.TrimPrefix "/" $path -}} + +{{ $gh_repo := $.Param "github_repo" -}} +{{ $gh_url := $.Param "github_url" -}} +{{ $gh_subdir := $.Param "github_subdir" | default "" -}} +{{ $gh_project_repo := $.Param "github_project_repo" -}} +{{ $gh_branch := $.Param "github_branch" | default "main" -}} + +{{ with $.Param "github_repo" -}} + {{ warnf "Warning: use of `github_repo` is deprecated, use `repo.url` instead " -}} +{{ end -}} +{{ with $.Param "github_subdir" -}} + {{ warnf "Warning: use of `github_subdir` is deprecated, use `repo.subdir` instead " -}} +{{ end -}} +{{ with $.Param "github_branch" -}} + {{ warnf "Warning: use of `github_branch` is deprecated, use `repo.branch` instead " -}} +{{ end -}} +{{ with $.Param "github_project_repo" -}} + {{ warnf "Warning: use of `github_project_repo` is deprecated, use `repo.project_repo` instead " -}} +{{ end -}} + +{{ if $gh_url -}} + {{ warnf "Warning: use of `github_url` is deprecated. For details, see https://www.docsy.dev/docs/adding-content/repository-links/#github_url-optional" -}} + {{ T "post_edit_this" }} +{{ else if $gh_repo -}} + + {{/* Adjust $path based on path_base_for_github_subdir */ -}} + {{ $ghs_base := $.Param "path_base_for_github_subdir" -}} + {{ $ghs_rename := "" -}} + {{ if reflect.IsMap $ghs_base -}} + {{ $ghs_rename = $ghs_base.to -}} + {{ $ghs_base = $ghs_base.from -}} + {{ end -}} + {{ with $ghs_base -}} + {{ warnf "Warning: use of `path_base_for_github_subdir` is deprecated, use `repo.path_base_for_subdir` instead " -}} + {{ $path = replaceRE . $ghs_rename $path -}} + {{ end -}} + + {{ $gh_repo_path := printf "%s/%s/%s" $gh_branch $gh_subdir $path -}} + {{ $gh_repo_path = replaceRE "//+" "/" $gh_repo_path -}} + + {{ $viewURL := printf "%s/tree/%s" $gh_repo $gh_repo_path -}} + {{ $editURL := printf "%s/edit/%s" $gh_repo $gh_repo_path -}} + {{ $issuesURL := printf "%s/issues/new?title=%s" $gh_repo (safeURL $.Title ) -}} + {{ $newPageStub := resources.Get "stubs/new-page-template.md" -}} + {{ $newPageQS := querify "value" $newPageStub.Content "filename" "change-me.md" | safeURL -}} + {{ $newPageURL := printf "%s/new/%s?%s" $gh_repo (path.Dir $gh_repo_path) $newPageQS -}} + + {{ T "post_view_this" }} + {{ T "post_edit_this" }} + {{ T "post_create_child_page" }} + {{ T "post_create_issue" }} + {{ with $gh_project_repo -}} + {{ $project_issueURL := printf "%s/issues/new" . -}} + {{ T "post_create_project_issue" }} + {{ end -}} + +{{ end -}} From 4cc960ad17173e3fa320220eb98343b5e3554c51 Mon Sep 17 00:00:00 2001 From: smainz Date: Fri, 10 May 2024 15:11:38 +0200 Subject: [PATCH 3/8] Switch to 'repo.XXX' parameters and add new github repo links --- layouts/partials/page-meta-links.html | 27 +++++++++++++++++++++++++ layouts/partials/repo-links-github.html | 20 ++++++++++++++++++ userguide/hugo.yaml | 10 ++++++--- 3 files changed, 54 insertions(+), 3 deletions(-) create mode 100644 layouts/partials/repo-links-github.html diff --git a/layouts/partials/page-meta-links.html b/layouts/partials/page-meta-links.html index f534c26b7..45fd43deb 100644 --- a/layouts/partials/page-meta-links.html +++ b/layouts/partials/page-meta-links.html @@ -2,8 +2,35 @@ {{/* Class names ending with `--KIND` are deprecated in favor of `__KIND`, but we're keeping them for a few releases after 0.9.0 */ -}} {{ if .File -}} +{{ $file_path := strings.TrimPrefix hugo.WorkingDir $.File.Filename -}} +{{ $file_path := strings.TrimPrefix "/" $file_path -}} + +{{ $git_repo := $.Param "repo.url" -}} +{{ $git_branch := $.Param "repo.branch" | default "main" -}} +{{ $git_subdir := $.Param "repo.subdir" | default "" -}} +{{ $git_project_repo := $.Param "repo.project_repo" -}}
{{ partial "repo-links-github-deprecated.html" . -}} + {{- /* Adjust $file_path based on path_base_for_subdir */ -}} + {{ $git_path_replace_from := $.Param "repo.path_base_for_subdir" -}} + {{ $git_path_replace_to := "" -}} + {{ if reflect.IsMap $git_path_replace_from -}} + {{ $git_path_replace_to = $git_path_replace_from.to -}} + {{ $git_path_replace_from = $git_path_replace_from.from -}} + {{ end -}} + {{ $git_path := $file_path }} + {{ with $git_path_replace_from -}} + {{ $git_path = replaceRE . $git_path_replace_to $file_path -}} + {{ end -}} + {{ $git_repo_path := path.Join $git_subdir $file_path -}} + + {{ $repo := (dict "repo_branch" $git_branch + "repo_path" $git_repo_path + "repo" ($.Param "repo") + "context" .) -}} +{{ with $.Param "repo.type" -}} + {{ partial ( printf "repo-links-%s.html" . ) $repo -}} +{{ end -}} {{ with .CurrentSection.AlternativeOutputFormats.Get "print" -}} {{ T "print_entire_section" }} {{ end }} diff --git a/layouts/partials/repo-links-github.html b/layouts/partials/repo-links-github.html new file mode 100644 index 000000000..5f05f9ddd --- /dev/null +++ b/layouts/partials/repo-links-github.html @@ -0,0 +1,20 @@ +{{/* cSpell:ignore querify subdir */ -}} +{{/* Class names ending with `--KIND` are deprecated in favor of `__KIND`, but we're keeping them for a few releases after 0.9.0 */ -}} + +{{ $viewURL := path.Join .repo.url "/tree" .repo_branch .repo_path -}} +{{ $editURL := path.Join .repo.url "/edit" .repo_branch .repo_path -}} +{{ $issuesQS := printf "title=%s" (safeURL $.context.Title) -}} +{{ $issuesURL := path.Join .repo.url "/issues/new" -}} +{{ $issuesURL = printf "%s?%s" $issuesURL $issuesQS -}} +{{ $newPageStub := resources.Get "stubs/new-page-template.md" -}} +{{ $newPageQS := querify "value" $newPageStub.Content "filename" "change-me.md" | safeURL -}} +{{ $newPageURL := path.Join .repo.url "/new" .repo_branch (path.Dir .repo_path) -}} +{{ $newPageURL = printf "%s?%s" $newPageURL $newPageQS -}} + {{ T "post_view_this" }} + {{ T "post_edit_this" }} + {{ T "post_create_child_page" }} + {{ T "post_create_issue" }} +{{ with .repo.project_url -}} + {{ $project_issueURL := printf "%s/issues/new" . -}} + {{ T "post_create_project_issue" }} +{{ end -}} diff --git a/userguide/hugo.yaml b/userguide/hugo.yaml index 92e5ab9dd..5698425e6 100644 --- a/userguide/hugo.yaml +++ b/userguide/hugo.yaml @@ -54,9 +54,13 @@ params: archived_version: false version: 0.10.0 url_latest_version: https://example.com - github_repo: https://github.com/google/docsy - github_project_repo: https://github.com/google/docsy - github_subdir: userguide + + repo: + type: github + url: https://github.com/google/docsy + subdir: userguide + project_url: https://github.com/google/docsy + time_format_blog: Monday, January 02, 2006 time_format_default: January 2, 2006 rss_sections: [blog] # TODO: drop since this is the default From ba136081c7ec6075b6ab016ab6a225dc7f55f4e3 Mon Sep 17 00:00:00 2001 From: smainz Date: Fri, 10 May 2024 17:16:19 +0200 Subject: [PATCH 4/8] Switch to 'repo.url' for last commit link and deprecate 'github_url' --- layouts/partials/page-meta-lastmod.html | 16 +++++++++++++++- 1 file changed, 15 insertions(+), 1 deletion(-) diff --git a/layouts/partials/page-meta-lastmod.html b/layouts/partials/page-meta-lastmod.html index c14ebfca5..a78c97e10 100644 --- a/layouts/partials/page-meta-lastmod.html +++ b/layouts/partials/page-meta-lastmod.html @@ -1,4 +1,5 @@ -{{ if and .GitInfo .Site.Params.github_repo -}} +{{ if and .GitInfo .Site.Params.github_repo -}} +{{ warnf "Warning: use of `github_repo` is deprecated, use `repo.url` instead " -}}
{{ T "post_last_mod" }} {{ .Lastmod.Format .Site.Params.time_format_default -}} {{ with .GitInfo }}: {{/* Trim WS */ -}} @@ -8,3 +9,16 @@ {{- end }}
{{ end -}} + +{{/* Looks like all repo types have the same frmat for the commit link */}} +{{ if and .GitInfo .Site.Params.repo.type -}} +
+ {{ T "post_last_mod" }} {{ .Lastmod.Format .Site.Params.time_format_default -}} + {{ with .GitInfo }}: {{/* Trim WS */ -}} + + {{- .Subject }} ({{ .AbbreviatedHash }}) {{- /* Trim WS */ -}} + + {{- end }} +
+{{ end -}} + From 36b367d5c6b8d08b7152cca0f5630f9207127fbe Mon Sep 17 00:00:00 2001 From: smainz Date: Wed, 24 Apr 2024 15:47:22 +0200 Subject: [PATCH 5/8] Add gitea repo links --- layouts/partials/repo-links-gitea.html | 20 ++++++++++++++++++++ 1 file changed, 20 insertions(+) create mode 100644 layouts/partials/repo-links-gitea.html diff --git a/layouts/partials/repo-links-gitea.html b/layouts/partials/repo-links-gitea.html new file mode 100644 index 000000000..1beaa665d --- /dev/null +++ b/layouts/partials/repo-links-gitea.html @@ -0,0 +1,20 @@ +{{/* cSpell:ignore querify subdir */ -}} +{{/* Class names ending with `--KIND` are deprecated in favor of `__KIND`, but we're keeping them for a few releases after 0.9.0 */ -}} + +{{ $viewURL := path.Join .repo.url "/src/branch/" .repo_branch .repo_path -}} +{{ $editURL := path.Join .repo.url "_edit/" .repo_branch .repo_path -}} +{{ $issuesQS := printf "title=%s" (safeURL $.context.Title )}} +{{ $issuesURL := path.Join .repo.url "/issues/new" -}} +{{ $issuesURL = printf "%s?%s" $issuesURL $issuesQS -}} +{{ $newPageStub := resources.Get "stubs/new-page-template.md" -}} +{{ $newPageQS := querify "value" $newPageStub.Content "filename" "change-me.md" | safeURL -}} +{{ $newPageURL := path.Join .repo.url "/_new/" .repo_branch (path.Dir .repo_path) -}} +{{ $newPageURL = printf "%s?%s" $newPageURL $newPageQS -}} + {{ T "post_view_this" }} + {{ T "post_edit_this" }} + {{ T "post_create_child_page" }} + {{ T "post_create_issue" }} +{{ with .repo.project_url -}} + {{ $project_issueURL := printf "%s/issues/new" . -}} + {{ T "post_create_project_issue" }} +{{ end -}} From f94496821965361ab107705e399ce37265aa9d8b Mon Sep 17 00:00:00 2001 From: smainz Date: Wed, 24 Apr 2024 17:00:36 +0200 Subject: [PATCH 6/8] Add azure repo links Taken from https://github.com/google/docsy/pull/1310 --- layouts/partials/repo-links-azure.html | 12 ++++++++++++ 1 file changed, 12 insertions(+) create mode 100644 layouts/partials/repo-links-azure.html diff --git a/layouts/partials/repo-links-azure.html b/layouts/partials/repo-links-azure.html new file mode 100644 index 000000000..6c4c318ae --- /dev/null +++ b/layouts/partials/repo-links-azure.html @@ -0,0 +1,12 @@ +{{ $baseUrl := replaceRE "/_git/.+$" "" .repo.url }} +{{ $viewURL := printf "%s?path=%s&version=GB%s&_a=contents" .repo.url .repo_path .repo_branch -}} +{{ $issuesURL := printf "%s/_workitems/create/Bug?[title]=%s" $baseUrl (safeURL $.context.Title ) -}} +{{ if .repo.azure.issue_area -}} + {{ $issuesURL = printf "%s/_workitems/create/Bug?[title]=%s&[Area Path]=%s" $baseUrl (safeURL $.context.Title) (safeURL .repo.azure.issue_area) -}} +{{ end -}} + {{ T "post_view_this" }} + {{ T "post_create_issue" }} +{{ with .repo.project_url -}} + {{ $project_issueURL := printf "%s/_workitems/create/Bug" (replaceRE "/_git.+$" "" .) -}} + {{ T "post_create_project_issue" }} +{{ end -}} From b3145f06c8761fb831cfd67e7f780f9b03a6c395 Mon Sep 17 00:00:00 2001 From: smainz Date: Mon, 13 May 2024 21:04:18 +0200 Subject: [PATCH 7/8] Add gitlab support Derived from github and changed issueUrl schema as in #1000 --- layouts/partials/repo-links-gitlab.html | 20 ++++++++++++++++++++ 1 file changed, 20 insertions(+) create mode 100644 layouts/partials/repo-links-gitlab.html diff --git a/layouts/partials/repo-links-gitlab.html b/layouts/partials/repo-links-gitlab.html new file mode 100644 index 000000000..12bc04ef2 --- /dev/null +++ b/layouts/partials/repo-links-gitlab.html @@ -0,0 +1,20 @@ +{{/* cSpell:ignore querify subdir */ -}} +{{/* Class names ending with `--KIND` are deprecated in favor of `__KIND`, but we're keeping them for a few releases after 0.9.0 */ -}} + +{{ $viewURL := path.Join .repo.url "/tree" .repo_branch .repo_path -}} +{{ $editURL := path.Join .repo.url "/edit" .repo_branch .repo_path -}} +{{ $issuesQS := printf "issue[title]=%s" (safeURL $.context.Title) -}} +{{ $issuesURL := path.Join .repo.url "/issues/new" -}} +{{ $issuesURL = printf "%s?%" $issuesURL $issuesQS -}} +{{ $newPageStub := resources.Get "stubs/new-page-template.md" -}} +{{ $newPageQS := querify "value" $newPageStub.Content "filename" "change-me.md" | safeURL -}} +{{ $newPageURL := path.Join .repo.url "/new" .repo_branch (path.Dir .repo_path) -}} +{{ $newPageURL = printf "%s?%s" $newPageURL $newPageQS -}} + {{ T "post_view_this" }} + {{ T "post_edit_this" }} + {{ T "post_create_child_page" }} + {{ T "post_create_issue" }} +{{ with .repo.project_url -}} + {{ $project_issueURL := printf "%s/issues/new" . -}} + {{ T "post_create_project_issue" }} +{{ end -}} From 53ce269b13c783d1e663c64c3da126e352662fa4 Mon Sep 17 00:00:00 2001 From: smainz Date: Fri, 10 May 2024 17:46:12 +0200 Subject: [PATCH 8/8] Update user guide --- .../docs/adding-content/repository-links.md | 260 +++++++++++++++++- 1 file changed, 257 insertions(+), 3 deletions(-) diff --git a/userguide/content/en/docs/adding-content/repository-links.md b/userguide/content/en/docs/adding-content/repository-links.md index 237d38b87..8b5398d91 100644 --- a/userguide/content/en/docs/adding-content/repository-links.md +++ b/userguide/content/en/docs/adding-content/repository-links.md @@ -15,11 +15,265 @@ The Docsy [docs and blog layouts](/docs/adding-content/content/#adding-docs-and- This page shows you how to configure these links. -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/). +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/). ## Link configuration -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. +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. + +{{< tabpane >}} +{{< tab header="Configuration file:" disabled=true />}} +{{< tab header="hugo.toml" lang="toml" >}} +[params.repo] + type = "github" + url = "https://github.com/google/docsy" + subdir = "userguide" + branch = "release" + project_url = "https://github.com/google/docsy" +{{< /tab >}} +{{< tab header="hugo.yaml" lang="yaml" >}} +params: + repo: + type: github + url: https://github.com/google/docsy + subdir: "userguide" + branch: "release" + project_url: "https://github.com/google/docsy" +{{< /tab >}} +{{< tab header="hugo.json" lang="json" >}} +{ + "params": { + "repo": { + "type": "github", + "url": "https://github.com/google/docsy", + "subdir": "userguide", + "branch"= "release", + "project_url" = "https://github.com/google/docsy" + } + } +} +{{< /tab >}} +{{< /tabpane >}} + +### `repo.type` + +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`. + +Other repo types: + +* [Forgejo](https://forgejo.org) is a fork of gitea and uses the same link schema as gitea, so you can use `type: gitea`. +* To use a **custom repository type** + * define `type: custom` in your configuration and + * place a custom template in your project at `layouts/partials/repo-links-custom.html` which will be used to render the links. + Instead of `custom` you can use any type, you like. + +### `repo.url` + +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. + +### `repo.subdir` (optional) + +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. + +### `repo.branch` (optional) + +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*. + +### `repo.project_url` (optional) + +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. + +It is assumed that the `project_url` points to the same type of git repository as your documentation site. + +### `path_base_for_subdir` (optional) + +Suppose that the source files for all of the pages under `content/some-section` +come from another repo, such as a [git submodule][]. Add settings like these to +the **section's index page** so that the repository links for all pages in that +section refer to the originating repo: + +{{< tabpane >}} +{{< tab header="Front matter:" disabled=true />}} +{{< tab header="toml" lang="toml" >}} ++++ +title = "Some super section" +[cascade.repo] +type = "github" +url = "https://github.com/some-username/another-repo/" +subdir = "docs" +path_base_for_subdir = "content/some-section" +… ++++ +{{< /tab >}} +{{< tab header="yaml" lang="yaml" >}} +--- +title: Some super section +cascade: + repo: + type: github + url: https://github.com/some-username/another-repo/ + subdir: docs + path_base_for_subdir: content/some-section +… +--- +{{< /tab >}} +{{< tab header="json" lang="json" >}} +{ + "title": "Some super section", + "cascade": { + repo: { + "type": "github", + "url": "https://github.com/some-username/another-repo/", + "subdir": "docs", + "path_base_for_subdir": "content/some-section" + } + } +} +{{< /tab >}} +{{< /tabpane >}} + +As an example, consider a page at the path +`content/some-section/subpath/some-page.md` with `branch` globally set to +`main`. The index page settings above will generate the following edit link for +`some-page.md`: + +```nocode +https://github.com/some-username/another-repo/edit/main/docs/subpath/some-page.md +``` + +To make it clear, without the settings in the sections index page, the edit link would be: + +```nocode +https://github.com/google/docsy/edit/main/userguide/content/some-section/subpath/some-page.md +``` + +If you only have a single page originating from another repo, then omit the +`cascade` key and write, at the top-level, the same settings as illustrated +above. + +If you'd like users to create project issues in the originating project repo as well, +then also set `project_url`, something like this: + +{{< tabpane >}} +{{< tab header="Front matter:" disabled=true />}} +{{< tab header="toml" lang="toml" >}} ++++ +… +[cascade.repo] +url = "https://github.com/some-username/another-repo/" +project_url = "https://github.com/some-username/another-repo/" +… ++++ +{{< /tab >}} +{{< tab header="yaml" lang="yaml" >}} +--- +… +cascade: + repo: + url: &repo https://github.com/some-username/another-repo/ + project_url: *repo +… +--- +{{< /tab >}} +{{< tab header="json" lang="json" >}} +{ + … + "cascade": { + "repo": { + "url": "https://github.com/some-username/another-repo/", + "project_url": "https://github.com/some-username/another-repo/" + } + } + … +} +{{< /tab >}} +{{< /tabpane >}} + +{{% alert title="Tip" %}} +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). +{{% /alert %}} + +The `path_base_for_subdir` setting is a regular expression, so you can +use it even if you have a site with [multiple languages][] for example: + +{{< tabpane >}} +{{< tab header="Front matter:" disabled=true />}} +{{< tab header="toml" lang="toml" >}} ++++ +… +path_base_for_subdir = "content/\w+/some-section" +… ++++ +{{< /tab >}} +{{< tab header="yaml" lang="yaml" >}} +--- +… +path_base_for_subdir: content/\w+/some-section +… +--- +{{< /tab >}} +{{< tab header="json" lang="json" >}} +{ +… + "path_base_for_subdir": "content/\w+/some-section" +… +} +{{< /tab >}} +{{< /tabpane >}} + +In situations where a page originates from a file under a different name, you +can specify `from` and `to` path-rename settings. Here's an example where an +index file is named `README.md` in the originating repo: + +{{< tabpane >}} +{{< tab header="Front matter:" disabled=true />}} +{{< tab header="toml" lang="toml" >}} ++++ +… +[repo] +url = "https://github.com/some-username/another-repo/" +subdir = "docs" + + [repo.path_base_for_github_subdir] + from = "content/some-section/(.*?)/_index.md" + to = "$1/README.md" +… ++++ +{{< /tab >}} +{{< tab header="yaml" lang="yaml" >}} +--- +… +repo: + url: https://github.com/some-username/another-repo/ + subdir: docs + path_base_for_github_subdir: + from: content/some-section/(.*?)/_index.md + to: $1/README.md +… +--- +{{< /tab >}} +{{< tab header="json" lang="json" >}} +{ + … + "repo": {} + "url": "https://github.com/some-username/another-repo/", + "subdir": "docs", + "path_base_for_subdir": { + "from": "content/some-section/(.*?)/_index.md", + "to": "$1/README.md" + } + }, + … +} +{{< /tab >}} +{{< /tabpane >}} +## GitHub configuration (deprecated) + +{{% alert title="Deprecation note" color="warning" %}} + These setting are deprecated. Use the params described in [Link Configuration][] instead. + + [Link Configuration]: #link-configuration +{{% /alert %}} ### `github_repo` @@ -361,7 +615,7 @@ Class names using the `--KIND` suffix were deprecated as of [v0.9.0]. To have page-source metadata displayed at the bottom of documentation pages and blog posts, set the `GitInfo` configuration parameter to `true`, and ensure that -`params.github_repo` is defined. +`params.repo.url` is defined. A last-modified page note looks something like this: