DOC-250: local check links extension (#425)

# Description of change https://hazelcast.atlassian.net/browse/DOC-250 --------- Co-authored-by: Jack Green <[email protected]>
hazelcast · Nov 29, 2024 · 273db7b · 273db7b
1 parent e43999f
commit 273db7b
Show file tree

Hide file tree

Showing 4 changed files with 30 additions and 10 deletions.
diff --git a/.github/actions/validate/action.yml b/.github/actions/validate/action.yml
@@ -16,6 +16,7 @@ runs:
         sparse-checkout: |
           antora-playbook.yml
           lib/load-check-links-playbook.js
+          lib/antora-link-checker-extension.js
         sparse-checkout-cone-mode: false
         path: hazelcast-docs
         ref: main
@@ -25,6 +26,6 @@ runs:
       run: |
         cp "./hazelcast-docs/lib/load-check-links-playbook.js" "./load-check-links-playbook.js"
         npm i
-        npm i -D [email protected] @jcahills/[email protected] [email protected]
+        npm i -D [email protected] [email protected]
         node load-check-links-playbook.js $GITHUB_REPOSITORY $GITHUB_BASE_REF
-        ./node_modules/.bin/antora --fetch --to-dir test --log-level=error --log-failure-level=error --extension=@jcahills/antora-link-checker check-links-playbook.yml
+        ./node_modules/.bin/antora --fetch --to-dir test --log-level=error --log-failure-level=error --extension=hazelcast-docs/lib/antora-link-checker-extension.js check-links-playbook.yml
diff --git a/lib/antora-link-checker-extension.js b/lib/antora-link-checker-extension.js
@@ -0,0 +1,8 @@
+// This extension stops the Antora site generator from building the site after checking internal links (xrefs).
+// As a result, the output is a list of broken links rather than a documentation site.
+
+module.exports.register = (context) => {
+	context.on('documentsConverted', () => {
+		context.stop()
+	})
+}
diff --git a/lib/load-check-links-playbook.js b/lib/load-check-links-playbook.js
@@ -87,19 +87,31 @@ function rewriteCurrentVersion() {
 	}
 }
 
-function excludeBaseBranch(sources, repoName, branchName) {
-	const matchedRepos = sources.filter(source => source.url.endsWith(repoName));
-	if (matchedRepos.length === 0) {
-		throw new Error(`There is no repository ${repoName} among the playbook sources!`);
-	}
-	let currentSource = matchedRepos.find(source => isMatch(branchName, source.branches));
+function getCurrentSource(matchedRepos, branchName) {
+	let currentSource = matchedRepos.find(source => {
+		if (Array.isArray(source.branches)) {
+			return source.branches.find(branch => isMatch(branchName, branch));
+		} else {
+			return isMatch(branchName, source.branches);
+		}
+	});
 	if (!currentSource) {
 		console.debug(`No matching base branch found. Rewriting version to omit version collision!`);
 		rewriteCurrentVersion();
 		currentSource = matchedRepos[0];
 	}
+
+	return currentSource;
+}
+
+function excludeBaseBranch(sources, repoName, branchName) {
 	const excludedBranch = `!${branchName}`;
+	const matchedRepos = sources.filter(source => source.url.endsWith(repoName));
+	if (matchedRepos.length === 0) {
+		throw new Error(`There is no repository ${repoName} among the playbook sources!`);
+	}
 
+	const currentSource = getCurrentSource(matchedRepos, branchName);
 	if (Array.isArray(currentSource.branches)) {
 		currentSource.branches.push(excludedBranch);
 	} else {

diff --git a/package.json b/package.json
@@ -7,7 +7,7 @@
   "scripts": {
     "build": "antora --to-dir docs --fetch antora-playbook.yml && cp _redirects docs",
     "build-local": "antora --to-dir docs --fetch antora-playbook-local.yml",
-    "check-links-local": "antora --fetch --to-dir test --log-level=error --log-failure-level=error --extension=@jcahills/antora-link-checker antora-playbook-local.yml",
+    "check-links-local": "antora --fetch --to-dir test --log-level=error --log-failure-level=error --extension=./lib/antora-link-checker-extension.js antora-playbook-local.yml",
     "generate-pdfs-platform-5-5": "antora assembler-playbook-platform-5-5.yml",
     "generate-pdfs-platform-5-4": "antora assembler-playbook-platform-5-4.yml",
     "generate-pdfs-platform-5-3": "antora assembler-playbook-platform-5-3.yml",
@@ -26,7 +26,6 @@
   "devDependencies": {
     "@antora/cli": "^3.1.1",
     "@antora/site-generator": "^3.1.1",
-    "@jcahills/antora-link-checker": "^1.0.1",
     "@djencks/antora-aggregate-collector": "^0.1.0-beta.1",
     "asciidoctor-kroki": "^0.15.0",
     "ngrok": "^4.2.2",