mdast-util-wikirefs

Extension for mdast-util-from-markdown and mdast-util-to-markdown to support wikirefs (including [[wikilinks]]). Converts the token stream produced by micromark-extension-wikirefs into an abstract syntax tree.

Note that this plugin only parses the input -- it is up to you to assign appropriate linking information and/or index relationships between files.

Using remark? You probably shouldn’t use this package directly, but instead use remark-wikirefs. See wikirefs-spec for a full description of the supported syntax.

🕸 Weave a semantic web in your 🎋 WikiBonsai digital garden.

Install

This package is ESM only. Install mdast-util-wikirefs on npm.

npm install mdast-util-wikirefs

Use

Markdown to AST

WikiRefs (MKDN -> AST)

To use all wiki constructs, use wikirefs:

import fromMarkdown from 'mdast-util-from-markdown'
import { syntaxWikiRefs } from 'micromark-extension-wikirefs'
import { fromMarkdownWikiRefs } from 'mdast-util-wikirefs'

let ast = fromMarkdown('[[fname]]', {
  extensions: [syntaxWikiRefs],
  mdastExtensions: [fromMarkdownWikiRefs]
})

See specific abstract syntax tree node forms below...

WikiAttrs (MKDN -> AST)

The corresponding wikiattr node for...

':attrtype::[[fname]]\n'

...is first converted to a data node which takes the form below:

{
  "type": "attrbox-data",
  "data": {
    "items": {
      "attrtype": [
        {
          "type": "wiki",
          "doctype": "",
          "filename": "fname",
          "htmlHref": "/fname-url",
          "htmlText": "title",
          "baseUrl": "",
        }
      ],
    },
  }
}

Data nodes like this are then extracted after render, are merged, and a single attrbox node is generated and inserted at the top of the document in the abstract syntax tree. It has the form below, where:

• data.items contains the original markdown source parsed into the individual components of the wikiattr.

{
  "type": "attrbox",
  "data": {
    "items": {
      "attrtype": [
        {
          "type": "wiki",
          "doctype": "",
          "filename": "fname",
          "htmlHref": "/fname-url",
          "htmlText": "title",
          "baseUrl": "",
        }
      ],
    },
    "hName": "aside",
    "hProperties": {
      "className": ["attrbox"],
    },
  },
  "children": [{
      "type": "attrbox-title",
      "data": {
        "hName": "span",
        "hProperties": {
          "className": ["attrbox-title"],
        },
      },
      "children": [{
        "type": "text",
        "value": "attrtype",
      }],
    }, {
      "type": "attrbox-list",
      "data": { "hName": "dl" },
      "children": [
        {
          "type": "attr-key",
          "data": { "hName": "dt" },
          "children": [{
            "type": "text",
            "value": "attrtype",
          }],
        }, {
          "type": "attr-val",
          "data": { "hName": "dd" },
          "children": [
            {
              "type": "wikiattr",
              "children": [{
                "type": "text",
                "value": "title",
              }],
              "data": {
                "hName": "a",
                "hProperties": {
                  "className": ["attr", "wiki", "reftype__attrtype"],
                  "dataHref": "/fname-url",
                  "href": "/fname-url",
                },
              }
            },
          ],
        },
      ],
    },
  ],
}

To use only the wikiattr construct:

import fromMarkdown from 'mdast-util-from-markdown';
import { syntaxWikiAttrs } from 'micromark-extension-wikirefs';
import { fromMarkdownWikiAttrs } from 'mdast-util-wikirefs';

let ast = fromMarkdown(':attrtype::[[fname]]\n', {
  extensions: [syntaxWikiAttrs],
  mdastExtensions: [fromMarkdownWikiAttrs]
});

WikiLinks (MKDN -> AST)

The corresponding wikilink node for...

[[fname]]

...in the abstract syntax tree has the form below, where:

• data.item contains the original markdown source parsed into the individual components of the wikilink.

