Asciidoctorj extension to create links to view or edit files on a git server (like github.com).

URLs

Do you want to improve this page? Please edit it on GitHub.

Usage

If you want to use the extension in your code, just write gh:<target>[<arguments>]. Listing 1 provides a complete example, that creates a link to edit a file on a GitHub repo:

Listing 1. Example using all possible arguments
See git-link:news/debuter-avec-asciidoctor.adoc[repository="asciidoctor/asciidoctor.org", branch="master", mode="view", link-text="this article in french", link-window="_blank", server="https://www.github.com/"] on GitHub.
Example 1. Output (example with all arguments)

See this article in french on GitHub.

Target argument

This mandatory parameter defines the path of the ressource (a file or a directory) inside the git repository.

One possible value is self. In that case the path will be computed using the file location of the document beeing processed (value taken from the asciidoctor docfile attribute). In order to work, the file needs to be on a specific location.

The first possibility is to have a document located in a folder containing the <repository-name> value in its name. For example, for a file in this repository, this would a valid path:

C:\git\asciidoctorj-gh-edit\src\docs\asciidoc\index.adoc

The derived path for the link would be

src/docs/asciidoc/index.adoc

An other possibility is:

~/git/asciidoctorj-gh-edit_repository/src/docs/asciidoc/index.adoc
This means that if you are using this plugin on a continous integration server like jenkins, you should have a workspace name (derived from the job name) matching the git repository name.

A second possibility is to use a location on a path containing the two folders target/checkout. In that case the checkout folder will be considered as the root of the repository. This is usefull when this plugin is used during a maven release process.

Example:

~/buildjob/target/checkout/src/docs/asciidoc/index.adoc

If multiple possible roots are detected, the latest win. Example:

C:\git\asciidoctorj-gh-edit\target\checkout\src\docs\asciidoc\index.adoc

In this last case the computed path is still:

src\docs\asciidoc\index.adoc

Additional arguments

The additional arguments are optional. You can use the named form (as in Listing 1) or use them in the correct order.

The link-text argument defines the text of the link. Default value is:

  • "edit on GitHub" in the edit mode

  • "view on GitHub" in the view and viewdir mode

Mode

The mode can be:

  • view: view a file (default used when the mode is undefined or unexpected).

  • viewdir: view a directory.

  • edit: edit a file.

When the target argument ends with a slash (/), the defined mode is ignored and viewdir is used.

The value can be defined as git-link-mode attribute in the document.

Branch

The branch argument corresponds to the git branch that should be used. If nothing is specified the default value master will be used.

The value can be defined as git-branch attribute in the document.

Repository

The repository agurment specifies the repository on GitHub (pattern: <owner>/<repository-name>). Depending on the case <owner> might be a GitHub user name or a GitHub organization name. For the repository of this project it would be jmini/asciidoctorj-gh-edit.

The value can be defined as git-repository attribute in the document.

The link-window argument defines where the the link will be openend. This is similar to the window attribute of the link macro.

The default value is empty (not set).

Server

The server argument is useful if you use your own Git Repository manager (the URL syntax needs to be compatible with GitHub. This is the case with GitLab). Possible values are:

The trailing slash is not mandatory.

The value can be defined as git-server attribute in the document.

If nothing is specified the default value https://github.com/ is used.

Additional examples

Listing 2 demonstrates how you can use the macro without any arguments. Please notice that in this case the argument repository (and optionally branch and server) should be defined at document level.

Listing 2. Simple usage (no arguments)
:git-repository: jmini/asciidoctorj-gh-edit
:git-branch: patch-1

Click on the git-link:self[] link.
Example 2. Output (simple usage)

Click on the view on GitHub link.

As with any Asciidoctor Macro you can used position attribute instead of named attribute. Listing 3 provides an example with two arguments.

Listing 3. Example with repository and branch as arguments (position attribute)
Click on the git-link:self[link, view, patch-1, jmini/asciidoctorj-gh-edit]!
Example 3. Output (example with repository and branch)

Click on the link!

Listing 4 provides an example where the repository and the link text are specified as named attribute You can also change the link text:

Listing 4. Example with repository and link text as arguments (named attribute)
Please git-link:self[mode="edit", repository="jmini/asciidoctorj-gh-edit", link-text="edit this page"] on GitHub.
Example 4. Output (example with repository and link text)

Please edit this page on GitHub.

Add the extension to your pom.xml file

The extension is the published on maven central. You need to add an additional repository to your pom:

Unresolved directive in index.adoc - include::{rootdir}pom.xml[tags=mvn-repo]

Then you need to declare com.bsiag.asciidoctorj:gh-edit as a dependency for the org.asciidoctor:asciidoctor-maven-plugin plugin. Your <build> section could looks like this:

Unresolved directive in index.adoc - include::{rootdir}pom.xml[tags=mvn-plugin]

Asciidoctorj version

This extension is build and tested with this version of asciidoctorj:

Unresolved directive in index.adoc - include::{rootdir}pom.xml[tags=mvn-adocj]

Source Code

As for any maven plugin, the source code of the plugin is available in the gh:viewdir[path='src', link-text='src'] folder.

If you are using the Eclipse Installer (Oomph) you can use the AsciidoctorjGhEdit.setup File (url) to setup your IDE properly.

Build

Run maven install on the root pom file:

mvn install

Get in touch

Use the git-link:[] issue tracker on GitHub.

You can also contact me on Twitter: @j2r2b

License