https://github.com/landakram/mdast-util-wiki-link
Extensions for mdast to support [[Wiki Links]].
https://github.com/landakram/mdast-util-wiki-link
Last synced: 5 months ago
JSON representation
Extensions for mdast to support [[Wiki Links]].
- Host: GitHub
- URL: https://github.com/landakram/mdast-util-wiki-link
- Owner: landakram
- Created: 2020-10-17T02:17:13.000Z (over 4 years ago)
- Default Branch: master
- Last Pushed: 2024-04-09T13:12:28.000Z (about 1 year ago)
- Last Synced: 2024-10-30T15:54:20.111Z (6 months ago)
- Language: TypeScript
- Homepage:
- Size: 593 KB
- Stars: 13
- Watchers: 3
- Forks: 8
- Open Issues: 3
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# mdast-util-wiki-link
[](https://badge.fury.io/js/mdast-util-wiki-link) [](https://travis-ci.org/landakram/mdast-util-wiki-link)
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 `[[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](https://github.com/remarkjs/remark)? You might want to use
[`remark-wiki-link`](https://github.com/landakram/remark-wiki-link) instead of using this package directly.
## Usage
### Markdown to AST
```javascript
import fromMarkdown from 'mdast-util-from-markdown'
import { syntax } from 'micromark-extension-wiki-link'
import * as wikiLink from 'mdast-util-wiki-link'
let ast = fromMarkdown('[[Test Page]]', {
extensions: [syntax()],
mdastExtensions: [wikiLink.fromMarkdown()]
})
```
The AST node will look like this:
```javascript
{
value: 'Test Page',
data: {
alias: 'Test Page',
permalink: 'test_page',
exists: false,
hName: 'a',
hProperties: {
className: 'internal new',
href: '#/page/test_page'
},
hChildren: [{
type: 'text',
value: 'Test 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.pageResolver`, which can be passed in when initializing the plugin.
* `data.exists`: Whether the page exists. A page exists if its permalink is found in `options.permalinks`, passed when initializing the plugin.
* `data.hProperties.className`: Classes that are automatically attached to the `a` when it is rendered as HTML. These are configurable with `options.wikiLinkClassName` and `options.newClassName`. `options.newClassName` is attached when `data.exists` is false.
* `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`](https://github.com/rehypejs/rehype).
### AST to Markdown
Taking the `ast` from the prior example, let's go back to markdown:
```javascript
import { fromMarkdown } from 'mdast-util-from-markdown'
import * as wikiLink from '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:
```javascript
let ast = fromMarkdown('[[Test Page]]', {
extensions: [syntax()],
mdastExtensions: [wikiLink.fromMarkdown({ permalinks: ['wiki_page'] })] // <--
})
```
#### `fromMarkdown`
* `options.permalinks [String]`: An array of permalinks that should be considered existing pages. If a wiki link is parsed and its permalink matches one of these permalinks, `node.data.exists` will be true.
* `options.pageResolver (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 `pageResolver` is:
```javascript
(name) => [name.replace(/ /g, '_').toLowerCase()]
```
* `options.hrefTemplate (permalink: String) -> String`: A function that maps a permalink to some path. This path is used as the `href` for the rendered `a`.
The default `hrefTemplate` is:
```javascript
(permalink) => `#/page/${permalink}`
```
* `options.wikiLinkClassName [String]`: a class name that is attached to any rendered wiki links. Defaults to `"internal"`.
* `options.newClassName [String]`: a class name that is attached to any rendered wiki links that do not exist. Defaults to `"new"`.
#### `toMarkdown`
* `options.aliasDivider [String]`: a string to be used as the divider for aliases. See the section below on [Aliasing pages](#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:
```
Page Alias
```