@moritzrs/micromark-extension-ofm-callout

micromark-extension-ofm-callout

micromark extensions to support Obsidian Flavored Markdown (OFM) callouts.

What is this?

This package contains two extensions to add support for OFM callout syntax to micromark.

As there is no formal specification, this extensions follows the behavior explained in the Obsidian help.

When to use this

This project is useful if you want to support OFM callouts in your markdown.

You can use these extensions when you are working with micromark. To support all OFM features use micromark-extension-ofm.

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

Install

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

npm install @moritzrs/micromark-extension-ofm-callout

Use

import { micromark } from "micromark";
import { ofmCallout, ofmCalloutHtml } from "@moritzrs/micromark-extension-ofm-callout";

const output = micromark("> [!type]+ Title\n> Content", {
	extensions: [ofmCallout()],
	htmlExtensions: [ofmCalloutHtml()],
});

console.log(output);

Yields:

<blockquote class="callout" data-type="type">
	<details open="">
		<summary>Title</summary>
		<p>Content</p>
	</details>
</blockquote>

API

This package exports the identifiers ofmCallout and ofmCalloutHtml. There is no default export.

ofmCallout()

Creates an extension for micromark to enable OFM callout syntax.

Parameters

• none

Returns

Extension for micromark that can be passed in extensions, to enable OFM callout syntax (Extension).

ofmCalloutHtml()

Creates an extension for micromark to support OFM callouts when serializing to HTML.

Parameters

• none

Returns

Extension for micromark that can be passed in htmlExtensions, to support OFM callouts when serializing to HTML (HtmlExtension).

Authoring

When authoring markdown with callouts, keep in mind that callouts don't work in most places. If not supported they will be treated as blockquotes and their prefix will be treated as raw text.

HTML

When using callouts, the will be expressed as following

<blockquote class="callout" data-type="type">
	<details open="">
		<summary>Title</summary>
		<p>Content</p>
	</details>
</blockquote>

CSS

callouts can be styled using the following selector.

blockquote.callout {
	/** General Callout styling */
}

blockquote.callout[data-type="type"] {
	/** Specific Callout type styling */
}

blockquote.callout details {
	/** Content */
}

blockquote.callout details summary {
	/** Title */
}

Syntax

Callouts derive from blockquotes and have a prefix that defines its appearance.

Callouts form with the following BNF:

<callout> ::= <prefix> ("\n" <content>)*

<prefix> ::= <space>? ">" <space>? "[" "!" <type> "]" <foldable>? <space> <title>?
<content> ::= <space>? ">" <letter>*

<type> ::= <letter>+ | <type> <space>+
<foldable> ::= "+" | "-"
<title> ::= (<letter> | <space>)+

<letter> ::= [a-z] | [A-Z] | [0-9]
<space> ::= " "

The above grammar is just a rough description and misses out some allowed characters and spaces.

Compatibility

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

Security

This package is safe.

Related

• micromark-extension-ofm - support for all of OFM
• mdast-util-ofm-callout - support for OFM callouts in mdast
• mdast-util-ofm - support for all of OFM in mdast
• remark-ofm - support for all of OFM in remark

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