Support anchor rewrites

Add support for anchor rewrites that can be used to change a previously
published anchor to and updated one.

Closes gh-29

Author: philwebb

README.adoc

@@ -441,6 +441,41 @@ For example, the following document will replace all package declarations with `
 
 
 
+=== Anchor Rewriting
+Anchor rewriting can be used if you need to evolve a document and change previously published anchor links.
+
+For example, say you publish a document with the following typo:
+
+[source,asciidoctor]
+----
+[[initializzzing]]
+== Initializing
+This is how to do it.
+----
+
+You then fix the typo and publish a new revision:
+
+[source,asciidoctor]
+----
+[[initializing]]
+== Initializing
+This is how to do it.
+----
+
+You can add a rewrite rule so that any links to `+++https://example.com/doc#initializzzing+++` will be automatically changed to `+++https://example.com/doc#initializing+++`.
+
+To define the rewrite rules, add a `anchor-rewrite.properties` file to your `base_dir` (usually the same directory as your `index.adoc` file).
+
+For example, the following file would be used in the example above:
+
+[source,properties]
+.anchor-rewrite.properties
+----
+initializzzing=initializing
+----
+
+
+
 == Contributing
 If you're looking to contribute to this project, or you're just trying to navigate the code please take a look at the link:CONTRIBUTING.adoc[CONTRIBUTING] file.
 

src/main/java/io/spring/asciidoctor/backend/SpringBackendsExtensionRegistry.java

@@ -16,6 +16,7 @@
 
 package io.spring.asciidoctor.backend;
 
+import io.spring.asciidoctor.backend.anchorrewrite.AnchorRewriteDocinfoProcessor;
 import org.asciidoctor.Asciidoctor;
 import org.asciidoctor.jruby.extension.spi.ExtensionRegistry;
 
@@ -29,6 +30,7 @@ public class SpringBackendsExtensionRegistry implements ExtensionRegistry {
 	@Override
 	public void register(Asciidoctor asciidoctor) {
 		asciidoctor.requireLibrary("spring-asciidoctor-backends");
+		asciidoctor.javaExtensionRegistry().docinfoProcessor(new AnchorRewriteDocinfoProcessor());
 	}
 
 }

src/main/java/io/spring/asciidoctor/backend/anchorrewrite/AnchorRewriteDocinfoProcessor.java

@@ -0,0 +1,51 @@
+/*
+ * Copyright 2021 the original author or authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package io.spring.asciidoctor.backend.anchorrewrite;
+
+import java.io.File;
+import java.io.IOException;
+
+import org.asciidoctor.ast.Document;
+import org.asciidoctor.extension.DocinfoProcessor;
+
+/**
+ * {@link DocinfoProcessor} to add an anchor-rewrite script.
+ *
+ * @author Phillip Webb
+ */
+public class AnchorRewriteDocinfoProcessor extends DocinfoProcessor {
+
+	@Override
+	public String process(Document document) {
+		try {
+			File directory = getDirectory(document);
+			File propertiesFile = new File(directory, "anchor-rewrite.properties");
+			return (propertiesFile.exists()) ? AnchorRewriteScriptTag.fromPropertiesFile(propertiesFile).getHtml() : "";
+		}
+		catch (IOException ex) {
+			throw new IllegalStateException(ex);
+		}
+	}
+
+	private File getDirectory(Document document) {
+		Object directory = document.getOptions().get("base_dir");
+		directory = (directory != null) ? directory : document.getOptions().get("docdir");
+		directory = (directory != null) ? directory : new File(".");
+		return (directory instanceof File) ? (File) directory : new File(directory.toString());
+	}
+
+}

src/main/java/io/spring/asciidoctor/backend/anchorrewrite/AnchorRewriteScriptTag.java

@@ -0,0 +1,86 @@
+/*
+ * Copyright 2021 the original author or authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package io.spring.asciidoctor.backend.anchorrewrite;
+
+import java.io.File;
+import java.io.FileInputStream;
+import java.io.IOException;
+import java.io.InputStream;
+import java.util.Collections;
+import java.util.Iterator;
+import java.util.LinkedHashMap;
+import java.util.Map;
+import java.util.Map.Entry;
+import java.util.Objects;
+import java.util.Properties;
+
+/**
+ * Generates the script tag for anchor rewrites.
+ *
+ * @author Phillip Webb
+ */
+class AnchorRewriteScriptTag {
+
+	private final Map<String, String> entries;
+
+	AnchorRewriteScriptTag(Map<?, ?> entries) {
+		this.entries = getValidEntries(entries);
+	}
+
+	private Map<String, String> getValidEntries(Map<?, ?> entries) {
+		Map<String, String> validEntries = new LinkedHashMap<>();
+		entries.forEach((key, value) -> {
+			if (!Objects.equals(key, value)) {
+				validEntries.put(String.valueOf(key), String.valueOf(value));
+			}
+		});
+		return Collections.unmodifiableMap(validEntries);
+	}
+
+	String getHtml() {
+		if (this.entries.isEmpty()) {
+			return "";
+		}
+		StringBuilder html = new StringBuilder();
+		html.append("<script type=\"application/json\" id=\"anchor-rewrite\">\n");
+		html.append("{\n");
+		Iterator<Entry<String, String>> iterator = this.entries.entrySet().iterator();
+		while (iterator.hasNext()) {
+			Entry<String, String> entry = iterator.next();
+			html.append(jsonQuote(entry.getKey()));
+			html.append(":");
+			html.append(jsonQuote(entry.getValue()));
+			html.append(iterator.hasNext() ? ",\n" : "\n");
+		}
+		html.append("}\n");
+		html.append("</script>");
+		return html.toString();
+	}
+
+	private String jsonQuote(String string) {
+		return "\"" + string.replace("\"", "\\\"") + "\"";
+	}
+
+	static AnchorRewriteScriptTag fromPropertiesFile(File propertiesFile) throws IOException {
+		Properties properties = new Properties();
+		try (InputStream inputStream = new FileInputStream(propertiesFile)) {
+			properties.load(inputStream);
+		}
+		return new AnchorRewriteScriptTag(properties);
+	}
+
+}

