Edit URL

On this page, you’ll learn:

How Antora builds the edit URL for each page.
How to customize the edit URL.
How to disable the edit URL.

Antora’s default edit URL assignment

Antora automatically derives an edit URL for all files sourced from the hosted GitLab (gitlab.com), GitHub (github.com), Bitbucket (bitbucket.org), and Pagure (pagure.io) services (SAAS). It does so by first converting the content source URL to a web URL, then using the reference and path information of the current file to construct a URL to the edit mode of that file in the hosted repository.

In the default UI, Antora uses this value (if set) to create an Edit this Page link in the upper right corner of each page. That link directs the visitor to the edit interface of that file provided by the hosted git service. For example, if you click the Edit this Page link on this page, your browser will go to GitLab’s file editing interface (on gitlab.com) and load the AsciiDoc source that was used to create this page.

One exception is if the repository is private. In this case, the default UI does not show the Edit this Page link. However, you can force the default UI to show the link by setting the FORCE_SHOW_EDIT_PAGE_LINK environment variable (e.g., FORCE_SHOW_EDIT_PAGE_LINK=true) when building the site. Alternately, you can customize the UI template to change the logic.

Another exception is if the page originates from the local filesystem (i.e., a worktree). In this case, the default UI uses the local file:// URI for the Edit this Page link. You can force the default UI to always use the edit URL by setting the CI environment variable (e.g., CI=true) when building the site. (This environment variable is already set in most CI environments). The assumption is that if the CI environment variable is set, the site is being published to a remote server where a file:// URI would not be accessible. Rather than setting this environment variable, you can customize the UI template to change the logic.

That covers how the edit URL is used. Let’s now look at how you can customize the value.

Customize the edit URL

The edit_url key is useful when you’re using an unrecognized git solution, or you want Edit this Page to link to an alternate view, such as the raw or rendered display, of a page’s source file.

The edit_url key is set in the playbook and can be applied to all of the content sources or customized per individual source. The key accepts a URL pattern that contains the URL segments of the git solution or source file view plus several placeholder segments, {web_url}, {refname}, {reftype}, {refhash}, and {path}. Antora automatically fulfills these placeholders with the file’s origin information at processing time.

Example 1. edit_url key and value

edit_url: '{web_url}/blob/{refname}/{path}' (1)

1	Enclose the value of `edit_url` in single quotation marks (`'`) when it starts with a curly bracket (`{`).

Example 1 shows a hypothetical edit URL pattern containing several placeholders. The word blob is an example of a URL segment that isn’t represented by a placeholder. In the following section, we’ll explain the role of the these placeholders.

How does Antora assemble an edit URL for a page?

When edit_url is set, either by default or explicitly, Antora computes the value of the {web_url}, {refname}, {reftype}, {refhash}, and {path} placeholders for each page according to its content source and file origin information. Then, using the pattern assigned to the edit_url key, it assembles each page’s unique edit URL.

web_url: The {web_url} placeholder is the corresponding web URL for the content source repository that Antora automatically computes from its git URL. For example, https://gitlab.com/cave/sneaky.git is converted to https://gitlab.com/cave/sneaky. This placeholder can be omitted if you use a web URL that differs from the one Antora computes.
refname: The {refname} is the name of the git reference (e.g., v2.1.x, main, rawhide).
reftype: The {reftype} is the type of the git reference (i.e., tag or branch).
refhash: The {refhash} is the commit hash of the git reference (e.g., aab0e5684afe0d4e05955fbef72b6e5538bb1ec5).
path: The {path} is the path of the source file relative to the root of the repository. It includes the start_path if one is specified.

To see an example of the values Antora would compute for the placeholders, we’ll use the content source, branches, and edit URL pattern inputs shown in Example 2.

Example 2. edit_url placeholders

content:
  sources:
  - url: https://app.company.com/the-group/zap.git
    branches: v1.2.5, next
    edit_url: '{web_url}/_src/{refname}/u890/{path}'

Let’s determine what the edit URL would look like for the page generated from a file named index.adoc. This index.adoc file is stored in branch v1.2.5 of the zap repository in the pages directory of the ROOT module. Using the pattern assigned to edit_url in Example 2, Antora would compute the edit URL shown in Example 3 for index.adoc.

Example 3. Edit URL for index.adoc using the inputs from Example 2

https://app.company.com/the-group/zap/_src/v1.2.5/u890/modules/ROOT/pages/index.adoc

Antora replaces {web_url} with the content source’s web URL. In this case, the .git is dropped from the end of the value of url. {refname} is replaced with the v1.2.5 git branch reference. Finally, {path} is replaced by the path to the source file, relative to the root of the repository. Since this source doesn’t have a specified start path, the resulting path is modules/ROOT/pages/index.adoc.

When a content source has an assigned start_path, Antora prepends it to {path}.

Example 4. Content source with start_path and edit_url set

content:
  sources:
  - url: https://app.company.com/the-group/zap.git
    branches: v1.2.5, next
    start_path: learn/docs
    edit_url: '{web_url}/_src/{refname}/u890/{path}'

Using the inputs from Example 4, the edit URL for index.adoc would be:

