Skip to content

Commit

Permalink
chore: use markdown plugin to normalize headlines and anchors
Browse files Browse the repository at this point in the history
  • Loading branch information
stfsy committed Apr 26, 2022
1 parent a89db85 commit 3165ccd
Show file tree
Hide file tree
Showing 5 changed files with 75 additions and 13 deletions.
55 changes: 47 additions & 8 deletions docs/.vuepress/config.js
Original file line number Diff line number Diff line change
@@ -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: {
Expand Down
21 changes: 21 additions & 0 deletions package-lock.json

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

2 changes: 2 additions & 0 deletions package.json
Original file line number Diff line number Diff line change
Expand Up @@ -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",
Expand Down
6 changes: 3 additions & 3 deletions templates/parameters.def
Original file line number Diff line number Diff line change
@@ -1,13 +1,13 @@
{{= data.tags.section }}
<h3 id="{{=data.operationUniqueSlug}}-parameters">Parameters</h3>
##### Parameters [#{{=data.method.verb}}-{{=data.normalizedPath}}-parameters]

|Name|In|Type|Required|Description|
|---|---|---|---|---|
{{~ data.parameters :p}}|{{=p.name}}|{{=p.in}}|{{=p.safeType}}|{{? p.required === true }}✔{{?? }} ❌ {{? }}|{{=p.shortDesc || 'none'}}|
{{~}}

{{? data.longDescs }}
#### Detailed descriptions
###### Descriptions [#{{=data.method.verb}}-{{=data.normalizedPath}}-parameter-descriptions]
{{~ data.parameters :p}}{{? p.shortDesc !== p.description}}
**{{=p.name}}**: {{=p.description}}{{?}}
{{~}}
Expand All @@ -30,7 +30,7 @@
{{~}}

{{? data.enums && data.enums.length }}
#### Enumerated Values
##### Enumerated Values [#{{=data.method.verb}}-{{=data.normalizedPath}}-enums]

|Parameter|Value|
|---|---|
Expand Down
4 changes: 2 additions & 2 deletions templates/responses.def
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@
{{~}}

{{? data.responseSchemas }}
<h3 id="{{=data.operationUniqueSlug}}-responses">Responses</h3>
##### Responses [#{{=data.method.verb}}-{{=data.normalizedPath}}-responses]

{{= data.utils.getResponseExamples(data) }}
{{?}}
Expand Down Expand Up @@ -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|
|---|---|---|---|---|
Expand Down

0 comments on commit 3165ccd

Please sign in to comment.