@braindb/mdast-util-wiki-link

fork of https://github.com/landakram/mdast-util-wiki-link

Extension for mdast-util-from-markdown and mdast-util-to-markdown to support [[Wiki Links]].

• Parse wiki-style links and render them as anchors
• Differentiate between "new" and "existing" wiki links by giving the parser a list of existing permalinks
• Parse aliased wiki links i.e [[Real Page|Page Alias]]

Using remark? You might want to use @braindb/remark-wiki-link instead of using this package directly.

Usage

Markdown to AST

import fromMarkdown from "mdast-util-from-markdown";
import { syntax } from "@braindb/micromark-extension-wiki-link";
import * as wikiLink from "@braindb/mdast-util-wiki-link";

let ast = fromMarkdown("[[Test Page]]", {
  extensions: [syntax()],
  mdastExtensions: [wikiLink.fromMarkdown()],
});

The AST node will look like this:

{
    value: 'Test Page',
    data: {
        alias: 'Test Page',
        permalink: 'Test Page',
        hName: 'a',
        hProperties: {
            href: 'Test Page',
        },
        hChildren: [{
            type: 'text',
            value: 'Test Page'
        }]
    }
}

• value: slug of the page
• data.alias: The display name for this link
• data.permalink: The permalink for this page. This permalink is computed from node.value using options.linkResolver, which can be passed in when initializing the plugin.
• data.hProperties.href: href value for the rendered a. This href is computed using options.hrefTemplate.

The hName and other h fields provide compatibility with rehype.

AST to Markdown

Taking the ast from the prior example, let's go back to markdown:

import { fromMarkdown } from "mdast-util-from-markdown";
import * as wikiLink from "@braindb/mdast-util-wiki-link";

let markdownString = toMarkdown(ast, {
  extensions: [wikiLink.toMarkdown()],
}).trim();
console.log(markdownString);
// [[Wiki Link]]

Configuration options

Both fromMarkdown and toMarkdown accept configuration as an object.

For example, one may configure fromMarkdown like so:

let ast = fromMarkdown("[[Test Page]]", {
  extensions: [syntax()],
  mdastExtensions: [
    wikiLink.fromMarkdown({
      linkResolver: (x) => name.replace(/ /g, "_").toLowerCase(),
    }),
  ], // <--
});

fromMarkdown

• options.linkResolver (pageName: string) -> string: A function that maps a page name to an array of possible permalinks. These possible permalinks are cross-referenced with options.permalinks to determine whether a page exists. If a page doesn't exist, the first element of the array is considered the permalink.

  The default linkResolver is:

  (name) => name;

• options.linkTemplate ({ slug: string, permalink: string, alias: string | null }) -> HAST: A function that generates "HAST" for link.

  The default linkTemplate is:

  function defaultLinkTemplate({ slug, permalink, alias }) {
    return {
      hName: "a",
      hProperties: { href: permalink == null ? slug : permalink },
      hChildren: [{ type: "text", value: alias == null ? slug : alias }],
    };
  }

toMarkdown

• options.aliasDivider string: a string to be used as the divider for aliases. See the section below on Aliasing pages. Defaults to "|".

Aliasing pages

Aliased pages are supported with the following markdown syntax:

[[Real Page|Page Alias]]

And will produce this HTML when rendered:

<a href="Real Page">Page Alias</a>