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.

Description

If you want to use the extension in your code, just write git-link:<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-git-link\src\docs\asciidoc\index.adoc

The derived path for the link would be

src/docs/asciidoc/index.adoc

An other possibility is:

~/git/asciidoctorj-git-link_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-git-link\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.

Link text

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-git-link.

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-git-link
: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-git-link]!
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-git-link", link-text="edit this page"] on GitHub.
Example 4. Output (example with repository and link text)

Please edit this page on GitHub.

Usage

The extension is published on maven central and can be directly consumed from maven or gradle.

Integration in a maven build

You need to declare fr.jmini.asciidoctorj:git-link as a dependency for the org.asciidoctor:asciidoctor-maven-plugin plugin. Your <build> section could looks like this:

<build>
  <plugins>
    <plugin>
      <groupId>org.asciidoctor</groupId>
      <artifactId>asciidoctor-maven-plugin</artifactId>
      <version>${asciidoctor.maven.plugin.version}</version>
      <dependencies>
        <dependency> (1)
          <groupId>fr.jmini.asciidoctorj</groupId>
          <artifactId>git-link</artifactId>
          <version>3.2.1</version>
        </dependency>
        <!-- ... (other dependencies) -->
      </dependencies>
      <!-- ... (configuration and executions sections) -->
    </plugin>
    <!-- ... (other plugins) -->
  </plugins>
</build>
1 Dependency declaration

For a complete example, see: pom.xml

Integration in a gradle build

The fr.jmini.asciidoctorj:git-link jar can be declared as dependency of the asciidoctor task:

asciidoctor {
    configurations 'asciidoctorExtensions'

    sourceDir = file('docs')
    baseDirFollowsSourceFile()
    outputDir = file('build/generated-docs')
    attributes = ['project-version'   : "$version",
                  'source-highlighter': 'coderay',
                  'imagesdir'         : '',
                  'toc'               : 'left',
                  'icons'             : 'font',
                  'sectanchors'       : 'true',
                  'idprefix'          : '',
                  'idseparator'       : '-',
                  'docinfo1'          : 'true']
    repositories {
        mavenCentral()
    }
    dependencies {
        asciidoctorExtensions 'fr.jmini.asciidoctorj:git-link:3.2.1' (1)
    }
}
1 Dependency declaration

For a complete example, see: build.gradle

AsciidoctorJ version

This extension is compatible with org.asciidoctor:asciidoctorj in range [2.0.0, 3.0.0[.

The continuous integration server runs the test suite with different AsciidoctorJ versions within this range.

Which version should I use?

Older version of this extension are compatible with older version of Asciidoctorj:

Asciidoctorj version

git-link:[] version

1.5.x

3.0.0

1.6.x

3.1.0

2.x.x

3.2.0

Download

The library is hosted on maven central.

Listing 5. Maven coordinates of the library
<dependency>
  <groupId>fr.jmini.asciidoctorj</groupId>
  <artifactId>git-link</artifactId>
  <version>3.2.2</version>
</dependency>

Source Code

As for any java project, the source code of the plugin is available in the src/ folder.

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

Build

This project is using gradle.

Command to build the sources locally:

./gradlew build

Command to deploy to your local maven repository:

./gradlew publishToMavenLocal

Command to build the documentation page:

./gradlew asciidoctor

The output of this command is an HTML page located at <git repo root>/build/docs/html5/index.html.

For project maintainers

signing.gnupg.keyName and signing.gnupg.passphrase are expected to be set in your local gradle.properties file to be able to sign. sonatypeUser and sonatypePassword are expected to be set in order to be able to publish to a distant repository.

Command to build and publish the result to maven central:

./gradlew publishToSonatype

Command to upload the documentation page on GitHub pages:

./gradlew gitPublishPush

Command to perform a release:

./gradlew release -Prelease.useAutomaticVersion=true

Using ssh-agent

Some tasks requires to push into the distant git repository (release task or updating the gh-pages branch). If they are failing with errors like this:

org.eclipse.jgit.api.errors.TransportException: ... Permission denied (publickey).

Then ssh-agent can be used.

eval `ssh-agent -s`
ssh-add ~/.ssh/id_rsa

(source for this approach)

Get in touch

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

You can also contact me on Twitter: @j2r2b

License

Eclipse Public License - v 1.0