src/main/js/site/anchorrewrite.js

@@ -0,0 +1,45 @@
+/*
+ * Copyright 2021 the original author or authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the 'License');
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an 'AS IS' BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+(function () {
+  "use strict";
+
+  window.addEventListener("load", onChange);
+  window.addEventListener("hashchange", onChange);
+
+  function onChange() {
+    const element = document.getElementById("anchor-rewrite");
+    const anchor = window.location.hash.substr(1);
+    if (element && anchor) {
+      const rewites = JSON.parse(element.innerHTML);
+      updateAnchor(anchor, rewites);
+    }
+  }
+
+  function updateAnchor(anchor, rewrites) {
+    const seen = [anchor];
+    console.debug(anchor);
+    while (rewrites[anchor]) {
+      anchor = rewrites[anchor];
+      if (seen.includes(anchor)) {
+        console.error("Skipping circular anchor update");
+        return;
+      }
+      seen.push(anchor);
+    }
+    window.location.hash = anchor;
+  }
+})();

src/test/asciidoc/anchor-rewrite.properties

@@ -0,0 +1,2 @@
+old1=old2
+old2=copy-to-clipboard

src/test/asciidoc/spring.adoc

@@ -68,6 +68,7 @@ public void itAlsoLooksNice() {
 
 
 
+[[copy-to-clipboard]]
 == Copy to Clipboard
 Hover over any code block and a copy-to-clipboard button is available:
 

src/test/gradle/src/asciidoc/anchor-rewrite.properties

@@ -0,0 +1 @@
+old-anchor=new-anchor

src/test/java/io/spring/asciidoctor/backend/anchorrewrite/AnchorRewriteScriptTagTests.java

@@ -0,0 +1,80 @@
+/*
+ * Copyright 2021 the original author or authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package io.spring.asciidoctor.backend.anchorrewrite;
+
+import java.io.File;
+import java.net.URL;
+import java.util.LinkedHashMap;
+import java.util.Map;
+
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.Test;
+import org.junit.jupiter.api.TestInfo;
+
+import static org.assertj.core.api.Assertions.assertThat;
+import static org.assertj.core.api.Assertions.contentOf;
+
+/**
+ * Tests for {@link AnchorRewriteScriptTag}.
+ *
+ * @author Phillip Webb
+ */
+class AnchorRewriteScriptTagTests {
+
+	private URL expected;
+
+	@BeforeEach
+	void setup(TestInfo testInfo) {
+		String name = "AnchorRewriteScriptTagTests_" + testInfo.getTestMethod().get().getName() + ".html";
+		this.expected = getClass().getResource(name);
+	}
+
+	@Test
+	void getHtmlGeneratesScriptTag() {
+		Map<String, String> entries = new LinkedHashMap<>();
+		entries.put("foo", "bar");
+		entries.put("green", "blue");
+		AnchorRewriteScriptTag tag = new AnchorRewriteScriptTag(entries);
+		assertThat(tag.getHtml()).isEqualTo(contentOf(this.expected));
+	}
+
+	@Test
+	void getHtmlWhenHasEqualKeyValueEntryGeneratesFilteredHtml() {
+		Map<String, String> entries = new LinkedHashMap<>();
+		entries.put("foo", "foo");
+		entries.put("green", "blue");
+		AnchorRewriteScriptTag tag = new AnchorRewriteScriptTag(entries);
+		assertThat(tag.getHtml()).isEqualTo(contentOf(this.expected));
+	}
+
+	@Test
+	void getHtmlWhenEmptyGeneratesEmptyHtml() {
+		Map<String, String> entries = new LinkedHashMap<>();
+		AnchorRewriteScriptTag tag = new AnchorRewriteScriptTag(entries);
+		assertThat(tag.getHtml()).isEqualTo("");
+	}
+
+	@Test
+	void fromPropertiesFileLoadsFileContents() throws Exception {
+		File file = new File(
+				"src/test/java/" + getClass().getPackage().getName().replace(".", "/") + "/anchor-rewrite.properties");
+		AnchorRewriteScriptTag tag = AnchorRewriteScriptTag.fromPropertiesFile(file);
+		assertThat(tag.getHtml()).contains("foo");
+
+	}
+
+}

src/test/java/io/spring/asciidoctor/backend/anchorrewrite/anchor-rewrite.properties

@@ -0,0 +1 @@
+foo=bar