Example 5. Edit URL for index.adoc using the inputs from Example 4

https://app.company.com/the-group/zap/_src/v1.2.5/u890/learn/docs/modules/ROOT/pages/index.adoc

Apply the same edit_url to multiple content sources

When all or most of your content sources use the same edit_url, you can set it directly on the content key.

Example 6. Set edit_url on the content key

content:
  edit_url: '{web_url}/_src/{refname}/u890/{path}' (1)
  sources:
  - url: https://app.company.com/the-group/zap.git
    branches: v1.2.5, next
  - url: https://app.company.com/city/team-l/zonk.git
    branches: v2.*

1	When `edit_url` is set directly on the `content` key, as it is here, its value is applied to all of the content sources unless the key is reset or disabled on an individual content source.

As seen in Example 7, the edit_url key can be set on an individual content source even when it’s set on the content key.

Example 7. Set edit_url on the content key and an individual source

content:
  edit_url: '{web_url}/_src/{refname}/u890/{path}' (1)
  sources:
  - url: https://app.company.com/the-group/zap.git (2)
    branches: v1.2.5, next
  - url: https://git.secretbase.org/ack/boom
    branches: dev
    edit_url: '{web_url}/{refname}/ping/0/{path}' (3)
  - url: https://app.company.com/city/team-l/zonk.git (4)
    branches: v2.*

1	This `edit_url` key is set directly on the `content` key. Its value is applied to all of the content sources unless the key is reset or disabled on an individual content source.
2	This content source will inherit the value of the `edit_url` key set directly on the `content` key.
3	When `edit_url` is set on an individual content source, that value will be used instead of the value assigned to the `edit_url` key set on the `content` key.
4	This content source will inherit the value of the `edit_url` key set directly on the `content` key.

Change the source file view linked to Edit this Page

By default, a page’s edit URL links to the file editing interface of the git service where the repository is hosted. This works as long as long as the content source is stored in one of the hosted git services that Antora recognizes, which includes GitLab (gitlab.com), GitHub (github.com), Bitbucket (bitbucket.org), and Pagure (pagure.io). If the repository is not stored in one of these hosted services (e.g., a self-hosted GitLab or Bitbucket instance), you can use the edit_url key to configure how this URL is constructed. For instance, in Example 8, each page’s computed edit URL will now be the URL for GitLab’s rendered file view of the corresponding source file.

Example 8. Route the edit URL to an alternate source file view

content:
  edit_url: '{web_url}/blob/{refname}/{path}' (1)
  sources:
  - url: https://gitlab.com/cave/sneaky.git
    branches: v2.0, v1.0

1	The `edit_url` key is assigned the URL pattern for GitLab’s rendered file view.

Using the inputs in Example 8, the Edit this Page link on each page sourced from the https://gitlab.com/cave/sneaky.git repository will link to the rendered view of the corresponding source file on GitLab.

To change the link text of Edit this Page or replace it with an image, you’ll need to update your UI.

Disable the edit URL

If the repository is private, the default UI will not show the Edit this Page link for the current page, even though the edit URL is defined. However, if the repository is public, and you want to disable the link, or nullify the edit URL for any other reason, you can do so using the playbook.

The edit_url key can turn off the edit URL feature on all of your content sources or per individual content source. To disable the edit URL, assign a tilde (~) or the word false to the edit_url key.

content:
  branches: v*
  edit_url: ~ (1)
  sources:
  - url: https://app.company.com/the-group/zap.git
  - url: https://gitlab.com/cave/sneaky.git

1 Disable the edit URL feature for all content sources by setting edit_url on the content key and assigning it a value of ~. The tilde (~) disables the edit URL feature. An edit URL won’t be produced for any of the pages sourced from the content sources unless edit_url is reset per individual content source.

The edit_url can also be disabled on an individual content source.

content:
  branches: v*
  sources:
  - url: https://app.company.com/the-group/zap.git
    edit_url: ~ (1)
  - url: https://gitlab.com/cave/sneaky.git (2)

1	The `edit_url` key is set on this individual content source and assigned a value of `~`.
2	Since `edit_url` isn’t explicitly set on the `content` key or on this content source, it will use the default edit URL behavior built into Antora.

Revert a content source to the default edit URL behavior

You can revert to the default edit URL behavior for an individual content source even when you’ve set or disabled the edit_url key at the content key level. On the source, set edit_url and assign it the value true.

Example 9. Reset edit_url to the default behavior

content:
  branches: v*
  edit_url: '{web_url}/_src/{refname}/u890/{path}' (1)
  sources:
  - url: https://app.company.com/the-group/zap.git
  - url: https://gitlab.com/cave/sneaky.git
    edit_url: true (2)
  - url: https://app.company.com/city/team-l/zonk.git

1	When `edit_url` is set directly on the `content` key, its value is applied to all of the content sources unless the key is reset or disabled on an individual content source.
2	Assign the value `true` to the `edit_url` key to revert a content source to the default edit URL behavior.

In Example 9, the zap and zonk content sources will use the edit_url set on the content key while the sneaky source will use the default edit URL behavior built into Antora.