From: Eduardo San Martin Morote <posva13@gmail.com>
Date: Tue, 1 Aug 2023 18:16:11 +0000 (+0200)
Subject: docs: upgrade api docs generation
X-Git-Tag: v4.2.5~22
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=7d992a2d8543bf8470eed79cabc87e89f9ae5770;p=thirdparty%2Fvuejs%2Frouter.git

docs: upgrade api docs generation

No longer need to manually edit duplicated links
---

diff --git a/package.json b/package.json
index a611511c..daaf2b25 100644
--- a/package.json
+++ b/package.json
@@ -35,7 +35,7 @@
     "prettier": "^2.8.8",
     "semver": "^7.5.4",
     "typedoc": "^0.24.8",
-    "typedoc-plugin-markdown": "^3.15.3",
+    "typedoc-plugin-markdown": "^3.15.4",
     "typescript": "~5.1.6",
     "yorkie": "^2.0.0"
   },
diff --git a/packages/docs/.vitepress/config/shared.ts b/packages/docs/.vitepress/config/shared.ts
index a028d2f0..cf84a4f6 100644
--- a/packages/docs/.vitepress/config/shared.ts
+++ b/packages/docs/.vitepress/config/shared.ts
@@ -35,6 +35,10 @@ export const sharedConfig = defineConfig({
       leftDelimiter: '%{',
       rightDelimiter: '}%',
     },
+
+    anchor: {
+      slugify: s => s.replace(/\s/g, '-'),
+    },
   },
 
   head: [
diff --git a/packages/docs/package.json b/packages/docs/package.json
index b676dcbd..940f7f64 100644
--- a/packages/docs/package.json
+++ b/packages/docs/package.json
@@ -8,7 +8,7 @@
     "docs:build": "vitepress build ."
   },
   "dependencies": {
-    "vitepress": "1.0.0-alpha.76",
+    "vitepress": "1.0.0-beta.7",
     "vue-router": "workspace:*"
   }
 }
diff --git a/packages/docs/typedoc-markdown.js b/packages/docs/typedoc-markdown.js
index 6cc4f04f..4e4d4ce3 100644
--- a/packages/docs/typedoc-markdown.js
+++ b/packages/docs/typedoc-markdown.js
@@ -2,9 +2,6 @@ const _fs = require('fs')
 const path = require('path')
 const TypeDoc = require('typedoc')
 const { PageEvent } = TypeDoc
-const {
-  prependYAML,
-} = require('typedoc-plugin-markdown/dist/utils/front-matter')
 
 const fs = _fs.promises
 
@@ -15,6 +12,7 @@ const DEFAULT_OPTIONS = {
   readme: 'none',
   out: path.resolve(__dirname, './api'),
   entryDocument: 'index.md',
+  preserveAnchorCasing: true,
   hideBreadcrumbs: false,
   hideInPageTOC: true,
 }
@@ -33,13 +31,6 @@ exports.createTypeDocApp = function createTypeDocApp(config = {}) {
 
   // If you want TypeDoc to load tsconfig.json / typedoc.json files
   app.options.addReader(new TypeDoc.TSConfigReader())
-  // app.options.addReader(new TypeDoc.TypeDocReader())
-
-  /** @type {'build' | 'serve'} */
-  let targetMode = 'build'
-
-  const slugify = s => s.replaceAll(' ', '-')
-  // encodeURIComponent(String(s).trim().toLowerCase().replace(/\s+/g, '-'))
 
   app.renderer.on(
     PageEvent.END,
@@ -48,55 +39,10 @@ exports.createTypeDocApp = function createTypeDocApp(config = {}) {
      * @param {import('typedoc/dist/lib/output/events').PageEvent} page
      */
     page => {
-      if (page.url !== 'index.md' && page.contents) {
-        page.contents = prependYAML(page.contents, {
-          // TODO: figure out a way to point to the source files?
-          editLink: false,
-        })
-      }
-
-      // avoid duplicated id titles
-      if (page.contents) {
-        const lines = page.contents.split('\n')
-        const titleStack = []
-        let currentLevel = 0
-        const TITLE_LEVEL = /^#+/
-        const existingIds = new Map()
-        for (let i = 0; i < lines.length; i++) {
-          const line = lines[i]
-          if (!line.startsWith('#')) continue
-          const level = line.match(TITLE_LEVEL)[0].length
-
-          // remove extra levels
-          if (level <= currentLevel) {
-            titleStack.splice(level - 1)
-          }
-          // add the current title
-          titleStack.push(line.slice(level).trim())
-          currentLevel = level
-
-          // no need to add ids to h1
-          if (level < 2) continue
-
-          // ignore the root level (h1) to match the sidebar
-          const slugifiedTitle = slugify(titleStack.slice(1).join('-'))
-            // ensure the link is valid #1743
-            .replaceAll('\\', '')
-          let id
-          if (existingIds.has(slugifiedTitle)) {
-            const current = existingIds.get(slugifiedTitle)
-            existingIds.set(slugifiedTitle, current + 1)
-            id = ` %{#${slugifiedTitle}_${current + 1}}%`
-          } else {
-            existingIds.set(slugifiedTitle, 0)
-            id = ` %{#${slugifiedTitle}}%`
-          }
-          const newLine = line + id
-          lines.splice(i, 1, newLine)
-        }
-
-        page.contents = lines.join('\n')
-      }
+      page.contents = prependYAML(page.contents, {
+        // TODO: figure out a way to point to the source files?
+        editLink: false,
+      })
     }
   )
 
@@ -156,3 +102,43 @@ async function exists(path) {
     return false
   }
 }
+/**
+ * @typedef {Record<string, string | number | boolean>} FrontMatterVars
+ */
+
+/**
+ * Prepends YAML block to a string
+ * @param {string} contents - string to prepend to
+ * @param {FrontMatterVars} vars - object of required front matter variables
+ */
+function prependYAML(contents, vars) {
+  return contents
+    .replace(/^/, toYAML(vars) + '\n\n')
+    .replace(/[\r\n]{3,}/g, '\n\n')
+}
+
+/**
+ * Converts YAML object to a YAML string
+ * @param {FrontMatterVars} vars
+ */
+function toYAML(vars) {
+  const yaml = `---
+${Object.entries(vars)
+  .map(
+    ([key, value]) =>
+      `${key}: ${
+        typeof value === 'string' ? `"${escapeDoubleQuotes(value)}"` : value
+      }`
+  )
+  .join('\n')}
+---`
+  return yaml
+}
+
+/**
+ * Escapes double quotes in a string
+ * @param {string} str - string to escape
+ */
+function escapeDoubleQuotes(str) {
+  return str.replace(/"/g, '\\"')
+}