Asciidoctorj extension to deal with the path to the source directory
URLs
-
Project home (this page)
Do you want to improve this page? Please edit it on GitHub. |
Description
INFO: with version 2.1.0
of the Asciidoctor Gradle Plugin, this plugin is no longer necessary:
The variable gradle-relative-srcdir
provided by the plugin contains the same value.
In complex asciidoctorj setup (using maven or gradle), it might be usefull to know the relative path to the source directory.
The "sourcedir" extension is a preprocessor that provides this value as new attribute: sourcedir
.
In order for the extension to work, you need to provide the configured value sourceDir
as sourcedir-definition
attribute.
When processing following directory, if the source directory is docs/
:
docs
├── page1.adoc
└── other
└── page2.adoc
Then the sourcedir
value will be:
-
empty string for
page1
-
../
forpage2
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:sourcedir
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>
<groupId>fr.jmini.asciidoctorj</groupId>
<artifactId>sourcedir</artifactId>
<version>1.1.0</version>
</dependency>
<!-- ... (other dependencies) -->
</dependencies>
<configuration>
<!-- ... (other configuration) -->
<attributes>
<sourcedir-definition>${project.basedir}/docs</sourcedir-definition>
<!-- ... (other attributes) -->
</attributes>
</configuration>
<!-- ... (other blocks like executions) -->
</plugin>
<!-- ... (other plugins) -->
</plugins>
</build>
For a complete example, see: pom.xml
Integration in a gradle build
The fr.jmini.asciidoctorj:sourcedir
jar can be declared as dependency of the asciidoctor
task:
asciidoctor {
sourceDir = file('docs') (3)
outputDir = file('build/generated-docs')
attributes = ['sourcedir-definition' : file('docs'), (2)
'project-version' : "$version",
'toc' : 'left',
'icons' : 'font',
'sectanchors' : 'true',
'idprefix' : '',
'idseparator' : '-']
repositories {
mavenCentral()
}
dependencies {
asciidoctor 'fr.jmini.asciidoctorj:sourcedir:1.1.0' (1)
}
}
1 | Dependency declaration |
2 | Addition of the sourcedir-definition , must be the same value as "3" |
3 | Source directory definition for the gradle plugin |
For a complete example, see: build.gradle
Source Code
As for any grade plugin, the source code of the plugin is available in the src/ folder.
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 in a distant maven repository:
./gradlew publish
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 sourcedir issue tracker on GitHub.
You can also contact me on Twitter: @j2r2b