mdast-util-ofm-tag

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

What is this?

This package contains two extensions to add support for OFM tag syntax to mdast. These extensions plug into mdast-util-from-markdown (to support parsing tags in markdown into a syntax tree) and mdast-util-to-markdown (to support serializing tags 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-tag.

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

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-tag

Use

import { fromMarkdown } from "mdast-util-from-markdown";
import { toMarkdown } from "mdast-util-to-markdown";
import { ofmTag } from "@moritzrs/micromark-extension-ofm-tag";
import { ofmTagFromMarkdown, ofmTagToMarkdown } from "@moritzrs/mdast-util-ofm-tag";

const tree = fromMarkdown("This is a #tag.", {
	extensions: [ofmTag()],
	mdastExtensions: [ofmTagFromMarkdown()],
});

console.log(tree);

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

console.log(out);

Yields

{
	type: "root",
	children: [
		{
			type: "paragraph",
			children: [
				{ type: "text", value: "This is a " },
				{ type: "ofmTag", value: "tag" },
				{ type: "text", value: "." },
			],
		},
	]
}

This is a #tag.

API

This package exports the identifiers ofmTagFromMarkdown and ofmTagToMarkdown. There is no default export.

ofmTagFromMarkdown()

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

Parameters

• none

Returns

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

ofmTagToMarkdown()

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

Parameters

• none

Returns

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

Syntax

See Syntax in micromark-extension-ofm-tag.

Syntax tree

The following interfaces are added to mdast by this utility.

Nodes

OfmTag

interface OfmTag <: Literal {
	type: "ofmTag";
	value: string;
}

OfmTag represents a keyword that should be findable in a search.

OfmTag can be used where phrasing content is expected.

For example, the following markdown:

#tag

Yields:

{
	type: "ofmTag",
	value: "tag",
}

Content Model

PhrasingContent (OFM tag)

type PhrasingContent = OfmTag | PhrasingContent;

Types

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

The OfmTag type of the mdast node is 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-tag - micromark extension to parse OFM tags

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