mdast-util-ofm-callout

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

What is this?

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

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

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

Use

import { fromMarkdown } from "mdast-util-from-markdown";
import { toMarkdown } from "mdast-util-to-markdown";
import { ofmCallout } from "@moritzrs/micromark-extension-ofm-callout";
import { ofmCalloutFromMarkdown, ofmCalloutToMarkdown } from "@moritzrs/mdast-util-ofm-callout";

const tree = fromMarkdown("> [!info]+ Title\n> Content", {
    extensions: [ofmCallout()],
    mdastExtensions: [ofmCalloutFromMarkdown()],
});

console.log(tree);

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

console.log(out);

Yields

{
    type: "root",
    children: [
        {
            type: "ofmCallout",
            kind: "info",
            title: "Title",
            folded: false,
            children: [
                {
                    type: "paragraph",
                    children: [
                        {
                            type: "text",
                            value: "Content",
                        },
                    ],
                },
            ],
        },
    ],
}

> [!info]+ Title
> Content

API

This package exports the identifiers ofmCalloutFromMarkdown and ofmCalloutToMarkdown. There is no default export.

ofmCalloutFromMarkdown()

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

Parameters

• none

Returns

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

ofmCalloutToMarkdown()

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

Parameters

• none

Returns

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

Syntax

See Syntax in micromark-extension-ofm-callout.

Syntax tree

The following interfaces are added to mdast by this utility.

Nodes

OfmCallout

interface OfmCallout <: Parent {
    type: "ofmCallout";
    kind: string;
    title: string;
    folded?: boolean;
}

OfmCallout represents an emphasized block similar to a blockquote.

OfmCallout can be used where block content is expected.

For example, the following markdown:

> [!info]+ Title
> Content

Yields:

{
    type: "ofmCallout";
    kind: "info";
    title: "Title;
    folded?: false;
    children: [
        {
            type: "paragraph",
            children: [
                {
                    type: "text",
                    value: "Content",
                },
            ],
        },
    ],
}

Content Model

PhrasingContent (OFM callout)

type PhrasingContent = OfmCallout | PhrasingContent;

Types

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

The OfmCallout 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-callout - micromark extension to parse OFM callouts

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