Markdown-it-Wikilinks-Plus — MediaWiki/Obsidian‑style [[WikiLinks]] for markdown‑it

Maintained fork. Turn [[double bracket links]] into regular HTML anchors when rendering Markdown with markdown‑it. Works for [[Page]], [[/Path/Page]], [[Page#Section]], and [[Page|Label]]. Great for Markdown wikis, VitePress/VuePress docs, Zettelkasten/PKM workflows, and Obsidian‑style notes.

Why this fork? The original repo is inactive; this fork is maintained with clearer docs, examples, and test coverage.

Usage

Install this into your project:

npm --save install markdown-it-wikilinks-plus

...and use it:

const wikilinks = require('markdown-it-wikilinks-plus')(options)
const md = require('markdown-it')()
          .use(wikilinks)
const html = md.render('Click [[Wiki Links|here]] to learn about [[/Wiki]] links.')

Output:

<p>Click <a href="./Wiki_Links.html">here</a> to learn about <a href="/Wiki.html">Wiki</a> links.</p>

It works with spaces and anchors too:

Input:

const md = require('markdown-it')()
           .use(wikilinks)
const html = md.render('[[Feline hypercuteness#Signs and symptoms]]')

Output:

<p><a href="./Feline_hypercuteness.html#Signs_and_symptoms">Feline hypercuteness</a> with anchor</p>

Options

baseURL

Default: /

The base URL for absolute wiki links.

const html = require('markdown-it')()
  .use(require('markdown-it-wikilinks-plus')({ baseURL: '/wiki/' }))
  .render('[[/Main Page]]')
  // <p><a href="/wiki/Main_Page.html">Main Page</a></p>

relativeBaseURL

Default: ./

The base URL for relative wiki links.

const html = require('markdown-it')()
  .use(require('markdown-it-wikilinks-plus')({ relativeBaseURL: '#', suffix: '' }))
  .render('[[Main Page]]')
  // <p><a href="#Main_Page">Main Page</a></p>

makeAllLinksAbsolute

Default: false

Render all wiki links as absolute links.

uriSuffix

Default: .html

Append this suffix to every URL.

const html = require('markdown-it')()
  .use(require('markdown-it-wikilinks-plus')({ uriSuffix: '.php' }))
  .render('[[Main Page]]')
  // <p><a href="./Main_Page.php">Main Page</a></p>

htmlAttributes

Default: {}

An object containing HTML attributes to be applied to every link.

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

generatePagePathFromLabel

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 generatePagePathFromLabel function.

Example

const _ = require('lodash')

function myCustomPagePathGenerator(label) {
  // clean up unwanted characters, normalize case and capitalize the first letter
  label = _.deburr(label)
  label = label.replace(/[^\w\s]/g, '')

  // normalize case
  label = _.capitalize(label.toLowerCase())

  return label
}

const html = require('markdown-it')()
  .use(require('markdown-it-wikilinks-plus')({ generatePagePathFromLabel: myCustomPagePathGenerator }))
  .render('Vive la [[révolution!]] VIVE LA [[RÉVOLUTION!!!]]')
  // <p>Vive la <a href="./Revolution.html">révolution!</a> VIVE LA <a href="./Revolution.html">RÉVOLUTION!!!</a></p>

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

postProcessPagePath

A transform applied to every page name. You can override it just like generatePagePathFromLabel (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 generatePagePathFromLabel (see above).

All the default transform does is trim surrounding whitespace.

stripHashFromLabel

Removes the #hash part of labels in direct wikilinks ([[page]]). Does not run on piped links ([[page|label]]).

Framework recipes

VitePress

// .vitepress/config.mjs
import { defineConfig } from 'vitepress'
export default defineConfig({
  markdown: {
    async config(md) {
      const wikilinks = (await import('@rgruner/markdown-it-wikilinks')).default
      md.use(wikilinks({ baseURL: '/wiki/' }))
    }
  }
})

VuePress (v2)

// .vuepress/config.js
const wikilinks = require('@rgruner/markdown-it-wikilinks')
module.exports = {
  markdown: { config: (md) => md.use(wikilinks({ baseURL: '/wiki/' })) }
}

Compatibility

• Node 16+ (tested in both ESM and CJS runtimes)
• markdown‑it ^13
• Works with VitePress and VuePress out of the box via their markdown‑it hooks

Migration from other forks

For basic usage, no code changes are needed—swap the package name to this fork. If you relied on undocumented behavior in other forks, see the Options section above.

FAQ

Does it support Obsidian‑style links? Yes—[[Page]], [[Page#Section]], and [[Page|Label]] work out of the box.

Can I remove the .html suffix? Set uriSuffix: ''.

How do I open links in a new tab? Use htmlAttributes: { target: '_blank', rel: 'noopener' }.

Can I generate pretty slugs? Provide generatePagePathFromLabel and/or postProcessPagePath to map labels to your site’s routing.

Contributing

PRs and issues welcome. Please include tests where possible. Run tests with npm test.

License

MIT

Credits

Based on markdown-it-ins by Vitaly Puzrin, Alex Kocharin.

Uses a fork of reurl by Alwin Blok.

Alternatives

• markdown-it-wikilinks (unscoped, original package)
• @ig3/markdown-it-wikilinks (scoped fork)
• @binyamin/markdown-it-wikilinks (different API/behavior)

Choose this fork if you need an actively maintained option with modern examples and recipes.