From 0c11ae5c1812ab70818ff43601b641866a26d168 Mon Sep 17 00:00:00 2001 From: smainz Date: Tue, 14 May 2024 11:44:48 +0200 Subject: [PATCH] Update documentation --- .../docs/adding-content/repository-links.md | 28 ++++++++++--------- 1 file changed, 15 insertions(+), 13 deletions(-) diff --git a/userguide/content/en/docs/adding-content/repository-links.md b/userguide/content/en/docs/adding-content/repository-links.md index 3a1385606..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,11 @@ 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 GitHub, Azure DevOps 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/). +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 a few 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 />}} @@ -29,7 +29,7 @@ There are a few site variables you can configure in `hugo.toml`/`hugo.yaml`/`hug url = "https://github.com/google/docsy" subdir = "userguide" branch = "release" - project_url = "https://github.com/google/docsy + project_url = "https://github.com/google/docsy" {{< /tab >}} {{< tab header="hugo.yaml" lang="yaml" >}} params: @@ -38,7 +38,7 @@ params: url: https://github.com/google/docsy subdir: "userguide" branch: "release" - project_url: "https://github.com/google/docsy + project_url: "https://github.com/google/docsy" {{< /tab >}} {{< tab header="hugo.json" lang="json" >}} { @@ -48,7 +48,7 @@ params: "url": "https://github.com/google/docsy", "subdir": "userguide", "branch"= "release", - "project_url" = "https://github.com/google/docsy + "project_url" = "https://github.com/google/docsy" } } } @@ -57,12 +57,11 @@ params: ### `repo.type` -Repo Links are created differently for different git repositories. Currently Docsy supports [GitHub](https://www.github.com), [Azure DevOps](https://azure.microsoft.com/products/devops) and [Gitea](https://about.gitea.com). Specify the type of repository you are using. Supported values are `github`, `azure`, `gitea`. +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: -* [GitLab](https://about.gitlab.com) can handle the same link scheme as GitHub, so you can use `type: gitlab`. -* [Forgejo](https://forgejo.org) is a fork of gitea and uses the same link schem as gitea, so you can use `type: gitea`. +* [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. @@ -70,7 +69,7 @@ Other repo types: ### `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. +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) @@ -78,15 +77,15 @@ Specify a value here if your content directory is not in your repo's root direct ### `repo.branch` (optional) -Specify a value here if you have would like to reference a different branch in the links to your repository like Edit this page or Create project issue. +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. +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. -### Working with git submodules: `path_base_for_subdir` (optional) +### `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 @@ -99,6 +98,7 @@ section refer to the originating repo: +++ 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" @@ -110,6 +110,7 @@ path_base_for_subdir = "content/some-section" 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 @@ -121,6 +122,7 @@ cascade: "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" @@ -139,7 +141,7 @@ As an example, consider a page at the path 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: +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