From bf7147db5a89147ffdbe5e716013235df99fe45b Mon Sep 17 00:00:00 2001 From: Erwin Bovendeur Date: Wed, 2 Nov 2022 10:14:27 +0100 Subject: [PATCH 1/4] Support for Azure Repositories --- layouts/partials/page-meta-lastmod.html | 9 +++- layouts/partials/page-meta-links-azure.html | 38 ++++++++++++++ layouts/partials/page-meta-links-github.html | 44 ++++++++++++++++ layouts/partials/page-meta-links.html | 54 +++----------------- 4 files changed, 95 insertions(+), 50 deletions(-) create mode 100644 layouts/partials/page-meta-links-azure.html create mode 100644 layouts/partials/page-meta-links-github.html diff --git a/layouts/partials/page-meta-lastmod.html b/layouts/partials/page-meta-lastmod.html index c14ebfca5..9ff8d60a2 100644 --- a/layouts/partials/page-meta-lastmod.html +++ b/layouts/partials/page-meta-lastmod.html @@ -1,8 +1,13 @@ -{{ if and .GitInfo .Site.Params.github_repo -}} +{{ $repo := .Site.Params.github_repo }} +{{ if .Site.Params.azure_repo -}} + {{ $repo = .Site.Params.azure_repo }} +{{ end -}} + +{{ if and (.GitInfo) (or (.Site.Params.github_repo) (.Site.Params.azure_repo)) -}}
{{ T "post_last_mod" }} {{ .Lastmod.Format .Site.Params.time_format_default -}} {{ with .GitInfo }}: {{/* Trim WS */ -}} - + {{- .Subject }} ({{ .AbbreviatedHash }}) {{- /* Trim WS */ -}} {{- end }} diff --git a/layouts/partials/page-meta-links-azure.html b/layouts/partials/page-meta-links-azure.html new file mode 100644 index 000000000..1d852c7a1 --- /dev/null +++ b/layouts/partials/page-meta-links-azure.html @@ -0,0 +1,38 @@ +{{ $path := strings.TrimPrefix (add hugo.WorkingDir "/") $.File.Filename -}} +{{ $pathFormatted := replace .File.Path "\\" "/" -}} +{{ $az_repo := ($.Param "azure_repo") -}} +{{ $az_subdir := ($.Param "azure_subdir") -}} +{{ $az_project_repo := ($.Param "azure_project_repo") -}} +{{ $az_branch := (default "main" ($.Param "azure_branch")) -}} +{{ $az_issue_area := ($.Param "azure_issue_area") -}} + +{{ if $az_repo -}} + {{/* Adjust $path based on path_base_for_azure_subdir */ -}} + {{ $azs_base := $.Param "path_base_for_azure_subdir" -}} + {{ $azs_rename := "" -}} + {{ if reflect.IsMap $azs_base -}} + {{ $azs_rename = $azs_base.to -}} + {{ $azs_base = $azs_base.from -}} + {{ end -}} + {{ with $azs_base -}} + {{ $path = replaceRE . $azs_rename $az_repo_path -}} + {{ end -}} + + {{ $az_repo_path := printf "%s/%s/%s" $az_branch $az_subdir $path -}} + {{ $az_repo_path = replaceRE "//+" "/" $az_repo_path -}} + + {{ $baseUrl := replaceRE "/_git/.+$" "" $az_repo }} + {{ $viewURL := printf "%s?path=%s&_a=contents" $az_repo $az_repo_path -}} + {{ $issuesURL := printf "%s/_workitems/create/Bug?[title]=%s" $baseUrl (safeURL $.Title ) -}} + {{ if $az_issue_area -}} + {{ $issuesURL = printf "%s/_workitems/create/Bug?[title]=%s&[Area Path]=%s" $baseUrl (safeURL $.Title) (safeURL $az_issue_area) -}} + {{ end -}} + + {{ T "post_view_this" }} + {{ T "post_create_issue" }} + {{ with $az_project_repo -}} + {{ $project_issueURL := printf "%s/_workitems/create/Bug" (replaceRE "/_git.+$" "" .) -}} + {{ T "post_create_project_issue" }} + {{ end -}} + +{{ end -}} diff --git a/layouts/partials/page-meta-links-github.html b/layouts/partials/page-meta-links-github.html new file mode 100644 index 000000000..8e2c652ad --- /dev/null +++ b/layouts/partials/page-meta-links-github.html @@ -0,0 +1,44 @@ +{{/* 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 (add hugo.WorkingDir "/") $.File.Filename -}} +{{ $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 -}} diff --git a/layouts/partials/page-meta-links.html b/layouts/partials/page-meta-links.html index bda98e0a5..11287e639 100644 --- a/layouts/partials/page-meta-links.html +++ b/layouts/partials/page-meta-links.html @@ -1,52 +1,10 @@ -{{/* 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 */ -}} - -{{ if .File -}} -{{ $path := strings.TrimPrefix (add hugo.WorkingDir "/") $.File.Filename -}} -{{ $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 .File }}
-{{ 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 -}} + {{ partial "page-meta-links-azure.html" . }} + {{ partial "page-meta-links-github.html" . }} - {{ $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 -}} -{{ with .CurrentSection.AlternativeOutputFormats.Get "print" -}} - {{ T "print_entire_section" }} -{{ end }} + {{ with .CurrentSection.AlternativeOutputFormats.Get "print" -}} + {{ T "print_entire_section" }} + {{ end }}
{{ end -}} From 5d44cea7245f1bd8b845f9130be1f0c334d96304 Mon Sep 17 00:00:00 2001 From: Erwin Bovendeur Date: Fri, 6 Jan 2023 13:20:47 +0100 Subject: [PATCH 2/4] Updated documentation for Azure Devops repositories --- .../docs/adding-content/repository-links.md | 75 +++++++++++++++++-- 1 file changed, 68 insertions(+), 7 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..58f9c1139 100644 --- a/userguide/content/en/docs/adding-content/repository-links.md +++ b/userguide/content/en/docs/adding-content/repository-links.md @@ -15,13 +15,15 @@ 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 and Azure Devops 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/). ## 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. -### `github_repo` +### Github + +#### `github_repo` 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. @@ -44,7 +46,7 @@ params: {{< /tab >}} {{< /tabpane >}} -### `github_subdir` (optional) +#### `github_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. @@ -67,7 +69,7 @@ params: {{< /tab >}} {{< /tabpane >}} -### `github_project_repo` (optional) +#### `github_project_repo` (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. @@ -90,7 +92,7 @@ params: {{< /tab >}} {{< /tabpane >}} -### `github_branch` (optional) +#### `github_branch` (optional) Specify a value here if you have would like to reference a different branch for the other github settings like **Edit this page** or **Create project issue**. @@ -113,7 +115,7 @@ params: {{< /tab >}} {{< /tabpane >}} -### `path_base_for_github_subdir` (optional) +#### `path_base_for_github_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 @@ -285,7 +287,7 @@ path_base_for_github_subdir: {{< /tab >}} {{< /tabpane >}} -### `github_url` (optional) +#### `github_url` (optional) {{% alert title="Deprecation note" color="warning" %}} This setting is deprecated. Use [path_base_for_github_subdir][] instead. @@ -324,6 +326,65 @@ This can be useful if you have page source files in multiple Git repositories, or require a non-GitHub URL. Pages using this value have **Edit this page** links only. +### Azure Devops + +#### `azure_repo` + +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. + +{{< tabpane persistLang=false >}} +{{< tab header="Configuration file:" disabled=true />}} +{{< tab header="config.toml" lang="toml" >}} +azure_repo = "https://dev.azure.com/google/docsy/_git/docsy" +{{< /tab >}} +{{< tab header="config.yaml" lang="yaml" >}} +azure_repo: 'https://dev.azure.com/google/docsy/_git/docsy' +{{< /tab >}} +{{< tab header="config.json" lang="json" >}} +{ + "azure_repo": "https://dev.azure.com/google/docsy/_git/docsy" +} +{{< /tab >}} +{{< /tabpane >}} + +#### `azure_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. + +{{< tabpane persistLang=false >}} +{{< tab header="Configuration file:" disabled=true />}} +{{< tab header="config.toml" lang="toml" >}} +azure_subdir = "userguide" +{{< /tab >}} +{{< tab header="config.yaml" lang="yaml" >}} +azure_subdir: 'userguide' +{{< /tab >}} +{{< tab header="config.json" lang="json" >}} +{ + "azure_subdir": "userguide" +} +{{< /tab >}} +{{< /tabpane >}} + +#### `azure_project_repo` (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. + +{{< tabpane persistLang=false >}} +{{< tab header="Configuration file:" disabled=true />}} +{{< tab header="config.toml" lang="toml" >}} +azure_project_repo = "https://dev.azure.com/google/docsy/_git/docsy" +{{< /tab >}} +{{< tab header="config.yaml" lang="yaml" >}} +azure_project_repo: 'https://dev.azure.com/google/docsy/_git/docsy' +{{< /tab >}} +{{< tab header="config.json" lang="json" >}} +{ + "azure_project_repo": "https://dev.azure.com/google/docsy/_git/docsy" +} +{{< /tab >}} +{{< /tabpane >}} + ### Disabling links You can use CSS to selectively hide links. For example, add the following to From 7fc21f7a58382720a481fc61121a518ee0d2f8dc Mon Sep 17 00:00:00 2001 From: Erwin Bovendeur Date: Tue, 19 Mar 2024 11:32:42 +0100 Subject: [PATCH 3/4] Fix paths on Windows systems (replace \\ with /) --- layouts/partials/page-meta-links-azure.html | 9 ++++----- layouts/partials/page-meta-links-github.html | 2 +- 2 files changed, 5 insertions(+), 6 deletions(-) diff --git a/layouts/partials/page-meta-links-azure.html b/layouts/partials/page-meta-links-azure.html index 1d852c7a1..445d6a5bb 100644 --- a/layouts/partials/page-meta-links-azure.html +++ b/layouts/partials/page-meta-links-azure.html @@ -1,5 +1,4 @@ -{{ $path := strings.TrimPrefix (add hugo.WorkingDir "/") $.File.Filename -}} -{{ $pathFormatted := replace .File.Path "\\" "/" -}} +{{ $path := strings.TrimPrefix (add (replace hugo.WorkingDir "\\" "/") "/") (replace $.File.Filename "\\" "/") -}} {{ $az_repo := ($.Param "azure_repo") -}} {{ $az_subdir := ($.Param "azure_subdir") -}} {{ $az_project_repo := ($.Param "azure_project_repo") -}} @@ -15,14 +14,14 @@ {{ $azs_base = $azs_base.from -}} {{ end -}} {{ with $azs_base -}} - {{ $path = replaceRE . $azs_rename $az_repo_path -}} + {{ $path = replaceRE . $azs_rename $path -}} {{ end -}} - {{ $az_repo_path := printf "%s/%s/%s" $az_branch $az_subdir $path -}} + {{ $az_repo_path := printf "%s/%s" $az_subdir $path -}} {{ $az_repo_path = replaceRE "//+" "/" $az_repo_path -}} {{ $baseUrl := replaceRE "/_git/.+$" "" $az_repo }} - {{ $viewURL := printf "%s?path=%s&_a=contents" $az_repo $az_repo_path -}} + {{ $viewURL := printf "%s?path=%s&version=GB%s&_a=contents" $az_repo $az_repo_path $az_branch -}} {{ $issuesURL := printf "%s/_workitems/create/Bug?[title]=%s" $baseUrl (safeURL $.Title ) -}} {{ if $az_issue_area -}} {{ $issuesURL = printf "%s/_workitems/create/Bug?[title]=%s&[Area Path]=%s" $baseUrl (safeURL $.Title) (safeURL $az_issue_area) -}} diff --git a/layouts/partials/page-meta-links-github.html b/layouts/partials/page-meta-links-github.html index 8e2c652ad..b55cd1fa4 100644 --- a/layouts/partials/page-meta-links-github.html +++ b/layouts/partials/page-meta-links-github.html @@ -1,7 +1,7 @@ {{/* 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 (add hugo.WorkingDir "/") $.File.Filename -}} +{{ $path := strings.TrimPrefix (add (replace hugo.WorkingDir "\\" "/") "/") (replace $.File.Filename "\\" "/") -}} {{ $gh_repo := $.Param "github_repo" -}} {{ $gh_url := $.Param "github_url" -}} {{ $gh_subdir := $.Param "github_subdir" | default "" -}} From 599ab6c517a0762563b51e988f4b2dad6137ef77 Mon Sep 17 00:00:00 2001 From: Erwin Bovendeur Date: Tue, 19 Mar 2024 11:42:50 +0100 Subject: [PATCH 4/4] Added (fake) azure repo links for demo purposes --- userguide/hugo.yaml | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/userguide/hugo.yaml b/userguide/hugo.yaml index fd0039c1d..a75741ffc 100644 --- a/userguide/hugo.yaml +++ b/userguide/hugo.yaml @@ -59,6 +59,13 @@ params: github_repo: https://github.com/google/docsy github_project_repo: https://github.com/google/docsy github_subdir: userguide + + # Added azure links for demo purposes + azure_repo: https://dev.azure.com/google/docsy/_git/docsy + azure_project_repo: https://dev.azure.com/google/docsy/_git/docsy + azure_subdir: userguide + azure_issue_area: Docsy\Issues + time_format_blog: Monday, January 02, 2006 time_format_default: January 2, 2006 rss_sections: [blog] # TODO: drop since this is the default