docs: use vue components for api-docs (#446)

8 files changed, 320 insertions, 142 deletions

diff --git a/docs/.vitepress/components/api-docs/method-parameters.vue b/docs/.vitepress/components/api-docs/method-parameters.vue
new file mode 100644
index 00000000..ca3aef37
--- /dev/null
+++ b/docs/.vitepress/components/api-docs/method-parameters.vue
@@ -0,0 +1,32 @@
+<script setup lang="ts">
+import type { MethodParameter } from './method';
+
+const props = defineProps<{ parameters: MethodParameter[] }>();
+</script>
+
+<template>
+  <div>
+    <h3>Parameters</h3>
+
+    <table>
+      <thead>
+        <tr>
+          <th>Name</th>
+          <th>Type</th>
+          <th>Default</th>
+          <th>Description</th>
+        </tr>
+      </thead>
+      <tbody>
+        <tr v-for="parameter of props.parameters" :key="parameter.name">
+          <td>{{ parameter.name }}</td>
+          <td>{{ parameter.type }}</td>
+          <td>
+            <code v-if="parameter.default">{{ parameter.default }}</code>
+          </td>
+          <td v-html="parameter.description"></td>
+        </tr>
+      </tbody>
+    </table>
+  </div>
+</template>
diff --git a/docs/.vitepress/components/api-docs/method.ts b/docs/.vitepress/components/api-docs/method.ts
new file mode 100644
index 00000000..ac0deb96
--- /dev/null
+++ b/docs/.vitepress/components/api-docs/method.ts
@@ -0,0 +1,14 @@
+export interface Method {
+  readonly name: string;
+  readonly description: string; // HTML
+  readonly parameters: MethodParameter[];
+  readonly returns: string;
+  readonly examples: string; // HTML
+}
+
+export interface MethodParameter {
+  readonly name: string;
+  readonly type?: string;
+  readonly default?: string;
+  readonly description: string; // HTML
+}
diff --git a/docs/.vitepress/components/api-docs/method.vue b/docs/.vitepress/components/api-docs/method.vue
new file mode 100644
index 00000000..fb1145cb
--- /dev/null
+++ b/docs/.vitepress/components/api-docs/method.vue
@@ -0,0 +1,23 @@
+<script setup lang="ts">
+import type { Method } from './method';
+import MethodParameters from './method-parameters.vue';
+
+const props = defineProps<{ method: Method }>();
+</script>
+
+<template>
+  <div>
+    <h2>{{ props.method.name }}</h2>
+
+    <div v-html="props.method.description"></div>
+
+    <MethodParameters
+      v-if="props.method.parameters.length > 0"
+      :parameters="props.method.parameters"
+    />
+
+    <p><strong>Returns:</strong> {{ props.method.returns }}</p>
+
+    <div v-html="props.method.examples" />
+  </div>
+</template>
diff --git a/docs/api/.gitignore b/docs/api/.gitignore
index 73d5e086..d77f28d2 100644
--- a/docs/api/.gitignore
+++ b/docs/api/.gitignore
@@ -1,3 +1,4 @@
 *.md
 !fake.md
 !localization.md
+*.ts
diff --git a/package.json b/package.json
index a1cf0da8..fb10043b 100644
--- a/package.json
+++ b/package.json
@@ -89,8 +89,10 @@
     ]
   },
   "devDependencies": {
+    "@types/markdown-it": "~12.2.3",
     "@types/node": "~16.11.25",
     "@types/prettier": "~2.4.4",
+    "@types/sanitize-html": "~2.6.2",
     "@types/validator": "~13.7.1",
     "@typescript-eslint/eslint-plugin": "~5.12.0",
     "@typescript-eslint/parser": "~5.12.0",
@@ -111,6 +113,7 @@
     "picocolors": "~1.0.0",
     "prettier": "2.5.1",
     "rimraf": "~3.0.2",
+    "sanitize-html": "~2.7.0",
     "simple-git-hooks": "~2.7.0",
     "standard-version": "~9.3.2",
     "typedoc": "~0.22.12",
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 901e8a79..12fc93f9 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -1,8 +1,10 @@
 lockfileVersion: 5.3
 
 specifiers:
+  '@types/markdown-it': ~12.2.3
   '@types/node': ~16.11.25
   '@types/prettier': ~2.4.4
+  '@types/sanitize-html': ~2.6.2
   '@types/validator': ~13.7.1
   '@typescript-eslint/eslint-plugin': ~5.12.0
   '@typescript-eslint/parser': ~5.12.0
@@ -23,6 +25,7 @@ specifiers:
   picocolors: ~1.0.0
   prettier: 2.5.1
   rimraf: ~3.0.2
+  sanitize-html: ~2.7.0
   simple-git-hooks: ~2.7.0
   standard-version: ~9.3.2
   typedoc: ~0.22.12
@@ -34,8 +37,10 @@ specifiers:
   vitest: ~0.4.2
 
 devDependencies:
+  '@types/markdown-it': 12.2.3
   '@types/node': 16.11.25
   '@types/prettier': 2.4.4
+  '@types/sanitize-html': 2.6.2
   '@types/validator': 13.7.1
   '@typescript-eslint/eslint-plugin': 5.12.0_c467cf9bb49b295941e83ce479a578b7
   '@typescript-eslint/parser': [email protected][email protected]
@@ -56,6 +61,7 @@ devDependencies:
   picocolors: 1.0.0
   prettier: 2.5.1
   rimraf: 3.0.2
+  sanitize-html: 2.7.0
   simple-git-hooks: 2.7.0
   standard-version: 9.3.2
   typedoc: [email protected]
@@ -365,6 +371,21 @@ packages:
     resolution: {integrity: sha512-qcUXuemtEu+E5wZSJHNxUXeCZhAfXKQ41D+duX+VYPde7xyEVZci+/oXKJL13tnRs9lR2pr4fod59GT6/X1/yQ==}
     dev: true
 
+  /@types/linkify-it/3.0.2:
+    resolution: {integrity: sha512-HZQYqbiFVWufzCwexrvh694SOim8z2d+xJl5UNamcvQFejLY/2YUtzXHYi3cHdI7PMlS8ejH2slRAOJQ32aNbA==}
+    dev: true
+
+  /@types/markdown-it/12.2.3:
+    resolution: {integrity: sha512-GKMHFfv3458yYy+v/N8gjufHO6MSZKCOXpZc5GXIWWy8uldwfmPn98vp81gZ5f9SVw8YYBctgfJ22a2d7AOMeQ==}
+    dependencies:
+      '@types/linkify-it': 3.0.2
+      '@types/mdurl': 1.0.2
+    dev: true
+
+  /@types/mdurl/1.0.2:
+    resolution: {integrity: sha512-eC4U9MlIcu2q0KQmXszyn5Akca/0jrQmwDRgpAMJai7qBWq4amIQhZyNau4VYGtCeALvW1/NtjzJJ567aZxfKA==}
+    dev: true
+
   /@types/minimist/1.2.2:
     resolution: {integrity: sha512-jhuKLIRrhvCPLqwPcx6INqmKeiA5EWrsCOPhrlFSrbrmU4ZMPjj5Ul/oLCMDO98XRUIwVm78xICz4EPCektzeQ==}
     dev: true
@@ -385,6 +406,12 @@ packages:
     resolution: {integrity: sha512-ReVR2rLTV1kvtlWFyuot+d1pkpG2Fw/XKE3PDAdj57rbM97ttSp9JZ2UsP+2EHTylra9cUf6JA7tGwW1INzUrA==}
     dev: true
 
+  /@types/sanitize-html/2.6.2:
+    resolution: {integrity: sha512-7Lu2zMQnmHHQGKXVvCOhSziQMpa+R2hMHFefzbYoYMHeaXR0uXqNeOc3JeQQQ8/6Xa2Br/P1IQTLzV09xxAiUQ==}
+    dependencies:
+      htmlparser2: 6.1.0
+    dev: true
+
   /@types/sinonjs__fake-timers/8.1.1:
     resolution: {integrity: sha512-0kSuKjAS0TrGLJ0M/+8MaFkGsQhZpB6pxOmvS3K8FYI72K//YmdfoW9X2qPsAKh1mkwxGD5zib9s1FIFed6E8g==}
     dev: true
@@ -1464,6 +1491,11 @@ packages:
     resolution: {integrity: sha512-oIPzksmTg4/MriiaYGO+okXDT7ztn/w3Eptv/+gSIdMdKsJo0u4CfYNFJPy+4SKMuCqGw2wxnA+URMg3t8a/bQ==}
     dev: true
 
+  /deepmerge/4.2.2:
+    resolution: {integrity: sha512-FJ3UgI4gIl+PHZm53knsuSFpE+nESMr7M4v9QcgB7S63Kj/6WqMiFQJpBBYz1Pt+66bZpP3Q7Lye0Oo9MPKEdg==}
+    engines: {node: '>=0.10.0'}
+    dev: true
+
   /define-properties/1.1.3:
     resolution: {integrity: sha512-3MqfYKj2lLzdMSf8ZIZE/V+Zuy+BgD6f164e8K2w7dgnpKArBDerGYpM46IYYcjnkdPNMjPk9A6VFB8+3SKlXQ==}
     engines: {node: '>= 0.4'}
@@ -1500,6 +1532,33 @@ packages:
       esutils: 2.0.3
     dev: true
 
+  /dom-serializer/1.3.2:
+    resolution: {integrity: sha512-5c54Bk5Dw4qAxNOI1pFEizPSjVsx5+bpJKmL2kPn8JhBUq2q09tTCa3mjijun2NfK78NMouDYNMBkOrPZiS+ig==}
+    dependencies:
+      domelementtype: 2.2.0
+      domhandler: 4.3.0
+      entities: 2.2.0
+    dev: true
+
+  /domelementtype/2.2.0:
+    resolution: {integrity: sha512-DtBMo82pv1dFtUmHyr48beiuq792Sxohr+8Hm9zoxklYPfa6n0Z3Byjj2IV7bmr2IyqClnqEQhfgHJJ5QF0R5A==}
+    dev: true
+
+  /domhandler/4.3.0:
+    resolution: {integrity: sha512-fC0aXNQXqKSFTr2wDNZDhsEYjCiYsDWl3D01kwt25hm1YIPyDGHvvi3rw+PLqHAl/m71MaiF7d5zvBr0p5UB2g==}
+    engines: {node: '>= 4'}
+    dependencies:
+      domelementtype: 2.2.0
+    dev: true
+
+  /domutils/2.8.0:
+    resolution: {integrity: sha512-w96Cjofp72M5IIhpjgobBimYEfoPjx1Vx0BSX9P30WBdZW2WIKU0T1Bd0kz2eNZ9ikjKgHbEyKx8BB6H1L3h3A==}
+    dependencies:
+      dom-serializer: 1.3.2
+      domelementtype: 2.2.0
+      domhandler: 4.3.0
+    dev: true
+
   /dot-prop/5.3.0:
     resolution: {integrity: sha512-QM8q3zDe58hqUqjraQOmzZ1LIH9SWQJTlEKCH4kJ2oQvLZk7RbQXvtDM2XEq3fwkV9CCvvH4LA0AV+ogFsBM2Q==}
     engines: {node: '>=8'}
@@ -1547,6 +1606,10 @@ packages:
       ansi-colors: 4.1.1
     dev: true
 
+  /entities/2.2.0:
+    resolution: {integrity: sha512-p92if5Nz619I0w+akJrLZH0MX0Pb5DX39XOwQTtXSdQQOaYH03S1uIQp4mhOZtAXrxq4ViO67YTiLBo2638o9A==}
+    dev: true
+
   /error-ex/1.3.2:
     resolution: {integrity: sha512-7dFHNmqeFSEt2ZBsCriorKnn3Z2pj+fd9kmI6QoWw4//DL+icEBfc0U7qJCisqrTsKTjw4fNFy2pW9OqStD84g==}
     dependencies:
@@ -2452,6 +2515,15 @@ packages:
     resolution: {integrity: sha512-H2iMtd0I4Mt5eYiapRdIDjp+XzelXQ0tFE4JS7YFwFevXXMmOp9myNrUvCg0D6ws8iqkRPBfKHgbwig1SmlLfg==}
     dev: true
 
+  /htmlparser2/6.1.0:
+    resolution: {integrity: sha512-gyyPk6rgonLFEDGoeRgQNaEUvdJ4ktTmmUh/h2t7s+M8oPpIPxgNACWa+6ESR57kXstwqPiCut0V8NRpcwgU7A==}
+    dependencies:
+      domelementtype: 2.2.0
+      domhandler: 4.3.0
+      domutils: 2.8.0
+      entities: 2.2.0
+    dev: true
+
   /http-signature/1.3.6:
     resolution: {integrity: sha512-3adrsD6zqo4GsTqtO7FyrejHNv+NgiIfAfv68+jVlFmSr9OGy7zrxONceFRLKvnnZA5jbxQBX1u9PpB6Wi32Gw==}
     engines: {node: '>=0.10'}
@@ -2643,6 +2715,11 @@ packages:
     engines: {node: '>=0.10.0'}
     dev: true
 
+  /is-plain-object/5.0.0:
+    resolution: {integrity: sha512-VRSzKkbMm5jMDoKLbltAkFQ5Qr7VDiTFGXxYFXXowVj387GeGNOCsOH6Msy00SGZ3Fp84b1Naa1psqgcCIEP5Q==}
+    engines: {node: '>=0.10.0'}
+    dev: true
+
   /is-regex/1.1.4:
     resolution: {integrity: sha512-kvRdxDsxZjhzUX07ZnLydzS1TU/TJlTUHHY4YLL87e37oUA49DfkLqgy+VjFocowy29cKvcSiu+kIv728jTTVg==}
     engines: {node: '>= 0.4'}
@@ -3321,6 +3398,10 @@ packages:
       lines-and-columns: 1.2.4
     dev: true
 
+  /parse-srcset/1.0.2:
+    resolution: {integrity: sha1-8r0iH2zJcKk42IVWq8WJyqqiveE=}
+    dev: true
+
   /path-exists/3.0.0:
     resolution: {integrity: sha1-zg6+ql94yxiSXqfYENe1mwEP1RU=}
     engines: {node: '>=4'}
@@ -3639,6 +3720,17 @@ packages:
     resolution: {integrity: sha512-YZo3K82SD7Riyi0E1EQPojLz7kpepnSQI9IyPbHHg1XXXevb5dJI7tpyN2ADxGcQbHG7vcyRHk0cbwqcQriUtg==}
     dev: true
 
+  /sanitize-html/2.7.0:
+    resolution: {integrity: sha512-jfQelabOn5voO7FAfnQF7v+jsA6z9zC/O4ec0z3E35XPEtHYJT/OdUziVWlKW4irCr2kXaQAyXTXDHWAibg1tA==}
+    dependencies:
+      deepmerge: 4.2.2
+      escape-string-regexp: 4.0.0
+      htmlparser2: 6.1.0
+      is-plain-object: 5.0.0
+      parse-srcset: 1.0.2
+      postcss: 8.4.6
+    dev: true
+
   /semver/5.7.1:
     resolution: {integrity: sha512-sauaDf/PZdVgrLTNYHRtpXa1iRiKcaebiKQ1BJdpQlWH2lCvexQdX55snPFyK7QzpudqbCI0qXFfOasHdyNDGQ==}
     hasBin: true
diff --git a/scripts/apidoc.ts b/scripts/apidoc.ts
index 81e0b510..93563248 100644
--- a/scripts/apidoc.ts
+++ b/scripts/apidoc.ts
@@ -1,9 +1,18 @@
-import * as TypeDoc from 'typedoc';
 import { writeFileSync } from 'fs';
 import { resolve } from 'path';
+import type { Options } from 'prettier';
 import { format } from 'prettier';
-import options from '../.prettierrc.cjs';
+import sanitizeHtml from 'sanitize-html';
+import * as TypeDoc from 'typedoc';
+import { createMarkdownRenderer } from 'vitepress';
+import prettierConfig from '../.prettierrc.cjs';
+import type {
+  Method,
+  MethodParameter,
+} from '../docs/.vitepress/components/api-docs/method';
 import faker from '../src';
+// TODO ST-DDT 2022-02-20: Actually import this/fix module import errors
+// import vitepressConfig from '../docs/.vitepress/config';
 
 const pathRoot = resolve(__dirname, '..');
 const pathDocsDir = resolve(pathRoot, 'docs');
@@ -13,6 +22,38 @@ const pathOutputJson = resolve(pathOutputDir, 'typedoc.json');
 
 const scriptCommand = 'pnpm run generate:api-docs';
 
+const markdown = createMarkdownRenderer(
+  pathOutputDir
+  // TODO ST-DDT 2022-02-20: Actually import this/fix module import errors
+  // vitepressConfig.markdown
+);
+
+const prettierMarkdown: Options = {
+  ...prettierConfig,
+  parser: 'markdown',
+};
+
+const prettierTypescript: Options = {
+  ...prettierConfig,
+  parser: 'typescript',
+};
+
+const prettierBabel: Options = {
+  ...prettierConfig,
+  parser: 'babel',
+};
+
+const htmlSanitizeOptions: sanitizeHtml.IOptions = {
+  allowedTags: ['a', 'code', 'div', 'li', 'span', 'p', 'pre', 'ul'],
+  allowedAttributes: {
+    a: ['href', 'target', 'rel'],
+    div: ['class'],
+    pre: ['v-pre'],
+    span: ['class'],
+  },
+  selfClosing: [],
+};
+
 function toBlock(comment?: TypeDoc.Comment): string {
   return (
     (comment?.shortText.trim() || 'Missing') +
@@ -20,38 +61,18 @@ function toBlock(comment?: TypeDoc.Comment): string {
   );
 }
 
-// https://stackoverflow.com/a/6234804/6897682
-function escapeHtml(unsafe: string): string {
-  return unsafe
-    .replace(/&/g, '&amp;')
-    .replace(/</g, '&lt;')
-    .replace(/>/g, '&gt;')
-    .replace(/"/g, '&quot;')
-    .replace(/'/g, '&#039;');
-}
-
-function parameterRow(
-  name: string,
-  type?: string,
-  def?: string,
-  comment?: TypeDoc.Comment
-): string {
-  def = def ? `<code>${def}</code>` : '';
-  return `<tr>
-  <td>${escapeHtml(name)}</td>
-  <td>${escapeHtml(type)}</td>
-  <td>${def}</td>
-  <td>
-
-::: v-pre
-
-${toBlock(comment)}
-
-:::
-
-  </td>
-</tr>
-`;
+function mdToHtml(md: string): string {
+  const rawHtml = markdown.render(md);
+  const safeHtml: string = sanitizeHtml(rawHtml, htmlSanitizeOptions);
+  // Revert some escaped characters for comparison.
+  if (rawHtml.replace(/&gt;/g, '>') === safeHtml.replace(/&gt;/g, '>')) {
+    return safeHtml;
+  } else {
+    console.debug('Rejected unsafe md:', md);
+    console.error('Rejected unsafe html:', rawHtml.replace(/&gt;/g, '>'));
+    console.error('Expected safe html:', safeHtml.replace(/&gt;/g, '>'));
+    throw new Error('Found unsafe html');
+  }
 }
 
 async function build(): Promise<void> {
@@ -99,24 +120,12 @@ async function build(): Promise<void> {
       link: `/api/${lowerModuleName}.html`,
     });
 
-    let content = `
-      # ${moduleName}
-
-      <!-- This file is automatically generated. -->
-      <!-- Run '${scriptCommand}' to update -->
-
-      ::: v-pre
-
-      ${toBlock(module.comment)}
-
-      :::
-
-      `.replace(/\n +/g, '\n');
-
-    const methods = module.getChildrenByKind(TypeDoc.ReflectionKind.Method);
+    const methods: Method[] = [];
 
     // Generate method section
-    for (const method of methods) {
+    for (const method of module.getChildrenByKind(
+      TypeDoc.ReflectionKind.Method
+    )) {
       const methodName = method.name;
       const prettyMethodName =
         methodName.substring(0, 1).toUpperCase() +
@@ -124,95 +133,64 @@ async function build(): Promise<void> {
       console.debug(`- method ${prettyMethodName}`);
       const signature = method.signatures[0];
 
-      content += `
-        ## ${prettyMethodName}
+      const parameters: MethodParameter[] = [];
 
-        ::: v-pre
-
-        ${toBlock(signature.comment)}
-
-        :::
-
-        `.replace(/\n +/g, '\n');
-
-      // Generate parameter section
+      // Collect Type Parameters
       const typeParameters = signature.typeParameters || [];
-      const parameters = signature.parameters || [];
       const signatureTypeParameters: string[] = [];
-      const signatureParameters: string[] = [];
-      let requiresArgs = false;
-      if (typeParameters.length !== 0 || parameters.length !== 0) {
-        content += `**Parameters**
-
-<table>
-  <thead>
-    <tr>
-      <th>Name</th>
-      <th>Type</th>
-      <th>Default</th>
-      <th>Description</th>
-    </tr>
-  </thead>
-  <tbody>
-`;
-
-        // typeParameters
-        typeParameters.forEach((parameter) => {
-          const parameterName = parameter.name;
-
-          signatureTypeParameters.push(parameterName);
-          content += parameterRow(
-            `<${parameterName}>`,
-            '',
-            '',
-            parameter.comment
-          );
+      for (const parameter of typeParameters) {
+        signatureTypeParameters.push(parameter.name);
+        parameters.push({
+          name: parameter.name,
+          description: mdToHtml(toBlock(parameter.comment)),
         });
+      }
 
-        // parameters
-        parameters.forEach((parameter, index) => {
-          const parameterDefault = parameter.defaultValue;
-          const parameterRequired = typeof parameterDefault === 'undefined';
-          if (index == 0) {
-            requiresArgs = parameterRequired;
-          }
-          const parameterName = parameter.name + (parameterRequired ? '?' : '');
-          const parameterType = parameter.type.toString();
+      // Collect Parameters
+      const signatureParameters: string[] = [];
+      let requiresArgs = false;
+      for (
+        let index = 0;
+        signature.parameters && index < signature.parameters.length;
+        index++
+      ) {
+        const parameter = signature.parameters[index];
+
+        const parameterDefault = parameter.defaultValue;
+        const parameterRequired = typeof parameterDefault === 'undefined';
+        if (index === 0) {
+          requiresArgs = parameterRequired;
+        }
+        const parameterName = parameter.name + (parameterRequired ? '?' : '');
+        const parameterType = parameter.type.toString();
 
-          let parameterDefaultSignatureText = '';
-          if (!parameterRequired) {
-            parameterDefaultSignatureText = ' = ' + parameterDefault;
-          }
+        let parameterDefaultSignatureText = '';
+        if (!parameterRequired) {
+          parameterDefaultSignatureText = ' = ' + parameterDefault;
+        }
 
-          signatureParameters.push(
-            parameterName + ': ' + parameterType + parameterDefaultSignatureText
-          );
-          content += parameterRow(
-            parameterName,
-            parameterType,
-            parameterDefault,
-            parameter.comment
-          );
+        signatureParameters.push(
+          parameterName + ': ' + parameterType + parameterDefaultSignatureText
+        );
+        parameters.push({
+          name: parameter.name,
+          type: parameterType,
+          default: parameterDefault,
+          description: mdToHtml(toBlock(parameter.comment)),
         });
-
-        content += `  </tbody>
-</table>
-
-`;
       }
-      content += '**Returns:** ' + signature.type.toString() + '\n\n';
 
       // Generate usage section
 
-      content += '````ts\n';
-
-      let signatureTypeParametersString = signatureTypeParameters.join(', ');
-      if (signatureTypeParametersString.length !== 0) {
-        signatureTypeParametersString = `<${signatureTypeParametersString}>`;
+      let signatureTypeParametersString = '';
+      if (signatureTypeParameters.length !== 0) {
+        signatureTypeParametersString = `<${signatureTypeParameters.join(
+          ', '
+        )}>`;
       }
       const signatureParametersString = signatureParameters.join(', ');
 
-      content += `faker.${lowerModuleName}.${methodName}${signatureTypeParametersString}(${signatureParametersString}): ${signature.type.toString()}\n`;
+      let examples = `faker.${lowerModuleName}.${methodName}${signatureTypeParametersString}(${signatureParametersString}): ${signature.type.toString()}\n`;
       faker.seed(0);
       if (!requiresArgs) {
         try {
@@ -221,34 +199,72 @@ async function build(): Promise<void> {
             example = example.substring(0, 47) + '...';
           }
 
-          content += `faker.${lowerModuleName}.${methodName}()`;
-          content += (example ? ` // => ${example}` : '') + '\n';
+          examples += `faker.${lowerModuleName}.${methodName}()`;
+          examples += (example ? ` // => ${example}` : '') + '\n';
         } catch (error) {
           // Ignore the error => hide the example call + result.
         }
       }
-      const examples =
+      const exampleTags =
         signature?.comment?.tags
           .filter((tag) => tag.tagName === 'example')
           .map((tag) => tag.text.trimEnd()) || [];
 
-      if (examples.length !== 0) {
-        content += examples.join('\n').trim() + '\n';
+      if (exampleTags.length > 0) {
+        examples += exampleTags.join('\n').trim() + '\n';
       }
 
-      content += '````\n\n';
+      methods.push({
+        name: prettyMethodName,
+        description: mdToHtml(toBlock(signature.comment)),
+        parameters: parameters,
+        returns: signature.type.toString(),
+        examples: mdToHtml('```ts\n' + examples + '```'),
+      });
     }
 
-    // Format md
+    // Write api docs page
+    let content = `
+      <script setup>
+      import ApiDocsMethod from '../.vitepress/components/api-docs/method.vue'
+      import { ${lowerModuleName} } from './${lowerModuleName}'
+      import { ref } from 'vue';
+
+      const methods = ref(${lowerModuleName});
+      </script>
 
-    content = format(content, {
-      ...options,
-      parser: 'markdown',
-    });
+      # ${moduleName}
+
+      <!-- This file is automatically generated. -->
+      <!-- Run '${scriptCommand}' to update -->
+
+      ::: v-pre
+
+      ${toBlock(module.comment)}
+
+      :::
 
-    // Write to disk
+      <ApiDocsMethod v-for="method of methods" v-bind:key="method.name" :method="method" v-once />
+      `.replace(/\n +/g, '\n');
+
+    content = format(content, prettierMarkdown);
 
     writeFileSync(resolve(pathOutputDir, lowerModuleName + '.md'), content);
+
+    // Write api docs data
+
+    let contentTs = `
+    import type { Method } from '../.vitepress/components/api-docs/method';
+
+    export const ${lowerModuleName}: Method[] = ${JSON.stringify(
+      methods,
+      null,
+      2
+    )}`;
+
+    contentTs = format(contentTs, prettierTypescript);
+
+    writeFileSync(resolve(pathOutputDir, lowerModuleName + '.ts'), contentTs);
   }
 
   // Write api-pages.mjs
@@ -260,10 +276,7 @@ async function build(): Promise<void> {
     export const apiPages = ${JSON.stringify(modulesPages)};
     `.replace(/\n +/, '\n');
 
-  apiPagesContent = format(apiPagesContent, {
-    ...options,
-    parser: 'babel',
-  });
+  apiPagesContent = format(apiPagesContent, prettierBabel);
 
   writeFileSync(pathDocsApiPages, apiPagesContent);
 }
diff --git a/src/random.ts b/src/random.ts
index 914e7c2b..d9096d71 100644
--- a/src/random.ts
+++ b/src/random.ts
@@ -304,7 +304,7 @@ export class Random {
   /**
    * alpha. returns lower/upper alpha characters based count and upcase options
    *
-   * @param options // defaults to { count: 1, upcase: false, bannedChars: [] }
+   * @param options Defaults to `{ count: 1, upcase: false, bannedChars: [] }`.
    */
   // TODO @Shinigami92 2022-02-14: Tests covered `(count, options)`, but they were never typed like that
   alpha(
@@ -375,7 +375,7 @@ export class Random {
    * alphaNumeric
    *
    * @param count defaults to 1
-   * @param options // defaults to { bannedChars: [] }
+   * @param options Defaults to `{ bannedChars: [] }`.
    * @param options.bannedChars array of characters which should be banned in new string
    */
   alphaNumeric(