Have ideas to improve npm?Join in the discussion! »

    mdast-util-wiki-link

    0.0.1 • Public • Published

    mdast-util-wiki-link

    npm version Build Status

    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 remark-wiki-link instead of using this package directly.

    Usage

    Markdown to AST

    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:

    {
        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.

    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 '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({ 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:

    (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:

    (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. 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 class="internal new" href="#/page/real_page">Page Alias</a>
    

    Install

    npm i mdast-util-wiki-link

    DownloadsWeekly Downloads

    318

    Version

    0.0.1

    License

    MIT

    Unpacked Size

    26.7 kB

    Total Files

    13

    Last publish

    Collaborators

    • avatar