Skip to content

Commit

Permalink
feat: support gitlab page meta links
Browse files Browse the repository at this point in the history
  • Loading branch information
@valdisrigdon
valdisrigdon committed May 13, 2022
1 parent 060d0ed commit 8bb68b4
Show file tree
Hide file tree
Showing 2 changed files with 160 additions and 36 deletions.
75 changes: 47 additions & 28 deletions layouts/partials/page-meta-links.html
View file
Original file line number Diff line number Diff line change
@@ -1,47 +1,66 @@
{{ if .File }}
{{ $pathFormatted := replace .File.Path "\\" "/" -}}
{{ $gh_repo := ($.Param "github_repo") -}}
{{ $gh_url := ($.Param "github_url") -}}
{{ $gh_subdir := ($.Param "github_subdir") -}}
{{ $gh_project_repo := ($.Param "github_project_repo") -}}
{{ $gh_branch := (default "main" ($.Param "github_branch")) -}}
{{ $github_url := "" -}}
{{ $git_repo_type := "" -}}
{{ $git_repo := "" -}}
{{ $git_subdir := "" -}}
{{ $git_project_repo := "" -}}
{{ $git_branch := "" -}}
{{ $git_base := "" -}}
{{ $issuesURL := "" -}}
{{ if $.Param "github_repo" -}}
{{ $git_repo_type = "github" -}}
{{ $github_url = ($.Param "github_url") -}}
{{ $git_repo = ($.Param "github_repo") -}}
{{ $git_subdir = ($.Param "github_subdir") -}}
{{ $git_project_repo = ($.Param "github_project_repo") -}}
{{ $git_branch = (default "main" ($.Param "github_branch")) -}}
{{ $git_base = $.Param "path_base_for_github_subdir" -}}
{{ $issuesURL = printf "%s/issues/new?title=%s" $git_repo (safeURL $.Title ) -}}
{{ else if $.Param "gitlab_repo" -}}
{{ $git_repo_type = "gitlab" -}}
{{ $git_repo = ($.Param "gitlab_repo") -}}
{{ $git_subdir = ($.Param "gitlab_subdir") -}}
{{ $git_project_repo = ($.Param "gitlab_project_repo") -}}
{{ $git_branch = (default "main" ($.Param "gitlab_branch")) -}}
{{ $git_base = $.Param "path_base_for_gitlab_subdir" -}}
{{ $issuesURL = printf "%s/issues/new?issue[title]=%s" $git_repo (safeURL $.Title ) -}}
{{ end }}
<div class="td-page-meta ml-2 pb-1 pt-2 mb-0">
{{ if $gh_url -}}
{{ if $github_url -}}
{{ warnf "Warning: use of `github_url` is deprecated. For details see https://www.docsy.dev/docs/adding-content/repository-links/#github_url-optional" -}}
<a href="{{ $gh_url }}" target="_blank"><i class="fa fa-edit fa-fw"></i> {{ T "post_edit_this" }}</a>
{{ else if $gh_repo -}}
{{ $gh_repo_path := printf "%s/content/%s" $gh_branch $pathFormatted -}}
{{ if and ($gh_subdir) (.Site.Language.Lang) -}}
{{ $gh_repo_path = printf "%s/%s/content/%s/%s" $gh_branch $gh_subdir ($.Site.Language.Lang) $pathFormatted -}}
<a href="{{ $github_url }}" target="_blank"><i class="fa fa-edit fa-fw"></i> {{ T "post_edit_this" }}</a>
{{ else if ne $git_repo_type "" -}}
{{ $git_repo_path := printf "%s/content/%s" $git_branch $pathFormatted -}}
{{ if and ($git_subdir) (.Site.Language.Lang) -}}
{{ $git_repo_path = printf "%s/%s/content/%s/%s" $git_branch $git_subdir ($.Site.Language.Lang) $pathFormatted -}}
{{ else if .Site.Language.Lang -}}
{{ $gh_repo_path = printf "%s/content/%s/%s" $gh_branch ($.Site.Language.Lang) $pathFormatted -}}
{{ else if $gh_subdir -}}
{{ $gh_repo_path = printf "%s/%s/content/%s" $gh_branch $gh_subdir $pathFormatted -}}
{{ $git_repo_path = printf "%s/content/%s/%s" $git_branch ($.Site.Language.Lang) $pathFormatted -}}
{{ else if $git_subdir -}}
{{ $git_repo_path = printf "%s/%s/content/%s" $git_branch $git_subdir $pathFormatted -}}
{{ end -}}

{{/* Adjust $gh_repo_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 -}}
{{/* Adjust $git_repo_path based on path_base_for_git(hub|lab)_subdir */ -}}
{{ $git_rename := "" -}}
{{ if reflect.IsMap $git_base -}}
{{ $git_rename = $git_base.to -}}
{{ $git_base = $git_base.from -}}
{{ end -}}
{{ with $ghs_base -}}
{{ $gh_repo_path = replaceRE . $ghs_rename $gh_repo_path -}}
{{ with $git_base -}}
{{ $git_repo_path = replaceRE . $git_rename $git_repo_path -}}
{{ end -}}

{{ $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 ) -}}
{{ $viewURL := printf "%s/tree/%s" $git_repo $git_repo_path -}}
{{ $editURL := printf "%s/edit/%s" $git_repo $git_repo_path -}}
{{ $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 $gh_repo_path $newPageQS -}}
{{ $newPageURL := printf "%s/new/%s?%s" $git_repo $git_repo_path $newPageQS -}}

