Merge pull request #3797 from mermaid-js/sidv/redirectOldDocs

feat: Redirect old documentation links.

cSpell.json

@@ -116,5 +116,8 @@
     "Multi-line code blocks",
     "HTML Tags"
   ],
-  "ignorePaths": ["packages/mermaid/src/docs/CHANGELOG.md"]
+  "ignorePaths": [
+    "packages/mermaid/src/docs/CHANGELOG.md",
+    "packages/mermaid/src/docs/.vitepress/redirect.ts"
+  ]
 }

packages/mermaid/src/docs.mts

@@ -245,7 +245,7 @@ const transformHtml = (filename: string) => {
 };
 
 const getGlobs = (globs: string[]): string[] => {
-  globs.push('!**/dist');
+  globs.push('!**/dist', '!**/redirect.spec.ts');
   if (!vitepress) {
     globs.push('!**/.vitepress', '!**/vite.config.ts', '!src/docs/index.md');
   }

packages/mermaid/src/docs/.vitepress/config.ts

@@ -35,7 +35,7 @@ function nav() {
     { text: 'Intro', link: '/intro/', activeMatch: '/intro/' },
     {
       text: 'Configuration',
-      link: '/config/Tutorials',
+      link: '/config/configuration',
       activeMatch: '/config/',
     },
     { text: 'Syntax', link: '/syntax/classDiagram', activeMatch: '/syntax/' },
@@ -118,6 +118,7 @@ function sidebarConfig() {
       text: '⚙️ Deployment and Configuration',
       collapsible: true,
       items: [
+        { text: 'Configuration', link: '/config/configuration' },
         { text: 'Tutorials', link: '/config/Tutorials' },
         { text: 'API-Usage', link: '/config/usage' },
         { text: 'Mermaid API Configuration', link: '/config/setup/README' },
@@ -126,7 +127,6 @@ function sidebarConfig() {
         { text: 'Accessibility', link: '/config/accessibility' },
         { text: 'Mermaid CLI', link: '/config/mermaidCLI' },
         { text: 'Advanced usage', link: '/config/n00b-advanced' },
-        { text: 'Configuration', link: '/config/configuration' },
       ],
     },
   ];

packages/mermaid/src/docs/.vitepress/theme/index.ts

@@ -2,11 +2,25 @@ import DefaultTheme from 'vitepress/theme';
 // @ts-ignore
 import Mermaid from 'vitepress-plugin-mermaid/Mermaid.vue';
 import './custom.css';
+import { getRedirect } from './redirect';
 
 export default {
   ...DefaultTheme,
-  enhanceApp({ app }) {
+  enhanceApp({ app, router }) {
     // register global components
     app.component('Mermaid', Mermaid);
+    router.onBeforeRouteChange = (to) => {
+      if (router.route.path !== '/') {
+        return;
+      }
+      try {
+        const newPath = getRedirect(to);
+        if (newPath) {
+          console.log(`Redirecting to ${newPath} from ${window.location}`);
+          // router.go isn't loading the ID properly.
+          window.location.href = `/mermaid/${newPath}`;
+        }
+      } catch (e) {}
+    };
   },
-};
+} as typeof DefaultTheme;

packages/mermaid/src/docs/.vitepress/theme/redirect.ts

@@ -0,0 +1,89 @@
+export interface Redirect {
+  path: string;
+  id?: string;
+}
+
+/**
+ * Extracts the base slug from the old URL.
+ * @param link - The old URL.
+ */
+const getBaseFile = (link: string): Redirect => {
+  const url = new URL(link);
+  if (
+    (url.hostname !== 'mermaid-js.github.io' && url.hostname !== 'localhost') ||
+    url.pathname !== '/mermaid/'
+  ) {
+    throw new Error('Not mermaidjs url');
+  }
+  const [path, params, ...rest] = url.hash
+    .toLowerCase()
+    .replace('.md', '')
+    .replace(/^#\/?/g, '')
+    .replace(/^\.\//g, '')
+    .split('?');
+
+  // Find id in params
+  const id = params
+    ?.split('&')
+    .find((param) => param.startsWith('id='))
+    ?.split('=')[1];
+
+  return { path, id };
+};
+
+const redirectMap: Record<string, string> = {
+  '8.6.0_docs': '',
+  accessibility: 'config/theming',
+  breakingchanges: '',
+  c4c: 'syntax/c4c',
+  classdiagram: 'syntax/classDiagram',
+  configuration: 'config/configuration',
+  demos: 'misc/integrations',
+  development: 'community/development',
+  directives: 'config/directives',
+  entityrelationshipdiagram: 'syntax/entityRelationshipDiagram',
+  examples: 'syntax/examples',
+  faq: 'misc/faq',
+  flowchart: 'syntax/flowchart',
+  gantt: 'syntax/gantt',
+  gitgraph: 'syntax/gitgraph',
+  integrations: 'misc/integrations',
+  'language-highlight': '',
+  markdown: '',
+  mermaidapi: 'config/usage',
+  mermaidcli: 'config/mermaidCLI',
+  mindmap: 'syntax/mindmap',
+  'more-pages': '',
+  'n00b-advanced': 'config/n00b-advanced',
+  'n00b-gettingstarted': 'intro/n00b-gettingStarted',
+  'n00b-overview': 'community/n00b-overview',
+  'n00b-syntaxreference': '',
+  newdiagram: 'community/newDiagram',
+  pie: 'syntax/pie',
+  plugins: '',
+  quickstart: 'intro/n00b-gettingStarted',
+  requirementdiagram: 'syntax/requirementDiagram',
+  security: 'community/security',
+  sequencediagram: 'syntax/sequenceDiagram',
+  setup: 'config/setup/README',
+  statediagram: 'syntax/stateDiagram',
+  themes: 'config/theming',
+  theming: 'config/theming',
+  tutorials: 'config/Tutorials',
+  upgrading: '',
+  usage: 'config/usage',
+  'user-journey': 'syntax/userJourney',
+};
+
+/**
+ *
+ * @param link - The old documentation URL.
+ * @returns The new documentation path.
+ */
+export const getRedirect = (link: string): string | undefined => {
+  const { path, id } = getBaseFile(link);
+  if (!(path in redirectMap)) {
+    return;
+  }
+  return `${redirectMap[path]}.html${id ? `#${id}` : ''}`;
+};

packages/mermaid/src/docs/index.md

@@ -32,6 +32,7 @@ features:
 
 <script setup>
 import { VPTeamMembers } from 'vitepress/theme'
+
 const websiteSVG = {
   svg: '<svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="feather feather-globe"><circle cx="12" cy="12" r="10"></circle><line x1="2" y1="12" x2="22" y2="12"></line><path d="M12 2a15.3 15.3 0 0 1 4 10 15.3 15.3 0 0 1-4 10 15.3 15.3 0 0 1-4-10 15.3 15.3 0 0 1 4-10z"></path></svg>'
 }

packages/mermaid/src/docs/redirect.spec.ts

@@ -0,0 +1,37 @@
+// This file should be moved into .vitepress folder once https://github.com/vitest-dev/vitest/issues/2344 is resolved.
+// Update https://github.com/mermaid-js/mermaid/blob/18c27c6f1d0537a738cbd95898df301b83c38ffc/packages/mermaid/src/docs.mts#L246 once fixed
+
+import { expect, test } from 'vitest';
+import { getRedirect } from './.vitepress/theme/redirect';
+
+test.each([
+  ['http://localhost:1234/mermaid/#/flowchart.md', 'syntax/flowchart.html'],
+  ['http://localhost/mermaid/#/flowchart.md', 'syntax/flowchart.html'],
+  ['https://mermaid-js.github.io/mermaid/#/flowchart.md', 'syntax/flowchart.html'],
+  ['https://mermaid-js.github.io/mermaid/#/./flowchart', 'syntax/flowchart.html'],
+  ['https://mermaid-js.github.io/mermaid/#/flowchart', 'syntax/flowchart.html'],
+  ['https://mermaid-js.github.io/mermaid/#flowchart', 'syntax/flowchart.html'],
+  ['https://mermaid-js.github.io/mermaid/#/flowchart', 'syntax/flowchart.html'],
+  ['https://mermaid-js.github.io/mermaid/#/flowchart.md?id=my-id', 'syntax/flowchart.html#my-id'],
+  ['https://mermaid-js.github.io/mermaid/#/./flowchart.md?id=my-id', 'syntax/flowchart.html#my-id'],
+  [
+    'https://mermaid-js.github.io/mermaid/#/flowchart?another=test&id=my-id&one=more',
+    'syntax/flowchart.html#my-id',
+  ],
+  ['https://mermaid-js.github.io/mermaid/#/n00b-advanced', 'config/n00b-advanced.html'],
+  ['https://mermaid-js.github.io/mermaid/#/n00b-advanced.md', 'config/n00b-advanced.html'],
+  [
+    'https://mermaid-js.github.io/mermaid/#/flowchart?id=a-node-in-the-form-of-a-circle',
+    'syntax/flowchart.html#a-node-in-the-form-of-a-circle',
+  ],
+])('should process url %s to %s', (link: string, path: string) => {
+  expect(getRedirect(link)).toBe(path);
+});
+
+test('should throw for invalid URL', () => {
+  // Not mermaid domain
+  expect(() => getRedirect('https://www.google.com')).toThrowError();
+
+  // Not `/mermaid/` path
+  expect(() => getRedirect('http://localhost/#/flowchart.md')).toThrowError();
+});