Add support for baseURL for relative URLs

Fixes #40
Add a new attribute :apidocs_baseuri:
If set, it'll be used to prefix any relative URLs matched in apidocs.properties

README.md

@@ -172,3 +172,54 @@ is processed as:
 ```adoc
 link:https://docs.oracle.com/javase/8/docs/api/java/util/logging/package-summary.html[`java.util.logging`]
 ```
+
+### Relative URLs
+
+It can be convenient to use relative URLs when referencing some Javadoc from the project itself, 
+when it is hosted at the same place as the userguide.
+
+For instance:
+
+```
+https://my.company.com/docs/v1.0.0/userguide.html
+https://my.company.com/docs/v1.0.0/apidocs/index.html
+```
+
+```properties
+com.company.my=apidocs/
+```
+
+But when using other Asciidoctor backends like pdf, those relative links will be broken.
+
+To solve this, the attribute `apidocs_baseurl` configures the base URL to use for relative Javadoc URLs:
+
+```xml
+<plugin>
+  <groupId>org.asciidoctor</groupId>
+  <artifactId>asciidoctor-maven-plugin</artifactId>
+  <configuration>
+    <attributes>
+      <apidocs_config>apidoc.properties</apidocs_config>
+    </attributes>
+  </configuration>
+  <executions>
+     <execution>
+        <id>backend-html</id>
+        <configuration>
+            <backend>html5</backend>
+            <!-- Keep relative links, as HTML userguide will be hosted alongside the Javadoc -->
+        </configuration>
+     </execution>
+     <execution>
+        <id>backend-pdf</id>
+        <configuration>
+            <backend>pdf</backend>
+            <attributes>
+              <!-- Transform relative links into absolute URLs -->
+              <apidocs_baseurl>https://my.company.com/</apidocs_baseurl>
+            </attributes>        
+        </configuration>
+     </execution>
+  </executions>
+</plugin>
+```

pom.xml

@@ -188,6 +188,9 @@
       <plugin>
         <artifactId>maven-javadoc-plugin</artifactId>
         <version>3.2.0</version>
+        <configuration>
+          <source>8</source>
+        </configuration>
         <executions>
           <execution>
             <id>attach-javadocs</id>

src/main/java/com/amadeus/asciidoc/apidoc/ImplicitApidocMacro.java

@@ -34,6 +34,8 @@ public class ImplicitApidocMacro extends InlineMacroProcessor {
 
   static final String ATTRIBUTE_APIDOCS_CONFIG = "apidocs_config";
 
+  static final String ATTRIBUTE_APIDOCS_BASE_URL = "apidocs_baseurl";
+
   /**
    * Packages are only lowercase. Assume there is at least 1 sub-package.
    */
@@ -60,15 +62,20 @@ public class ImplicitApidocMacro extends InlineMacroProcessor {
   @Override
   public Object process(ContentNode parent, String target, Map<String, Object> attributes) {
     LOG.log(Level.FINE, "Processing {0}", target);
+    Map<String, Object> documentAttributes = parent.getDocument().getAttributes();
 
     if (registry == null) {
-      String path = (String)parent.getDocument().getAttributes().get(ATTRIBUTE_APIDOCS_CONFIG);
+      String path = (String)documentAttributes.get(ATTRIBUTE_APIDOCS_CONFIG);
       registry = new ApidocRegistry(path);
     }
 
-    String baseUrl = registry.findBestMatch(target.replaceFirst("@", ""));
-    if (baseUrl != null) {
-      Link link = buildLink(baseUrl, target);
+    String url = registry.findBestMatch(target.replaceFirst("@", ""));
+    if (url != null) {
+      // Prefix relative URLs
+      if(!url.startsWith("http") && documentAttributes.get(ATTRIBUTE_APIDOCS_BASE_URL) != null){
+        url = documentAttributes.get(ATTRIBUTE_APIDOCS_BASE_URL) + url;
+      }
+      Link link = buildLink(url, target);
       return renderLink(parent, link, attributes);
     } else {
       // If single sub-package, assume it may be "filename.extension" and don't report a warning.

src/test/java/com/amadeus/asciidoc/apidoc/ApidocExtensionTest.java

@@ -29,21 +29,21 @@ public class ApidocExtensionTest {
 
   private static Asciidoctor asciidoctor;
 
-  private static Map<String, Object> options = new HashMap<>();
+  private Map<String, Object> options = new HashMap<>();
 
-  private static Attributes attributes = new Attributes();
+  private Attributes attributes = new Attributes();
 
   private StubLogHandler logHandler = new StubLogHandler();
 
   @BeforeAll
   public static void setUpOnce() {
     asciidoctor = Asciidoctor.Factory.create(); // Slow, do it only once.
-    attributes.setAttribute(ImplicitApidocMacro.ATTRIBUTE_APIDOCS_CONFIG, "src/test/resources/apidoc.properties");
-    options = OptionsBuilder.options().attributes(attributes).asMap();
   }
 
   @BeforeEach
   public void setUp() {
+    attributes.setAttribute(ImplicitApidocMacro.ATTRIBUTE_APIDOCS_CONFIG, "src/test/resources/apidoc.properties");
+    options = OptionsBuilder.options().attributes(attributes).asMap();
     asciidoctor.registerLogHandler(logHandler);
   }
 
@@ -113,6 +113,16 @@ public void relativeLinks() {
     assertEquals(block("<a href=\"apidocs/com/company/my/Class.html\">Class</a>"), output);
   }
 
+  @Test
+  public void relativeLinksWithBaseUrl() {
+    attributes.setAttribute(ImplicitApidocMacro.ATTRIBUTE_APIDOCS_BASE_URL, "https://my.company.com/");
+    Map<String, Object> options = OptionsBuilder.options().attributes(attributes).asMap();
+
+    String output = asciidoctor.convert("com.company.my.Class", options);
+
+    assertEquals(block("<a href=\"https://my.company.com/apidocs/com/company/my/Class.html\">Class</a>"), output);
+  }
+
   @Test
   public void passthroughShouldSkipMacro() {
     String output = asciidoctor.convert("pass:[com.company.my.Class]", options);
@@ -173,7 +183,7 @@ public void blockListingTitleShouldNotTriggerWarning() {
   }
 
   @Test
-  public void unkownPackageBaseApidocShouldSkipAndWarn() {
+  public void unknownPackageBaseApidocShouldSkipAndWarn() {
     String output = asciidoctor.convert("com.unknown.Class", options);
 
     assertEquals(block("com.unknown.Class"), output);