Extend edit URL pattern
The edit_url
in the playbook allows to configure a pattern (as introduced in issue #292 (closed)) for a specific git host, therefore is provides the following variables (source Antora Docs) :
-
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). -
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.
This may be sufficient for covering different hosting providers, given the standard set of directories provided in the repository itself.
If the content inside the repository differs and documents are copied to Antora's directory structure in the CI/CD pipeline, there is no way to fix the edit URL and point to the actual file.
One solution could be, to provide additional placeholders in the pattern, to subdivide path
variabel and allow for a custom file path creation.
Given the example value of the path
variable form Example 5, we have learn/docs/modules/ROOT/pages/index.adoc
which itself is composed out of the following parts:
-
learn/docs/
: is given by thestart_path
-
modules/
: is a fixed directory required by antora -
ROOT/
: is the module name, which can be chosen freely. In this case, it is the root module. -
pages/
: is the family name, which currently can beattachments
,examples
,images
,pages
, orpartials
. -
index.adoc
: is the actual file name or file path, if subdirectories are used inside the family directory, e.g., as supported by Pages Directory and Files.
To be more flexible in the creation of the edit path, these parts could be provided as additional placeholders in the edit URL pattern, e.g., such that
content:
sources:
- url: https://app.company.com/the-group/zap.git
branches: v1.2.5, next
edit_url: '{web_url}/blob/{refname}/{start_path}/modules/{module}/{family}/{file_path}'
would be a valid expression in addition to edit_url: '{web_url}/blob/{refname}/{path}'
.
That could be good solution, if complete directory structures are created or altered in the CI/CD process.
An alternative solution with an even higher flexibility, would be to allow to overwrite the edit_url
inside an asciidoc file itself. That would be a good solution, if single files are moved to an existing document structure inside the CI/CD process.