build: fix cross document links in docusaurus

Author: Neunerlei

_changelog/2.4.0.md

@@ -18,7 +18,7 @@
 ### Quality of Life
 
 - Allow `DB_BACKUP_INTERVAL` to be set to `never`, to disable automatic database backups. This is useful for users who want to manage their own backup strategy or do not want to use the built-in backup functionality.
-- Adds a new `DB_BACKUP_INTERVAL_ARGS` environment variable, that works in tandem with `DB_BACKUP_INTERVAL`, to allow more fine-grained control over the database backup process. Read more in the [Dot Env documentation](/architecture/10-dot%20Env)
+- Adds a new `DB_BACKUP_INTERVAL_ARGS` environment variable, that works in tandem with `DB_BACKUP_INTERVAL`, to allow more fine-grained control over the database backup process. Read more in the [Dot Env documentation](../_documentation/3-architecture/10-dot%20Env.md)
 - Adds new `APP_TRUSTED_PROXIES` environment variable, to the app to run behind a reverse proxy with SSL termination. Read more in the [Dot Env documentation](../_documentation/3-architecture/10-dot%20Env.md#APP_TRUSTED_PROXIES)
 - `php artisan check:model-status` is now `php artisan ai:models:check-status`, to be more consistent with the naming of other AI related commands. The old command name is still available as an alias, but it is recommended to use the new command name.
 

_documentation.build/docusaurus.config.js

@@ -1,6 +1,7 @@
 // @ts-check
 import {themes as prismThemes} from 'prism-react-renderer';
 import {changelogSorter} from './changelogSorter.js';
+import remarkRewriteCrossDocLinks from './remarkRewriteCrossDocLinks.js';
 
 // The "x" is there, because the docs are stored in the parent directory, which confuses docusaurus
 // It will be automatically be stripped out by docusaurus
@@ -37,6 +38,7 @@ const config = {
                 id: 'changelog',
                 sidebarPath: require.resolve('./sidebars-changelog.js'),
                 editUrl: editUrl,
+                beforeDefaultRemarkPlugins: [remarkRewriteCrossDocLinks],
                 async sidebarItemsGenerator({docs}) {
                     return changelogSorter(docs, githubOrganization, githubProject);
                 }
@@ -53,7 +55,8 @@ const config = {
                     path: '../_documentation',
                     routeBasePath: '/',
                     sidebarPath: require.resolve('./sidebars-docs.js'),
-                    editUrl: editUrl
+                    editUrl: editUrl,
+                    beforeDefaultRemarkPlugins: [remarkRewriteCrossDocLinks]
                 },
                 theme: {
                     customCss: require.resolve('./custom.css')

_documentation.build/package-lock.json

@@ -20,8 +20,9 @@
     "clsx": "^2.0.0",
     "prism-react-renderer": "^2.3.0",
     "react": "^18.0.0",
-      "react-dom": "^18.0.0",
-      "semver": "^7.7.3"
+    "react-dom": "^18.0.0",
+    "semver": "^7.7.3",
+    "unist-util-visit": "^5.1.0"
   },
   "devDependencies": {
     "@docusaurus/module-type-aliases": "3.6.3",

_documentation.build/package.json

@@ -0,0 +1,88 @@
+import {visit} from 'unist-util-visit';
+
+/**
+ * A remark plugin that rewrites cross-documentation-root links in markdown files.
+ *
+ * In the source markdown, authors write relative links across doc roots like:
+ *   ../_documentation/3-architecture/10-dot Env.md#ANCHOR  (from _changelog)
+ *   ../_changelog/2.4.0.md                                 (from _documentation)
+ *
+ * These links work on GitHub but break in Docusaurus because `_changelog` and `_documentation`
+ * are separate docs plugin instances with different base paths.
+ *
+ * This plugin rewrites those links to absolute Docusaurus URLs by:
+ *   1. Detecting `../_documentation/` or `../_changelog/` prefixes
+ *   2. Removing the `.md` extension
+ *   3. Stripping Docusaurus-style number prefixes (e.g. `3-` from dirs, `10-` from files)
+ *   4. Prepending the target routeBasePath (`/` for docs, `/changelog` for changelog)
+ *
+ * The result is a valid absolute URL like `/architecture/dot%20Env#anchor`
+ * or `/changelog/2.4.0`
+ */
+function remarkRewriteCrossDocLinks() {
+    /**
+     * Strips a Docusaurus-style number prefix from a single path segment.
+     * E.g. "3-architecture" -> "architecture", "10-dot Env" -> "dot Env"
+     * But preserves prefixes like "10.1-Model Config" (version-like, ignored by Docusaurus).
+     */
+    function stripNumberPrefix(segment) {
+        // Docusaurus ignores prefixes that look like versions: \d+[-_.]\d+
+        if (/^\d+[-_.]\d+/.test(segment)) {
+            return segment;
+        }
+        // Strip pattern: leading digits followed by separator(s)
+        return segment.replace(/^\d+\s*[-_.]+\s*/, '');
+    }
+
+    /**
+     * Maps a `../<sourceDir>/` prefix to the corresponding Docusaurus routeBasePath.
+     */
+    const prefixToRouteBase = {
+        '_documentation': '',    // routeBasePath: '/'
+        '_changelog': 'changelog' // routeBasePath: 'changelog'
+    };
+
+    const prefixPattern = new RegExp(
+        '^\\.\\.\/(' + Object.keys(prefixToRouteBase).join('|') + ')\/(.*)'
+    );
+
+    return (tree) => {
+        visit(tree, 'link', (node) => {
+            if (!node.url) return;
+
+            const match = node.url.match(prefixPattern);
+            if (!match) return;
+
+            const sourceDir = match[1];
+            const routeBase = prefixToRouteBase[sourceDir];
+            let targetPath = match[2];
+
+            // Separate anchor from path
+            let anchor = '';
+            const hashIndex = targetPath.indexOf('#');
+            if (hashIndex !== -1) {
+                anchor = targetPath.substring(hashIndex).toLowerCase();
+                targetPath = targetPath.substring(0, hashIndex);
+            }
+
+            // Remove .md extension
+            targetPath = targetPath.replace(/\.md$/, '');
+
+            // Decode URL encoding (e.g. %20 -> space) so we can process segments
+            targetPath = decodeURIComponent(targetPath);
+
+            // Strip number prefixes from each path segment
+            const segments = targetPath.split('/').map(stripNumberPrefix);
+
+            // Re-encode spaces and rebuild path
+            const rewrittenPath = '/' + [routeBase, ...segments]
+                .filter(Boolean)
+                .map(s => encodeURIComponent(s))
+                .join('/');
+
+            node.url = rewrittenPath + anchor;
+        });
+    };
+}
+
+export default remarkRewriteCrossDocLinks;