mdast-util-ofm-wikilink

mdast extensions to parse and serialize Obsidian Flavored Markdown (OFM) wikilinks and embeddings.

What is this?

This package contains two extensions to add support for OFM wikilink syntax to mdast. These extensions plug into mdast-util-from-markdown (to support parsing wikilinks in markdown into a syntax tree) and mdast-util-to-markdown (to support serializing wikilinks in syntax trees to markdown)

When to use this

You can use these extension when you are working with mdast-util-from-markdown and mdast-util-to-markdown already.

When working with mdast-util-from-markdown, you must combine this package with micromark-extension-ofm-wikilink.

When you don't need a syntax tree, you can use micromark directly with micromark-extension-ofm-wikilink.

When you are working with syntax trees and want all of OFM, use mdast-util-ofm instead.

All these packages are used in remark-ofm, which focusses on making it easier to transform content by abstracting these internal away.

Install

This package is ESM only. In Node.js (version 18+), install with npm:

npm install @moritzrs/mdast-util-ofm-wikilink

Use

import { fromMarkdown } from "mdast-util-from-markdown";
import { toMarkdown } from "mdast-util-to-markdown";
import { ofmWikilink } from "@moritzrs/micromark-extension-ofm-wikilink";
import { ofmWikilinkFromMarkdown, ofmWikilinkToMarkdown } from "@moritzrs/mdast-util-ofm-wikilink";

const tree = fromMarkdown("This is a [[link]].", {
	extensions: [ofmWikilink()],
	mdastExtensions: [ofmWikilinkFromMarkdown()],
});

console.log(tree);

const out = toMarkdown(tree, { extensions: [ofmWikilinkToMarkdown()] });

console.log(out);

Yields

{
	type: "root",
	children: [
		{
			type: "paragraph",
			children: [
				{ type: "text", value: "This is a " },
				{ type: "ofmWikilink", value: "link", url: "link", hash: "" },
				{ type: "text", value: "." },
			],
		},
	]
}

This is a [[link]].

API

This package exports the identifiers ofmWikilinkFromMarkdown and ofmWikilinkToMarkdown. There is no default export.

ofmWikilinkFromMarkdown()

Creates an extension for mdast-util-from-markdown to enable OFM wikilink in markdown.

Parameters

• none

Returns

Extension for mdast-util-from-markdown that can be passed in extensions, to enable OFM wikilink syntax (FromMarkdownExtension).

ofmWikilinkToMarkdown()

Creates an extension for mdast-util-to-markdown to enable OFM wikilink in markdown.

Parameters

• none

Returns

Extension for mdast-util-to-markdown that can be passed in extensions, to support OFM wikilinks when serializing to markdown (ToMarkdownExtension).

Syntax

See Syntax in micromark-extension-ofm-wikilink.

Syntax tree

The following interfaces are added to mdast by this utility.

Nodes

OfmWikilink

interface OfmWikilink <: Literal {
	type: "ofmWikilink";
	url: string;
	hash: string;
	value: string;
}

OfmWikilink represents an internal link.

OfmWikilink can be used where phrasing content is expected.

For example, the following markdown:

[[link]]

Yields:

{
	type: "ofmWikilink",
	url: "link",
	hash: "",
	value: "link",
}

OfmWikiEmbedding

interface OfmWikiEmbedding <: Literal {
	type: "ofmWikilink";
	url: string;
	hash: string;
	value: string;
}

OfmWikiEmbedding represents an embedded internal file.

OfmWikiEmbedding can be used where phrasing content is expected.

For example, the following markdown:

![[link]]

Yields:

{
	type: "ofmWikiembedding"
	url: "link",
	hash: "",
	value: "link",
}

Content Model

PhrasingContent (OFM wikilink)

type PhrasingContent = OfmWikilink | OfmWikiEmbedding | PhrasingContent;

Types

This package is fully typed with TypeScript. It does not export additional types.

The OfmWikilink and OfmWikiEmbedding types of the mdast node are exposed from @types/mdast.

Compatibility

This package was tested to work with node version 18 and later.

Related

• remark-ofm - remark plugin to support OFM
• mdast-util-ofm - mdast extension to parse and serialize OFM
• micromark-extension-ofm-wikilink - micromark extension to parse OFM wikilinks

Contribute

I don't know if i can check PRs in a timely manner, but feel free to open PRs or issues. If participation is high I will need to add a code of conduct and contribution guidelines.

Disclaimer

This package is not affiliated with Obsidian.md or the developers of Obsidian.md.

License

MIT © Moritz R. Schulz