markdown-it-wikilinks-plus/README.md

WikiMedia-style links for the markdown-it parser

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

![NPM markdown-it-wikilinks-plus](https://img.shields.io/npm/v/markdown-it-wikilinks-plus.svg) [![Build Status](https://travis-ci.org/rgruner/markdown-it-wikilinks-plus.svg?branch=master)](https://travis-ci.org/rgruner/markdown-it-wikilinks-plus) [![Coverage Status](https://coveralls.io/repos/github/rgruner/markdown-it-wikilinks-plus/badge.svg?branch=master)](https://coveralls.io/github/rgruner/markdown-it-wikilinks-plus?branch=master)


**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:

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

...and *use* it:

```js
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:**

```html
<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:**

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

**Output:**

```html
<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.

```js
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.

```js
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.

```js
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.

```js
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](https://meta.wikimedia.org/wiki/Help:Piped_link) 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

```js
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](https://meta.wikimedia.org/wiki/Help:Piped_link) 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](https://github.com/parshap/node-sanitize-filename) 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

```js
// .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)

```js
// .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](https://github.com/markdown-it/markdown-it-ins) by Vitaly Puzrin, Alex Kocharin.

Uses a fork of [reurl](https://github.com/alwinb/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.