{
  "type": "wikilink",
  "children": [{
    "type": "text",
    "value": "title",
  }],
  "data": {
    "item": {
      "filename": "fname",
      "doctype": "",
      "label": "",
      "linktype": "reftype__linktype",
      "htmlHref": "/fname-url",
      "htmlText": "title",
    },
    "hName": "a",
    "hProperties": {
      "className": ["wiki", "link"],
      "dataHref": "/fname-url",
      "href": "/fname-url",
    },
  }
}

To use only the wikilink construct:

import fromMarkdown from 'mdast-util-from-markdown';
import { syntaxWikiLinks } from 'micromark-extension-wikirefs';
import { fromMarkdownWikiLinks } from 'mdast-util-wikirefs';

let ast = fromMarkdown('[[fname]]', {
  extensions: [syntaxWikiLinks],
  mdastExtensions: [fromMarkdownWikiLinks]
});

WikiEmbeds (MKDN -> AST)

The corresponding wikiembed node for...

![[fname]]
![[audio.mp3]]
![[image.png]]
![[video.mp4]]

...in the abstract syntax tree has the form below, where:

• data.item contains the original markdown source parsed into the individual components of the wikilink.

{
  "type": "wikiembed",
  "data": {
    "item": {
      "doctype": "",
      "filename": "embed-doc",
      "media": "markdown",
      "htmlHref": "/fname-url",
    },
    "hName": "p",
  },
  "children": [{
    "type": "embed-mkdn-wrapper",
    "data": {
      "hName": "div",
      "hProperties": {
        "className": ["embed-wrapper"]
      }
    },
    "children": [{
      "type": "embed-mkdn-title",
      "data": {
        "hName": "div",
        "hProperties": {
          "className": ["embed-title"]
        }
      },
      "children": [{
        "type": "a",
        "data": {
          "hName": "a",
          "hProperties": {
            "className": ["wiki", "embed"],
            "dataHref": "/tests/fixtures/embed-doc",
            "href": "/tests/fixtures/embed-doc",
          }
        },
        "children": [{
          "type": "text",
          "value": "embedded document",
        }]
      }],
    }, {
      "type": "embed-mkdn-link",
      "data": {
        "hName": "div",
        "hProperties": {
          "className": ["embed-link"]
        }
      },
      "children": [{
        "type": "a",
        "data": {
          "hName": "a",
          "hProperties": {
            "className": ["embed-link-icon"],
            "dataHref": "/tests/fixtures/embed-doc",
            "href": "/tests/fixtures/embed-doc",
          }
        },
        "children": [{
          "type": "i",
          "data": {
            "hName": "i",
            "hProperties": {
              "className": ["link-icon"],
            }
          }
        }],
      }],
    }, {
      "type": "embed-mkdn-content",
      "data": {
        "hName": "div",
        "hProperties": {
          "className": ["embed-content"]
        }
      },
      "children": [{
        "type": "root",
        "position": {
          "start": { "column": 1, "line": 1, "offset": 0 },
          "end": { "column": 22, "line": 1, "offset": 21 },
        },
        "children": [{
          "type": "paragraph",
          "position": {
            "start": { "column": 1, "line": 1, "offset": 0 },
            "end": { "column": 22, "line": 1, "offset": 21 },
          },
          "children": [{
            "type": "text",
            "value": "Here is some content.",
            "position": {
              "start": { "column": 1, "line": 1, "offset": 0 },
              "end": { "column": 22, "line": 1, "offset": 21 },
            },
          }]
        }],
      }],
    },],
  }],
},
{
  "type": "wikiembed",
  "data": {
    "item": {
      "doctype": "",
      "filename": "audio.mp3",
      "media": "audio",
      "htmlHref": "/fname-url",
    },
    "hName": "p",
  },
  "children": [{
    "type": "embed-media-span",
    "data": {
      "hName": "span",
      "hProperties": {
        "className": ["embed-media"],
        "src": "audio.mp3",
        "alt": "audio.mp3",
      }
    },
    "children": [{
      "type": "embed-media-audio",
      "data": {
        "hName": "audio",
        "hProperties": {
          "controls": true,
          "className": ["embed-audio"],
          "src": "/tests/fixtures/audio.mp3",
          "type": "audio/mp3",
        }
      }
    }],
  }],
},
{
  "type": "wikiembed",
  "data": {
    "item": {
      "doctype": "",
      "filename": "image.png",
      "media": "image",
      "htmlHref": "/fname-url",
    },
    "hName": "p",
  },
  "children": [{
    "type": "embed-media-span",
    "data": {
      "hName": "span",
      "hProperties": {
        "className": ["embed-media"],
        "src": "image.png",
        "alt": "image.png",
      }
    },
    "children": [{
      "type": "embed-media-image",
      "data": {
        "hName": "img",
        "hProperties": {
          "className": ["embed-image"],
          "src": "/tests/fixtures/image.png",
        }
      }
    }]
  }],
},
{
  "type": "wikiembed",
  "data": {
    "item": {
      "doctype": "",
      "filename": "video.mp4",
      "media": "video",
      "htmlHref": "/fname-url",
    },
    "hName": "p",
  },
  "children": [{
    "type": "embed-media-span",
    "data": {
      "hName": "span",
      "hProperties": {
        "className": ["embed-media"],
        "src": "video.mp4",
        "alt": "video.mp4",
      }
    },
    "children": [{
      "type": "embed-media-video",
      "data": {
        "hName": "video",
        "hProperties": {
          "controls": true,
          "className": ["embed-video"],
          "src": "/tests/fixtures/video.mp4",
          "type": "video/mp4",
        }
      }
    }],
  }],
}

