markdown-it-internal-link

Internal links plugin for markdown-it markdown parser.

Use this plugin to parse and render [[internal links]] (also called wikilinks or roamlinks).

Install

Node:

npm install --save markdown-it-internal-link

Usage

Node:

const md = require("markdown-it")();
const internalLink = require("markdown-it-internal-link");

md.use(internalLink, options);

Browser:

const md = window.markdownit();

md.use(window.markdownItInternalLink, options);

By default, all [[bracketed]] links are converted to <a href="bracketed">bracketed</a>. To override this behavior, specify the options parameter as either an object or a function.

Options

If options is an object, the plugin uses its properties to make the HTML attributes of the <a> element, except options.text used for the inner text. All the properties can be given as strings, or functions ((content: string, env: any) => string). The content argument is a string corresponding to the text inside double-brackets. The env argument is the environment object passed to markdown-it before rendering.

Example:

md.use(internalLink, {
    // add a class attribute
    class: "my-link",

    // add a title attribute
    title: "click me",

    // override the inner text
    text: (content) => content.toUpperCase()
});

md.render("[[foo]]");
// => `<a class="my-link" href="foo" title="click me">FOO</a>`

If options is a function, it must have the signature (content: string, env: any) => (object | string). This function can return an object with a structure similar to the previous example. For example, how to render wikilinks with optional label (piped links):

md.use(internalLink, (content) => {
    // search for the pipe character
    const pos = content.indexOf("|");

    return {
        // add a class attribute
        class: "wikilink",

        // override the href attribute
        href: pos === -1 ? content : content.substring(0, pos),

        // override the inner text
        text: pos === -1 ? content : content.substring(pos + 1)
    };
});

md.render("[[foo]]"); // => `<a class="wikilink" href="foo">foo</a>`

md.render("[[foo|bar]]"); // => `<a class="wikilink" href="foo">bar</a>`

To fully control the rendering, the function can return a string instead.

The following example converts internal links to <button> elements:

md.use(internalLink, (content) => `<button>${content}</button>`);

md.render("[[foo]]"); // => `<button>foo</button>`

One can also use the env parameter to specify a per-render context.

The following example collects all the internal links of the document:

md.use(internalLink, (content, env) => env.internalLinks.push(content));

const env = { internalLinks: [] };

md.render("[[foo]] and [[bar]]", env);
// => `<a href="foo">foo</a> and <a href="bar">bar</a>`

console.log(env.internalLinks); // => ["foo", "bar"]

License

This software is licensed under the MIT license. Please see the LICENSE file for further information.