From 3165ccd68343fe86f3913c71de2738fd7f9bf6a1 Mon Sep 17 00:00:00 2001
From: stfsy <s.pfaffel@gmail.com>
Date: Thu, 6 Jan 2022 14:11:20 +0100
Subject: [PATCH] chore: use markdown plugin to normalize headlines and anchors

---
 docs/.vuepress/config.js | 55 ++++++++++++++++++++++++++++++++++------
 package-lock.json        | 21 +++++++++++++++
 package.json             |  2 ++
 templates/parameters.def |  6 ++---
 templates/responses.def  |  4 +--
 5 files changed, 75 insertions(+), 13 deletions(-)

diff --git a/docs/.vuepress/config.js b/docs/.vuepress/config.js
index 0ac2f41..833a180 100644
--- a/docs/.vuepress/config.js
+++ b/docs/.vuepress/config.js
@@ -1,16 +1,55 @@
-/**
- * @typedef {import('@vuepress/theme-default').NavbarConfig} NavbarConfig
- */
+const anchorPlugin = require('markdown-it-anchor')
+
+// eslint-disable-next-line no-control-regex
+const rControl = /[\u0000-\u001f]/g
+const rSpecial = /[\s~`!@#$%^&*()\-_+=[\]{}|\\;:"'“”‘’<>,.?/]+/g
+const rCombining = /[\u0300-\u036F]/g
+
+const slugify = (str) => {
+    return str
+        .normalize('NFKD')
+        // Remove accents
+        .replace(rCombining, '')
+        // Remove control characters
+        .replace(rControl, '')
+        // Replace special characters
+        .replace(rSpecial, '-')
+        // Remove continuos separators
+        .replace(/-{2,}/g, '-')
+        // Remove prefixing and trailing separators
+        .replace(/^-+|-+$/g, '')
+        // ensure it doesn't start with a number (#121)
+        .replace(/^(\d)/, '_$1')
+        // lowercase
+        .toLowerCase()
+}
 
-/**
- * @type NavbarConfig
- */
 module.exports = {
     // site config
     lang: 'en-US',
     title: 'discue',
-    description: 'Documentation of discue.io: Your secure and reliable messaging and queueing service.',
-    markdown: { extractHeaders: { level: [2, 3, 4] } },
+    extendsMarkdown: (md) => {
+        md.use(require('markdown-it-attrs'), {
+            allowedAttributes: ['id'],
+            leftDelimiter: '[',
+            rightDelimiter: ']',
+            allowedAttributes: []  // empty array = all attributes are allowed
+        })
+        md.use(anchorPlugin, {
+            level: [1, 2, 3, 4, 5, 6],
+            slugify,
+            permalink: anchorPlugin.permalink.ariaHidden({
+                class: 'header-anchor',
+                symbol: '#',
+                space: true,
+                placement: 'before',
+            }),
+        })
+    },
+    markdown: {
+        extractHeaders: { level: [2, 3, 4, 5, 6] },
+        anchor: false
+    },
     // theme and its config
     theme: '@vuepress/theme-default',
     themeConfig: {
diff --git a/package-lock.json b/package-lock.json
index 4f0da4f..7ede0a6 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -9,6 +9,8 @@
       "version": "0.1.0",
       "license": "MIT",
       "devDependencies": {
+        "markdown-it-anchor": "^8.4.1",
+        "markdown-it-attrs": "^4.1.3",
         "nodemon": "^2.0.15",
         "postcss": "^8.4.12",
         "postcss-cli": "^9.1.0",
@@ -3975,6 +3977,18 @@
         "markdown-it": "*"
       }
     },
+    "node_modules/markdown-it-attrs": {
+      "version": "4.1.3",
+      "resolved": "https://registry.npmjs.org/markdown-it-attrs/-/markdown-it-attrs-4.1.3.tgz",
+      "integrity": "sha512-d5yg/lzQV2KFI/4LPsZQB3uxQrf0/l2/RnMPCPm4lYLOZUSmFlpPccyojnzaHkfQpAD8wBHfnfUW0aMhpKOS2g==",
+      "dev": true,
+      "engines": {
+        "node": ">=6"
+      },
+      "peerDependencies": {
+        "markdown-it": ">= 9.0.0 < 13.0.0"
+      }
+    },
     "node_modules/markdown-it-container": {
       "version": "3.0.0",
       "resolved": "https://registry.npmjs.org/markdown-it-container/-/markdown-it-container-3.0.0.tgz",
@@ -9594,6 +9608,13 @@
       "dev": true,
       "requires": {}
     },
+    "markdown-it-attrs": {
+      "version": "4.1.3",
+      "resolved": "https://registry.npmjs.org/markdown-it-attrs/-/markdown-it-attrs-4.1.3.tgz",
+      "integrity": "sha512-d5yg/lzQV2KFI/4LPsZQB3uxQrf0/l2/RnMPCPm4lYLOZUSmFlpPccyojnzaHkfQpAD8wBHfnfUW0aMhpKOS2g==",
+      "dev": true,
+      "requires": {}
+    },
     "markdown-it-container": {
       "version": "3.0.0",
       "resolved": "https://registry.npmjs.org/markdown-it-container/-/markdown-it-container-3.0.0.tgz",
diff --git a/package.json b/package.json
index 9837d63..fefc39f 100644
--- a/package.json
+++ b/package.json
@@ -13,6 +13,8 @@
   "author": "Stefan Pfaffel",
   "license": "MIT",
   "devDependencies": {
+    "markdown-it-anchor": "^8.4.1",
+    "markdown-it-attrs": "^4.1.3",
     "nodemon": "^2.0.15",
     "postcss": "^8.4.12",
     "postcss-cli": "^9.1.0",
diff --git a/templates/parameters.def b/templates/parameters.def
index 8df3b31..f077d39 100644
--- a/templates/parameters.def
+++ b/templates/parameters.def
@@ -1,5 +1,5 @@
 {{= data.tags.section }}
-<h3 id="{{=data.operationUniqueSlug}}-parameters">Parameters</h3>
+##### Parameters [#{{=data.method.verb}}-{{=data.normalizedPath}}-parameters]
 
 |Name|In|Type|Required|Description|
 |---|---|---|---|---|
@@ -7,7 +7,7 @@
 {{~}}
 
 {{? data.longDescs }}
-#### Detailed descriptions
+###### Descriptions [#{{=data.method.verb}}-{{=data.normalizedPath}}-parameter-descriptions]
 {{~ data.parameters :p}}{{? p.shortDesc !== p.description}}
 **{{=p.name}}**: {{=p.description}}{{?}}
 {{~}}
@@ -30,7 +30,7 @@
 {{~}}
 
 {{? data.enums && data.enums.length }}
-#### Enumerated Values
+##### Enumerated Values [#{{=data.method.verb}}-{{=data.normalizedPath}}-enums]
 
 |Parameter|Value|
 |---|---|
diff --git a/templates/responses.def b/templates/responses.def
index 6a9846b..03842ce 100644
--- a/templates/responses.def
+++ b/templates/responses.def
@@ -5,7 +5,7 @@
 {{~}}
 
 {{? data.responseSchemas }}
-<h3 id="{{=data.operationUniqueSlug}}-responses">Responses</h3>
+##### Responses [#{{=data.method.verb}}-{{=data.normalizedPath}}-responses]
 
 {{= data.utils.getResponseExamples(data) }}
 {{?}}
@@ -67,7 +67,7 @@ Status Code **{{=response.status}}**
 {{ data.responseHeaders = data.utils.getResponseHeaders(data); }}
 {{? data.responseHeaders.length }}
 
-### Response Headers
+##### Response Headers [#{{=data.method.verb}}-{{=data.normalizedPath}}-response-headers]
 
 |Status|Header|Type|Format|Description|
 |---|---|---|---|---|