Features

Author: Gianluca Beil

internal/documentation/jsdoc-to-markdown.js

@@ -76,7 +76,16 @@ async function htmlToMarkdown(options = {}) {
 const excludedFiles = {"index.html": "", "global.html": "", "custom.css": ""};
 const inputDirectory = path.join("dist", "api");
 const outputDirectory = path.join("docs", "api");
+let packageTagName = "https://github.com/UI5/cli/blob/main/packages/";
 
+// 1. Find tag name
+if (process.argv[2] == "gh-pages") {
+    // Read package.json of packages/builder
+    const builderJson = JSON.parse(fs.readFileSync("tmp/packages/@ui5/builder/package.json"));
+    packageTagName = `https://github.com/UI5/cli/blob/cli-v${builderJson["version"]}/packages/`;
+}
+
+// 2. Check and create api directory, also remove all existing files if it exists
 if (!fs.existsSync(outputDirectory)) {
     fs.mkdirSync(outputDirectory);
 } else {
@@ -85,19 +94,37 @@ if (!fs.existsSync(outputDirectory)) {
 	}
 }
 
+// 3. Iterate through every .html generated by jsdoc
 for (const file of fs.readdirSync(path.join("dist", "api"))) {
+    // Skip js files
 	if (excludedFiles[file] !== undefined) continue;
+
     const filePath = path.join(inputDirectory, file);
+    // Skip directories
 	if (fs.statSync(filePath).isDirectory()) continue;
+
+    // Read the html file
 	const htmlString = fs.readFileSync(filePath);
+
+    // Convert html to markdown
 	let markdown = await htmlToMarkdown({
 		html: htmlString
 	});
+
+    // Escape characters in markdown
     markdown = escapeMarkdown(markdown);
+
+    // Fix some markdown syntax e.g. <optional> -> Optional
     markdown = fixMarkdown(markdown);
-    if (file.endsWith(".js.html")) {
-        markdown = markdown.replace("```", "```javascript");
+
+    // Point all js links to GitHub
+    const linkMatches = markdown.matchAll(/\((.*?)\.js.html\)/g);
+    for (const linkMatch of linkMatches) {
+        const githubUrl = packageTagName + linkMatch[1].replace(".js.html", "").replaceAll("_", "/").replace("project", "") + ".js";
+        markdown = markdown.replaceAll(linkMatch[1] + ".js.html#line", githubUrl + "#L").replaceAll(linkMatch[1] + ".js.html", githubUrl);
     }
+    
+    // Save markdown file
     fs.writeFileSync(
         path.join(outputDirectory, file.replace(".html", ".md")),
         markdown

internal/documentation/jsdoc-to-markdown.sh

@@ -31,8 +31,9 @@
 		"preview": "vitepress preview --port 8080",
 		"jsdoc": "npm run jsdoc-generate && npm run jsdoc-to-markdown",
 		"jsdoc-generate": "jsdoc -c jsdoc/jsdoc-workspace.json -t $(node -p 'path.dirname(require.resolve(\"docdash\"))') ./ || (echo 'Error during JSDoc generation! Check log.' && exit 1)",
-		"jsdoc-generate-gh-pages": "jsdoc -c jsdoc/jsdoc.json -t $(node -p 'path.dirname(require.resolve(\"docdash\"))') ./ || (echo 'Error during JSDoc generation! Check log.' && exit 1)",
+		"jsdoc-generate-gh-pages": "jsdoc -c jsdoc/jsdoc.json -t $(node -p 'path.dirname(require.resolve(\"docdash\"))') ./ || (echo 'Error during JSDoc generation! Check log.' && exit 1) && npm run jsdoc-to-markdown-gh-pages",
 		"jsdoc-to-markdown": "node ./jsdoc-to-markdown.js",
+		"jsdoc-to-markdown-gh-pages": "node ./jsdoc-to-markdown.js gh-pages",
 		"generate-cli-doc": "node ./scripts/generateCliDoc.js",
 		"schema-generate": "node ./scripts/buildSchema.js",
 		"schema-generate-gh-pages": "node ./scripts/buildSchema.js gh-pages",