Showcase section to the docs - keepings docs up to date (#4055)

* Add a Showcase section to the docs with Swimm

* Build docs

* Move FAQ to Config

* Create showcases page

* Build docs

* Prettier

* feat: Redirect old docs URLs

---------

Co-authored-by: Sidharth Vinod <sidharthv96@gmail.com>

docs/config/faq.md

@@ -2,7 +2,7 @@
 >
 > ## THIS IS AN AUTOGENERATED FILE. DO NOT EDIT.
 >
-> ## Please edit the corresponding file in [/packages/mermaid/src/docs/misc/faq.md](../../packages/mermaid/src/docs/misc/faq.md).
+> ## Please edit the corresponding file in [/packages/mermaid/src/docs/config/faq.md](../../packages/mermaid/src/docs/config/faq.md).
 
 # Frequently Asked Questions
 

docs/ecosystem/integrations.md

@@ -2,7 +2,7 @@
 >
 > ## THIS IS AN AUTOGENERATED FILE. DO NOT EDIT.
 >
-> ## Please edit the corresponding file in [/packages/mermaid/src/docs/misc/integrations.md](../../packages/mermaid/src/docs/misc/integrations.md).
+> ## Please edit the corresponding file in [/packages/mermaid/src/docs/ecosystem/integrations.md](../../packages/mermaid/src/docs/ecosystem/integrations.md).
 
 # Integrations
 

docs/ecosystem/showcases.md

@@ -0,0 +1,9 @@
+> **Warning**
+>
+> ## THIS IS AN AUTOGENERATED FILE. DO NOT EDIT.
+>
+> ## Please edit the corresponding file in [/packages/mermaid/src/docs/ecosystem/showcases.md](../../packages/mermaid/src/docs/ecosystem/showcases.md).
+
+# Showcases
+
+- [Swimm - Up-to-date diagrams with Swimm, the knowledge management tool for code](https://docs.swimm.io/Features/diagrams-and-charts).

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

@@ -77,8 +77,8 @@ function sidebarAll() {
       ],
     },
     ...sidebarSyntax(),
+    ...sidebarEcosystem(),
     ...sidebarConfig(),
-    ...sidebarMisc(),
     ...sidebarCommunity(),
   ];
 }
@@ -125,19 +125,20 @@ function sidebarConfig() {
         { text: 'Accessibility', link: '/config/accessibility' },
         { text: 'Mermaid CLI', link: '/config/mermaidCLI' },
         { text: 'Advanced usage', link: '/config/n00b-advanced' },
+        { text: 'FAQ', link: '/config/faq' },
       ],
     },
   ];
 }
 
-function sidebarMisc() {
+function sidebarEcosystem() {
   return [
     {
-      text: '📚 Misc',
+      text: '📚 Ecosystem',
       collapsible: true,
       items: [
-        { text: 'Use-Cases and Integrations', link: '/misc/integrations' },
-        { text: 'FAQ', link: '/misc/faq' },
+        { text: 'Showcases', link: '/ecosystem/showcases' },
+        { text: 'Use-Cases and Integrations', link: '/ecosystem/integrations' },
       ],
     },
   ];

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

@@ -10,9 +10,6 @@ export default {
     // register global components
     app.component('Mermaid', Mermaid);
     router.onBeforeRouteChange = (to) => {
-      if (router.route.path !== '/') {
-        return;
-      }
       try {
         const newPath = getRedirect(to);
         if (newPath) {

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

@@ -5,31 +5,34 @@ import { expect, test } from 'vitest';
 import { getRedirect } from './redirect';
 
 test.each([
+  // Old docs, localhost
   ['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.org/#/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'],
+  // Old docs, github pages
+  ['https://mermaid-js.github.io/mermaid/#/flowchart.md', 'syntax/flowchart.html'], // without dot
+  ['https://mermaid-js.github.io/mermaid/#/./flowchart', 'syntax/flowchart.html'], // with dot
+  ['https://mermaid-js.github.io/mermaid/#flowchart', 'syntax/flowchart.html'], // without slash
+  ['https://mermaid-js.github.io/mermaid/#/flowchart', 'syntax/flowchart.html'], // with slash
+  ['https://mermaid-js.github.io/mermaid/#/flowchart.md?id=my-id', 'syntax/flowchart.html#my-id'], // with id
+  ['https://mermaid-js.github.io/mermaid/#/./flowchart.md?id=my-id', 'syntax/flowchart.html#my-id'], // with id and dot
   [
-    'https://mermaid-js.github.io/mermaid/#/flowchart?another=test&id=my-id&one=more',
+    'https://mermaid-js.github.io/mermaid/#/flowchart?another=test&id=my-id&one=more', // with multiple params
     '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/#/n00b-advanced', 'config/n00b-advanced.html'], // without .md
+  ['https://mermaid-js.github.io/mermaid/#/n00b-advanced.md', 'config/n00b-advanced.html'], // with .md
   [
-    'https://mermaid-js.github.io/mermaid/#/flowchart?id=a-node-in-the-form-of-a-circle',
+    'https://mermaid-js.github.io/mermaid/#/flowchart?id=a-node-in-the-form-of-a-circle', // with id, without .md
     'syntax/flowchart.html#a-node-in-the-form-of-a-circle',
   ],
+  // Old docs, without base path, new domain
+  ['https://mermaid.js.org/#/flowchart.md', 'syntax/flowchart.html'],
+  // New docs, without base path, new domain
+  ['https://mermaid.js.org/misc/faq.html', 'configure/faq.html'],
+  [
+    'https://mermaid.js.org/misc/faq.html#frequently-asked-questions',
+    'configure/faq.html#frequently-asked-questions',
+  ], // with hash
 ])('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();
-});

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

@@ -1,4 +1,4 @@
-export interface Redirect {
+interface Redirect {
   path: string;
   id?: string;
 }
@@ -7,15 +7,7 @@ export interface Redirect {
  * 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 !== 'mermaid.js.org' &&
-    url.hostname !== 'localhost'
-  ) {
-    throw new Error('Not mermaidjs url');
-  }
+const getBaseFile = (url: URL): Redirect => {
   const [path, params, ...rest] = url.hash
     .toLowerCase()
     .replace('.md', '')
@@ -32,7 +24,7 @@ const getBaseFile = (link: string): Redirect => {
   return { path, id };
 };
 
-const redirectMap: Record<string, string> = {
+const idRedirectMap: Record<string, string> = {
   '8.6.0_docs': '',
   accessibility: 'config/theming',
   breakingchanges: '',
@@ -76,15 +68,25 @@ const redirectMap: Record<string, string> = {
   'user-journey': 'syntax/userJourney',
 };
 
+const urlRedirectMap: Record<string, string> = {
+  '/misc/faq.html': 'configure/faq.html',
+};
+
 /**
  *
  * @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;
+  const url = new URL(link);
+  // Redirects for deprecated vitepress URLs
+  if (url.pathname in urlRedirectMap) {
+    return `${urlRedirectMap[url.pathname]}${url.hash}`;
+  }
+
+  // Redirects for old docs URLs
+  const { path, id } = getBaseFile(url);
+  if (path in idRedirectMap) {
+    return `${idRedirectMap[path]}.html${id ? `#${id}` : ''}`;
   }
-  return `${redirectMap[path]}.html${id ? `#${id}` : ''}`;
 };

packages/mermaid/src/docs/ecosystem/showcases.md

@@ -0,0 +1,3 @@
+# Showcases
+
+- [Swimm - Up-to-date diagrams with Swimm, the knowledge management tool for code](https://docs.swimm.io/Features/diagrams-and-charts).