Improve link handling and support review apps

.gitlab-ci.yml

@@ -9,6 +9,18 @@ build:
   extends:
     - .build
   stage: build
+  variables:
+    C0_GLOBAL_BASE: /-/telescopium/-/jobs/$CI_JOB_ID/artifacts/dist
+  after_script:
+    - node scripts/local_link_suffixer.js
+    - |
+      echo -e "\e[0Ksection_start:`date +%s`:glpa_summary\r\e[0KHeader of the summary"
+      echo "Documentation preview available at https://code0-tech.gitlab.io${C0_GLOBAL_BASE}/index.html"
+      echo -e "\e[0Ksection_end:`date +%s`:glpa_summary\r\e[0K"
+  artifacts:
+    paths:
+      - dist
+    expire_in: 7 days
   rules:
     - if: ($CI_COMMIT_BRANCH != "build-branch" || $C0_TRIGGER_REF != "refs/heads/main") && $CI_COMMIT_BRANCH != "glpa/main"
 

astro.config.mjs

@@ -1,5 +1,6 @@
 import { defineConfig } from 'astro/config';
 import starlight from '@astrojs/starlight';
+import transformLocalLinks from "./src/plugins/transformLocalLinks.js";
 
 const defaultConfig = {
 	title: 'Code0 Documentation'
@@ -9,28 +10,6 @@ const config = process.env.SRC_DIR
 	? (await import(/* @vite-ignore */`${process.env.SRC_DIR}/docs/starlight.json`)).default
 	: defaultConfig;
 
-const transformLocalLinks = () => {
-	return {
-		name: 'transform-local-links',
-
-		transform(src, id) {
-			if (id.endsWith('.md') || id.endsWith('.mdx')) {
-				const directory = id.endsWith('index.md') || id.endsWith('index.mdx') ? '' : '../';
-
-				const code = src
-					.replaceAll(/\[([^\]]+?)]\(([^)]+?)\.mdx?\)/g, `[$1](${directory}$2/)`)
-					.replaceAll(/href=\\"([^"]+?)\.mdx?\\"/g, `href=\\"${directory}$1/\\"`)
-					.replaceAll(/href: "([^"]+?)\.mdx?"/g, `href: "${directory}$1/"`);
-
-				return {
-					code: code,
-					map: null, // provide source map if available
-				}
-			}
-		},
-	}
-}
-
 // https://astro.build/config
 export default defineConfig({
 	base: process.env.BASE_URL,

build.sh

@@ -13,7 +13,7 @@ build_project() {
   ln -s $(pwd)/projects/$project/docs/content projects/$project/content/docs
   ln $(pwd)/src/content/config.ts projects/$project/content/config.ts
   if [[ "$project" != "docs-landing-page" ]]; then
-    export BASE_URL=/$project/
+    export BASE_URL=$C0_GLOBAL_BASE/$project/
     export OUT_DIR=./dist/$project
   fi
   SRC_DIR=$(pwd)/projects/$project npm run build
@@ -23,6 +23,7 @@ build_project() {
   rm -rf projects/$project/env.d.ts
 }
 
+export BASE_URL=$C0_GLOBAL_BASE/
 build_project "docs-landing-page"
 
 for project in $(ls projects | grep -v docs-landing-page); do

ci-template.gitlab-ci.yml

@@ -8,3 +8,43 @@ docs:
     C0_TRIGGER_PROJECT: $CI_PROJECT_NAME
     C0_TRIGGER_SHA: $CI_COMMIT_SHA
     C0_TRIGGER_REF: $C0_GH_REF
+
+docs:preview:
+  stage: test
+  image: registry.gitlab.com/gitlab-ci-utils/curl-jq:latest
+  needs:
+    - docs
+  script:
+    - >
+      QUERY='{
+        "query":"query($fullPath: ID!, $iid: ID!, $bridgeJob: String!, $downstreamJob:String!) {
+          project(fullPath: $fullPath) {
+            pipeline(iid: $iid) {
+              job(name: $bridgeJob) {
+                downstreamPipeline {
+                job(name: $downstreamJob) { id }
+              }
+            }
+          }
+        }
+        }","variables":{
+          "fullPath":"'"$CI_PROJECT_PATH"'",
+          "iid":"'"$CI_PIPELINE_IID"'",
+          "bridgeJob":"docs",
+          "downstreamJob":"build"
+        }
+      }'
+    - INLINED_QUERY=${QUERY//[$'\t\r\n']}
+    - echo $INLINED_QUERY
+    - >
+      RESPONSE=$(curl
+      -X POST
+      --data "$INLINED_QUERY"
+      -H 'Content-Type: application/json'
+      https://gitlab.com/api/graphql)
+    - echo $RESPONSE
+    - BUILD_JOB_ID=$(echo "$RESPONSE" | jq -r .data.project.pipeline.job.downstreamPipeline.job.id | awk -F '/' '{print $NF}')
+    - |
+      echo -e "\e[0Ksection_start:`date +%s`:glpa_summary\r\e[0KHeader of the summary"
+      echo "Documentation preview available at https://code0-tech.gitlab.io/-/telescopium/-/jobs/$BUILD_JOB_ID/artifacts/dist/index.html"
+      echo -e "\e[0Ksection_end:`date +%s`:glpa_summary\r\e[0K"

projects/docs-landing-page/docs/content/index.mdx

@@ -7,18 +7,18 @@ template: splash
 import { Card, CardGrid } from '@astrojs/starlight/components';
 
 <CardGrid stagger>
-    <Card title='<a href="/pictor/">Pictor</a>' icon="document">
+    <Card title='<a href="pictor/">Pictor</a>' icon="document">
         Documentation about the component library.
     </Card>
-    <Card title='<a href="/sagittarius/">Sagittarius</a>' icon="rocket">
+    <Card title='<a href="sagittarius/">Sagittarius</a>' icon="rocket">
         Documentation about the backend.
     </Card>
 </CardGrid>
 
 ## Internal documentation
 
 <CardGrid stagger>
-    <Card title='<a href="/telescopium/">Telescopium</a>' icon="document">
+    <Card title='<a href="telescopium/">Telescopium</a>' icon="document">
         Documentation about this documentation page.
     </Card>
 </CardGrid>

scripts/local_link_suffixer.js

@@ -0,0 +1,52 @@
+import path from "path";
+import fs from "fs";
+
+const __dirname = path.resolve('dist');
+
+function getFiles(targetDirectory = '.') {
+    const directoryPath = path.join(__dirname, targetDirectory);
+    return readDirectoryRecursive(directoryPath, `${__dirname}/${targetDirectory}`);
+}
+
+function readDirectoryRecursive(directory, currentPath) {
+    const dirents = fs.readdirSync(directory, { withFileTypes: true });
+
+    const files = dirents.filter(dirent => dirent.isFile()).map(dirent => `${dirent.name}`);
+    const directories = dirents.filter(dirent => dirent.isDirectory());
+    directories.forEach(dir => {
+        const recursedFiles = readDirectoryRecursive(path.join(currentPath, dir.name), `${currentPath}/${dir.name}`).map(filename => `${dir.name}/${filename}`);
+        files.push(...recursedFiles);
+    });
+    return files;
+}
+
+function readFile(file) {
+    return fs.readFileSync(path.resolve(__dirname, file), "utf-8");
+}
+
+function writeFile(file, content) {
+    fs.writeFileSync(path.resolve(__dirname, file), content, "utf-8");
+}
+
+function suffixLink(match, url) {
+    const urlObj = new URL(url, 'https://docs.code0.tech');
+    if(urlObj.origin !== 'https://docs.code0.tech') {
+        // not a relative url
+        return match;
+    }
+
+    if(urlObj.pathname === '/' && urlObj.hash !== '') {
+        // mostly a link to a hash on the same page
+        return match;
+    }
+
+    return match.replace(url, url.split('#')[0] + 'index.html' + urlObj.hash);
+}
+
+getFiles().forEach(file => {
+    const content = readFile(file);
+
+    const replacedContent = content.replaceAll(/<a [^>]*?href="([^"]+?)"[^>]*?>/g, suffixLink);
+
+    writeFile(file, replacedContent);
+});

src/plugins/transformLocalLinks.js

@@ -0,0 +1,35 @@
+const replaceUrl = (directoryPrefix) => (match, fullUrl, matchedUrl) => {
+    if(new URL(fullUrl, 'https://docs.code0.tech').origin !== 'https://docs.code0.tech') {
+        // not a relative url
+        return match;
+    }
+
+    let replacementUrl = matchedUrl;
+
+    if(/(?:^|\/)index$/.test(matchedUrl)) {
+        replacementUrl = matchedUrl === 'index' ? '' : matchedUrl.replace(/\/index/, '');
+    }
+
+    return match.replace(fullUrl, `${directoryPrefix}${replacementUrl}/`.replace('//', ''))
+}
+
+export default () => ({
+    name: 'transform-local-links',
+
+    transform(src, id) {
+        if (id.endsWith('.md') || id.endsWith('.mdx')) {
+            const directory = id.endsWith('index.md') || id.endsWith('index.mdx') ? '' : '../';
+
+            const regexes = [
+                /\[[^\]]+?]\((([^)]+?)\.mdx?)\)/g,
+                /href=\\"(([^"]+?)\.mdx?)\\"/g,
+                /href: "(([^"]+?)\.mdx?)"/g
+            ]
+
+            return {
+                code: regexes.reduce((acc, regex) => acc.replaceAll(regex, replaceUrl(directory)), src),
+                map: null
+            }
+        }
+    },
+})