<a href="{{ $viewURL }}" class="td-page-meta--view" target="_blank" rel="noopener"><i class="fa fa-file-alt fa-fw"></i> {{ T "post_view_this" }}</a>
<a href="{{ $editURL }}" class="td-page-meta--edit" target="_blank" rel="noopener"><i class="fa fa-edit fa-fw"></i> {{ T "post_edit_this" }}</a>
<a href="{{ $newPageURL }}" class="td-page-meta--child" target="_blank" rel="noopener"><i class="fa fa-edit fa-fw"></i> {{ T "post_create_child_page" }}</a>
<a href="{{ $issuesURL }}" class="td-page-meta--issue" target="_blank" rel="noopener"><i class="fab fa-github fa-fw"></i> {{ T "post_create_issue" }}</a>
{{ with $gh_project_repo -}}
<a href="{{ $issuesURL }}" class="td-page-meta--issue" target="_blank" rel="noopener"><i class="fab fa-{{ $git_repo_type }} fa-fw"></i> {{ T "post_create_issue" }}</a>
{{ with $git_project_repo -}}
{{ $project_issueURL := printf "%s/issues/new" . -}}
<a href="{{ $project_issueURL }}" class="td-page-meta--project-issue" target="_blank" rel="noopener"><i class="fas fa-tasks fa-fw"></i> {{ T "post_create_project_issue" }}</a>
{{ end -}}
Expand Down
121 changes: 113 additions & 8 deletions userguide/content/en/docs/Adding content/repository-links.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -6,53 +6,55 @@ description: Help your users interact with your source repository.

The Docsy [docs and blog layouts](/docs/adding-content/content/#adding-docs-and-blog-posts) include links for readers to edit the page or create issues for your docs or project via your site's source repository. The current generated links for each docs or blog page are:

* **View page source**: Brings the user to the page source in your docs repo.
* **View page source**: Brings the user to the page source in your docs repo.
* **Edit this page**: Brings the user to an editable version of the page content in their fork (if available) of your docs repo. If the user doesn't have a current fork of your docs repo, they are invited to create one before making their edit. The user can then create a pull request for your docs.
* **Create child page**: Brings the user to a create new file form in their fork of your docs repo. The new file will be located as a child of the page they clicked the link on. The form will be pre-populated with a template the user can edit to create their page. You can change this by adding `assets/stubs/new-page-template.md` to your own project.
* **Create documentation issue**: Brings the user to a new issue form in your docs repo with the name of the current page as the issue's title.
* **Create project issue** (optional): Brings the user to a new issue form in your project repo. This can be useful if you have separate project and docs repos and your users want to file issues against the project feature being discussed rather than your docs.

This page shows you how to configure these links.

Currently, Docsy supports only GitHub repository links "out of the box". 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 only GitHub and GitLab repository links "out of the box". 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 variables you can configure in `config.toml` 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.

```toml
github_repo = "https://github.com/google/docsy"
```

### `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.

```toml
github_subdir = "userguide"
```

### `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.

```toml
github_project_repo = "https://github.com/google/docsy"
```

### `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**.

```toml
github_branch = "release"
```

### `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
Expand Down Expand Up @@ -121,7 +123,7 @@ path_base_for_github_subdir:
---
```

### `github_url` (optional)
#### `github_url` (optional)

{{% alert title="Deprecation note" color="warning" %}}
This setting is deprecated. Use [path_base_for_github_subdir][] instead.
Expand All @@ -143,6 +145,109 @@ 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.

### GitLab

#### `gitlab_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.

```toml
gitlab_repo = "https://gitlab.com/google/docsy"
```

#### `gitlab_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.

```toml
gitlab_subdir = "userguide"
```

#### `gitlab_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.

```toml
gitlab_project_repo = "https://gitlab.com/google/docsy"
```

#### `gitlab_branch` (optional)

Specify a value here if you have would like to reference a different branch for the other GitLab settings like **Edit this page** or **Create project issue**.

```toml
gitlab_branch = "release"
```

#### `path_base_for_gitlab_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:

```yaml
---
title: Some super section
cascade:
gitlab_repo: https://gitlab.com/some-username/another-repo/
gitlab_subdir: docs
path_base_for_gitlab_subdir: content/some-section
...
---
```

As an example, consider a page at the path
`content/some-section/subpath/some-page.md` with `gitlab_branch` globally set to
`main`. The index page settings above will generate the following edit link for
`some-page.md`:

```nocode
https://gitlab.com/some-username/another-repo/edit/main/docs/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 repo as well,
then also set `gitlab_project_repo`, something like this:

```yaml
---
...
cascade:
gitlab_repo: &repo https://gitlab.com/some-username/another-repo/
gitlab_project_repo: *repo
...
---
```

Using a [Yaml anchor][] is optional, but it helps keep the settings [DRY][].

The `path_base_for_gitlab_subdir` setting is a regular expression, so you can
use it even if you have a site with [multiple languages][] for example:

```yaml
path_base_for_gitlab_subdir: content/\w+/some-section
```

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:

```yaml
---
...
gitlab_repo: https://gitlab.com/some-username/another-repo/
githlab_subdir: docs
path_base_for_gitlab_subdir:
from: content/some-section/(.*?)/_index.md
to: $1/README.md
...
---
```

## Disabling links

You can use CSS to selectively disable (hide) links. For example, add the
Expand Down

0 comments on commit 8bb68b4

Please sign in to comment.