vuepress-markdown-it-wikilink

Wikimedia-style links for VuePress using the markdown-it parser.

This plugin is intended to be used together with VuePress. If you are looking for a plugin to use for markdown-it only, please resolve to: kwvanderlinde/markdown-it-wikilinks.

Installation

Install this inside your VuePress project folder:

# with yarn 
yarn add vuepress-markdown-it-wikilink
 
# with npm 
npm i vuepress-markdown-it-wikilink

And in your VuePress configuration file (most often in docs/.vuepress/config.js):

const wikilinks = require('vuepress-markdown-it-wikilink')({
  // ... options here ...
})
 
module.exports = {
  // ...
  markdown: {
    extendMarkdown: (md) => {
      md.use(wikilinks)
    },
  },
  // ...
}

Options

Options here defined will render as expected inside VuePress. Only the <a></a> tags are converted to <router-link></router-link> and hrefs are converted in format: to="href".

Option	Default value	Note	Example
`baseURL`	`/`	The base URL for absolute wiki links.	#baseurl
`relativeBaseURL`	`/`	The base URL for relative wiki links.	#relativeBaseURL
`makeAllLinksAbsolute`	false	Render all wiki links as absolute links.
`uriSuffix`	`.html`	Append this suffix to every URL.	#uriSuffix
`htmlAttributes`	`{ class: 'wikilinks' }`	An object containing HTML attributes to be applied to every link.	#htmlAttributes
`generatePageNameFromLabel`		Provide a custom page name generator.	#generatePageNameFromLabel
`postProcessPageName`		A transform applied to every page name.	#postProcessPageName
`postProcessLabel`		A transform applied to every link label.	#postProcessLabel

`baseURL`

const html = require('markdown-it')()
  .use(require('vuepress-markdown-it-wikilink')({ baseURL: '/wiki/' }))
  .render('[[Main Page]]')
// <p><router-link to="./wiki/Main_Page.html">Main Page</router-link></p>

`relativeBaseURL`

const html = require('markdown-it')()
  .use(require('vuepress-markdown-it-wikilink')({ relativeBaseURL: '#', suffix: '' }))
  .render('[[Main Page]]')
// <p><router-link to="#Main_Page">Main Page</router-link></p>

`uriSuffix`

const html = require('markdown-it')()
  .use(require('vuepress-markdown-it-wikilink')({ uriSuffix: '.php' }))
  .render('[[Main Page]]')
// <p><router-link to="./Main_Page.php">Main Page</router-link></p>

`htmlAttributes`

const attrs = {
  class: 'wikilink',
  rel: 'nofollow',
}
const html = require('markdown-it')()
  .use(require('vuepress-markdown-it-wikilink')({ htmlAttributes: attrs }))
  .render('[[Main Page]]')
// <p><router-link to="./Main_Page.html" class="wikilink" rel="nofollow">Main Page</router-link></p>

`generatePageNameFromLabel`

Unless otherwise specified, the labels of the links are used as the targets. This means that a non-piped link such as [[Slate]] will point to the Slate page on your website. But say you wanted a little more flexibility - like being able to have [[Slate]], [[slate]], [[SLATE]] and [[Slate!]] to all point to the same page. Well, you can do this by providing your own custom generatePageNameFromLabel function.

Example

const _ = require('lodash')
 
function myCustomPageNameGenerator(label) {
  return label.split('/').map(function (pathSegment) {
    // clean up unwanted characters, normalize case and capitalize the first letter
    pathSegment = _.deburr(pathSegment)
    pathSegment = pathSegment.replace(/[^\w\s]/g, '')
 
    // normalize case
    pathSegment = _.capitalize(pathSegment.toLowerCase())
 
    return pathSegment
  })
}
 
const html = require('markdown-it')()
  .use(
    require('vuepress-markdown-it-wikilink')({
      generatePageNameFromLabel: myCustomPageNameGenerator,
    })
  )
  .render('Vive la [[révolution!]] VIVE LA [[RÉVOLUTION!!!]]')
// <p>Vive la <router-link to="./Revolution.html">révolution!</router-link> VIVE LA <router-link to="./Revolution.html">RÉVOLUTION!!!</router-link></p>

Please note that the generatePageNameFromLabel function does not get applied for piped links such as [[/Misc/Cats/Slate|kitty]] since those already come with a target.

`postProcessPageName`

A transform applied to every page name. You can override it just like generatePageNameFromLabel (see above). The default transform does the following things:

trim surrounding whitespace
sanitize the string
replace spaces with underscores

`postProcessLabel`

A transform applied to every link label. You can override it just like generatePageNameFromLabel (see above). All the default transform does is trim surrounding whitespace.

Credits

Based on markdown-it-ins by Vitaly Puzrin, Alex Kocharin. Some adjustments are applied according to this fork: ceilfors/markdown-it-wikilinks.

Authored and maintained by Spencer Woo.

@Portfolio · @Blog · @GitHub