mdast-util-wikirefs
Version:
Converts a `micromark` token stream into an `mdast` syntax tree.
549 lines (475 loc) • 12.8 kB
Markdown
# `mdast-util-wikirefs`
[](https://github.com/wikibonsai/wikibonsai)
[](https://npmjs.org/package/mdast-util-wikirefs)
Extension for [`mdast-util-from-markdown`](https://github.com/syntax-tree/mdast-util-from-markdown) and
[`mdast-util-to-markdown`](https://github.com/syntax-tree/mdast-util-to-markdown) to support [wikirefs](https://github.com/wikibonsai/wikirefs) (including `[[wikilinks]]`). Converts the token stream produced by [`micromark-extension-wikirefs`](https://github.com/wikibonsai/remark-wikirefs/tree/master/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`](https://github.com/remarkjs/remark)? You probably shouldn’t use this package directly, but instead use [`remark-wikirefs`](https://github.com/wikibonsai/remark-wikirefs/tree/master/remark-wikirefs). See [`wikirefs-spec`](https://github.com/wikibonsai/wikirefs/blob/main/wikirefs/spec) for a full description of the supported syntax.
🕸 Weave a semantic web in your [🎋 WikiBonsai](https://github.com/wikibonsai/wikibonsai) digital garden.
## Install
This package is [ESM only](https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c). Install [`mdast-util-wikirefs`](https://www.npmjs.com/package/mdast-util-wikirefs) on `npm`.
```
npm install mdast-util-wikirefs
```
## Use
### Markdown to AST
#### WikiRefs (MKDN -> AST)
To use all wiki constructs, use `wikirefs`:
```javascript
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...
```markdown
':attrtype::[[fname]]\n'
```
...is first converted to a data node which takes the form below:
```json
{
"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.
```json
{
"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:
```javascript
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...
```markdown
[[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.
```json
{
"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:
```javascript
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...
```markdown
![[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.
```json
{
"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:
```javascript
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 `ast`s from the previous example...
#### WikiRefs (AST -> MKDN)
```javascript
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:
```markdown
:attrtype::[[fname]]
```
To use only the wikiattr construct:
```javascript
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:
```markdown
[[fname]]
```
To use only the wikilink construct:
```javascript
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:
```markdown
![[fname]]
![[audio.mp3]]
![[image.png]]
![[video.mp4]]
```
To use only the wikiembed construct:
```javascript
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`:
```js
// defaults
let mdastOpts = {
attrs: {
enable: true,
},
links: {
enable: true,
},
embeds: {
enable: true,
},
};
```
### Options Descriptions
See [`remark-wikirefs` readme](https://github.com/wikibonsai/remark-wikirefs#options-descriptions) for option descriptions.