To use only the wikiembed construct:

import fromMarkdown from 'mdast-util-from-markdown';
import { syntaxWikiEmbeds } from 'micromark-extension-wikirefs';
import { fromMarkdownWikiEmbeds } from 'mdast-util-wikirefs';

let ast = fromMarkdown('[[fname]]', {
  extensions: [syntaxWikiEmbeds],
  mdastExtensions: [fromMarkdownWikiEmbeds]
});

AST to Markdown

Taking the asts from the previous example...

WikiRefs (AST -> MKDN)

import fromMarkdown from 'mdast-util-from-markdown'
import { toMarkdownWikiRefs } from 'mdast-util-wikirefs'

let markdownString = toMarkdown(ast, {
  extensions: [toMarkdownWikiRefs]
}).trim();

WikiAttrs (AST -> MKDN)

...result will be:

:attrtype::[[fname]]

To use only the wikiattr construct:

import fromMarkdown from 'mdast-util-from-markdown'
import { toMarkdownWikiAttrs } from 'mdast-util-wikirefs'

let markdownString = toMarkdown(ast, {
  extensions: [toMarkdownWikiAttrs]
}).trim();

WikiLinks (AST -> MKDN)

...result will be:

[[fname]]

To use only the wikilink construct:

import fromMarkdown from 'mdast-util-from-markdown'
import { toMarkdownWikiLinks } from 'mdast-util-wikirefs'

let markdownString = toMarkdown(ast, {
  extensions: [toMarkdownWikiLinks]
}).trim();

WikiEmbeds (AST -> MKDN)

...result will be:

![[fname]]
![[audio.mp3]]
![[image.png]]
![[video.mp4]]

To use only the wikiembed construct:

import fromMarkdown from 'mdast-util-from-markdown'
import { toMarkdownWikiEmbeds } from 'mdast-util-wikirefs'

let markdownString = toMarkdown(ast, {
  extensions: [toMarkdownWikiEmbeds]
}).trim();

Options

mdast Options

Works for both fromMarkdown and toMarkdown:

// defaults
let mdastOpts = {
  attrs: {
    enable: true,
  },
  links: {
    enable: true,
  },
  embeds: {
    enable: true,
  },
};

Options Descriptions

See remark-wikirefs readme for option descriptions.