remark-mdat

A remark plugin implementing the Markdown Autophagic Template (MDAT) system.

[!NOTE]

Please see The mdat package for a higher-level CLI tool and library with a collection of built-in expansion rules.

Table of contents

• Overview
• Getting started
  • Dependencies
  • Installation
• Usage
  • API
  • Examples
• Utilities
• Implementation notes
• The future
• Maintainers
• Acknowledgments
• Contributing
• License

Overview

This is a remark plugin that automates the inline expansion of placeholder HTML comments with dynamic content in Markdown, making it easy to keep readme files and other documentation in sync with an external single source of truth.

The plugin can take placeholder comments in a Markdown file like this:

1<!-- title -->

And replace it with dynamic data. In this case, from package.json:

1<!-- title -->
2
3# remark-mdat
4
5<!-- /title -->

This plugin powers the higher-level mdat package, which is a better place to start if you just want to expand some comments and aren't working directly with remark processing pipelines.

Getting started

Dependencies

This library is ESM only and requires Node 18 (specifically ^18.19.0 || >=20.5.0). It's designed to work with Remark 15. remark-mdat is implemented in TypeScript and bundles a complete set of type definitions.

Installation

1npm install remark-mdat

Usage

API

Core plugin

This package's default export implements the unified Plugin type.

The plugin is integrated into a remark process chain via the .use() method:

1import { remark } from 'remark'
2import remarkMdat from 'remark-mdat'
3
4remark().use(remarkMdat)

Options

The plugin accepts an optional options object which exposes some configuration options and, most importantly, determines how comments in the source Markdown file will be expanded via the rules field:

1export type Options = {
2  addMetaComment?: boolean // Default: false
3  closingPrefix?: string // Default: '/',
4  keywordPrefix?: string // Default: '',
5  metaCommentIdentifier?: string // Default: '+',
6  rules?: Rules // Default: a single test rule for the 'mdat' keyword
7}

Examples

Basic

remark-mdat includes one test rule by default, <!-- mdat -->.

1import { remark } from 'remark'
2import remarkMdat from 'remark-mdat'
3
4const markdownInput = '<!-- mdat -->'
5const markdownOutput = await remark().use(remarkMdat).process(markdownInput)
6
7console.log(markdownOutput.toString())
8
9// Logs:
10// <!-- mdat -->
11//
12// Powered by the Markdown Autophagic Template system: [mdat](https://github.com/kitschpatrol/mdat).
13//
14// <!-- /mdat -->

With options

If you wanted to replace <!-- time --> comments in your Markdown file with the current time, you could pass in a rule:

1import type { Rules } from 'remark-mdat'
2import { remark } from 'remark'
3import remarkMdat from 'remark-mdat'
4
5// Create the rule
6const rules: Rules = {
7  time: () => new Date().toDateString(),
8}
9
10const markdownInput = '<!-- time -->'
11
12// Pass the time rule to remarkMdat
13const markdownOutput = await remark().use(remarkMdat, { rules }).process(markdownInput)
14
15console.log(markdownOutput.toString())
16
17// Logs:
18// <!-- time -->
19//
20// Mon Feb 05 2024
21//
22// <!-- /time -->

See the mdat package for a higher-level API and CLI that can operate directly on files or strings. It also provides dynamic rule loading and configuration resolution, and bundles a collection of rules convenient for use in readme files.

Utilities

The plugin bundles a number of mdast utilities designed to operate directly on syntax trees. These are exported to support customized Unified.js processors and enforce modularity and separation of concerns in mdat's internal implementation, but you do not need to use them directly — all functionality is encapsulated in the single remarkMdat plugin export.

The remark-mdat plugin chains these utilities together to accommodate the typical use case of end-to-end expansion and validation of mdat comments. For now, the individual utility transformers are not published individually to NPM, and are instead bundled with remark-mdat.

• mdast-util-mdat

  Composite transformer function performing end-to-end mdat comment expansion and validation on Markdown ASTs by chaining the other utility functions described below.

  Exported as mdat

  Utilities wrapped by mdast-util-mdat:

  • mdast-util-mdat-split

    Transformer function that allows inline mdat expansion comments.

    Exported as mdatSplit

  • mdast-util-mdat-clean

    Transformer function that "resets" all mdat comment expansions in a file, collapsing expanded comments back into single-line placeholders.

    Exported as mdatClean

  • mdast-util-mdat-expand

    Transformer function that expands mdat comments (e.g. <!-- title -->) in a Markdown file according to the rule set passed in to the MdatExpandOptions argument.

    Exported as mdatExpand

  • mdast-util-mdat-check

    Transformer function that validates an expanded Markdown document against the requirements defined in the rules passed in to the MdatCheckOptions argument.

    See reporterMdat to extract, format, and log results from VFile messages written by mdatCheck. This function does not modify the tree, it only appends messages to the VFiles passed through it.

    Exported as mdatCheck

Implementation notes

This project was split from a monorepo containing both mdat and remark-mdat into separate repos in July 2024.

The future

• Consider making remark a peer dependency? Though perhaps not strip-markdown/issues/24...

Maintainers

@kitschpatrol

Acknowledgments

Thanks to the unified team for their superb ecosystem of AST tools.

Contributing

Issues and pull requests are welcome.

License

MIT © Eric Mika