fix: use remark to transform changelogs better

Author: barjin

apify-docs-theme/package.json

@@ -26,7 +26,8 @@
         "babel-loader": "^9.1.3",
         "docusaurus-gtm-plugin": "^0.0.2",
         "postcss-preset-env": "^9.3.0",
-        "prism-react-renderer": "^2.0.6"
+        "prism-react-renderer": "^2.0.6",
+        "remark": "^15.0.1"
     },
     "peerDependencies": {
         "clsx": "*",

apify-docs-theme/src/markdown.js

@@ -1,31 +1,102 @@
+const { remark } = require('remark');
+
 function updateChangelog(changelog) {
+    const tree = remark.parse(changelog);
+
+    bumpHeadingsLevels(tree);
+    linkifyUserTags(tree);
+    prettifyPRLinks(tree);
+
+    changelog = remark.stringify(tree);
     changelog = addFrontmatter(changelog);
-    changelog = pushHeadings(changelog);
-    changelog = fixUserLinks(changelog);
-    changelog = fixPRLinks(changelog);
     changelog = escapeMDXCharacters(changelog);
     return changelog;
 }
 
-function addFrontmatter(changelog, header = 'Changelog') {
-    return `---
-title: ${header}
-sidebar_label: ${header}
-toc_max_heading_level: 2
----
-${changelog}`;
+function bumpHeadingsLevels(tree) {
+    tree.children?.forEach((child) => {
+        if (child.type === 'heading') {
+            child.depth += 1;
+        }
+
+        bumpHeadingsLevels(child);
+    });
 }
 
-function pushHeadings(changelog) {
-    return changelog.replaceAll(/\n#[^#]/g, '\n## ');
+function linkifyUserTags(tree) {
+    for (let i = 0; i < tree.children?.length; i++) {
+        const child = tree.children[i];
+        if (child.type === 'text') {
+            const userTagRegex = /@([a-zA-Z0-9-]+)(\s|$)/g;
+            const match = userTagRegex.exec(child.value);
+
+            if (match) {
+                const [_, username, ending] = match;
+                const before = child.value.slice(0, match.index);
+                const after = child.value.slice(userTagRegex.lastIndex);
+
+                const link = {
+                    type: 'link',
+                    url: `https://github.com/${username}`,
+                    children: [{ type: 'text', value: `@${username}` }],
+                };
+                child.value = before;
+
+                tree.children.splice(i + 1, 0, link);
+
+                if (after) {
+                    tree.children.splice(i + 2, 0, { type: 'text', value: `${ending}${after}` });
+                }
+
+                i += 2;
+            }
+        }
+
+        linkifyUserTags(child);
+    }
 }
 
-function fixUserLinks(changelog) {
-    return changelog.replaceAll(/by @([a-zA-Z0-9-]+)/g, 'by [@$1](https://github.com/$1)');
+// If there is a PR URL (https://github.com/**/**/pull/number) in the text body, split the body, and replace the URL with a link to the PR (the text should be the PR number).
+function prettifyPRLinks(tree) {
+    for (let i = 0; i < tree.children?.length; i++) {
+        const child = tree.children[i];
+        if (child.type === 'text') {
+            const prLinkRegex = /https:\/\/github.com\/.*\/pull\/(\d+)/g;
+            const match = prLinkRegex.exec(child.value);
+
+            if (match) {
+                const [_, prNumber] = match;
+                const before = child.value.slice(0, match.index);
+                const after = child.value.slice(prLinkRegex.lastIndex);
+
+                const link = {
+                    type: 'link',
+                    url: match[0],
+                    children: [{ type: 'text', value: `#${prNumber}` }],
+                };
+                child.value = before;
+
+                tree.children.splice(i + 1, 0, link);
+
+                if (after) {
+                    tree.children.splice(i + 2, 0, { type: 'text', value: after });
+                }
+
+                i += 2;
+            }
+        }
+
+        prettifyPRLinks(child);
+    }
 }
 
-function fixPRLinks(changelog) {
-    return changelog.replaceAll(/(((https?:\/\/)?(www.)?)?github.com\/[^\s]*?\/pull\/([0-9]+))/g, '[#$5]($1)');
+function addFrontmatter(changelog, header = 'Changelog') {
+    return `---
+title: ${header}
+sidebar_label: ${header}
+toc_max_heading_level: 3
+---
+${changelog}`;
 }
 
 function escapeMDXCharacters(changelog) {