Mdast-util-tight-comments NPM

mdast-util-tight-comments

This is a small mdast utility that extends mdast-util-to-markdown allowing for the selective removal of newlines around certain mdast comment nodes.

This is a low level project used by remark-tight-comments, which is a companion package to remark-ignore.

Install

Due to the nature of the unified ecosystem, this package is ESM only and cannot be require'd.

npm install mdast-util-tight-comments

Usage

Suppose we have the following Markdown file example.md:

<!-- prettier-ignore-start -->
<!-- remark-ignore-start -->
<!-- START doctoc generated TOC please keep comment here to allow auto update -->
<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->

- [Install remark](#install)
- [Usage](#usage)
- [API](#api)
- [Related](#related)
- [Contributing and Support](#contributing-and-support)
  - [Contributors](#contributors)

<!-- END doctoc generated TOC please keep comment here to allow auto update -->
<!-- remark-ignore-end -->
<!-- prettier-ignore-end -->

<!-- Begin the documentation section -->

<!-- TODO: add another section here -->

<!-- remark-ignore -->

# Install [remark](https://npm.im/remark)

Notice how the <!-- START doctoc… and <!-- DON'T EDIT… comments are tightly positioned such that there is no newline between them. This is required by doctoc.

Now, running the following JavaScript:

import fs from 'node:fs';
import { unified } from 'unified';
import remarkParse from 'remark-parse';
import { toMarkdown } from 'mdast-util-to-markdown';

const doc = fs.readFileSync('example.md');
const tree = unified().use(remarkParse).parse(doc);

console.log(toMarkdown(tree));

Would output the following (assuming remark is configured for dash bullets and singular list item indents):

<!-- prettier-ignore-start -->

<!-- remark-ignore-start -->

<!-- START doctoc generated TOC please keep comment here to allow auto update -->

<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->

- [Install remark](#install)
- [Usage](#usage)
- [API](#api)
- [Related](#related)
- [Contributing and Support](#contributing-and-support)
  - [Contributors](#contributors)

<!-- END doctoc generated TOC please keep comment here to allow auto update -->

<!-- remark-ignore-end -->

<!-- prettier-ignore-end -->

<!-- Begin the documentation section -->

<!-- TODO: add another section here -->

<!-- remark-ignore -->

# Install [remark](https://npm.im/remark)

Notice how the <!-- START doctoc… and <!-- DON'T EDIT… comments are now separated by a newline, which will cause erroneous behavior when running doctoc. ~~Additionally, all the unnecessary newlines around the comments are very ugly.~~

Suppose instead we ran the following JavaScript:

import fs from 'node:fs';
import { unified } from 'unified';
import remarkParse from 'remark-parse';
import { toMarkdown } from 'mdast-util-to-markdown';
import { joinTightComments } from 'mdast-util-tight-comments';

const doc = fs.readFileSync('example.md');
const tree = unified().use(remarkParse).parse(doc);

console.log(toMarkdown(tree, { join: [joinTightComments] }));

Then we would get the following output:

<!-- prettier-ignore-start -->
<!-- remark-ignore-start -->
<!-- START doctoc generated TOC please keep comment here to allow auto update -->
<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->

- [Install](#install)
- [Usage](#usage)
- [API](#api)
- [Related](#related)
- [Contributing and Support](#contributing-and-support)
  - [Contributors](#contributors)

<!-- END doctoc generated TOC please keep comment here to allow auto update -->
<!-- remark-ignore-end -->
<!-- prettier-ignore-end -->

<!-- Begin the documentation section -->
<!-- TODO: add another section here -->

<!-- remark-ignore -->

# Install [remark](https://npm.im/remark)

That's better! But not perfect. What if we want to preserve the default spacing around the <!-- Begin the… comment? Specifically, we want to maintain the newline before and after this comment.

To preserve newlines before a comment, affix the opening tag with a |. To preserve newlines after a comment, prefix the closing tag with a |. These can be combined to preserve a newline both before and after a comment.

For example, suppose we edited example.md to contain the following:

<!-- prettier-ignore-start -->
<!-- remark-ignore-start -->
<!-- START doctoc generated TOC please keep comment here to allow auto update -->
<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->

- [Install remark](#install)
- [Usage](#usage)
- [API](#api)
- [Related](#related)
- [Contributing and Support](#contributing-and-support)
  - [Contributors](#contributors)

<!-- END doctoc generated TOC please keep comment here to allow auto update -->
<!-- remark-ignore-end -->
<!-- prettier-ignore-end -->

<!--| Begin the documentation section |-->

<!-- TODO: add another section here -->

<!-- remark-ignore -->

# Install [remark](https://npm.im/remark)

Notice the  line. Since there aren't any other remark plugins being used, running the above JavaScript with this new readme.md file would output the contents of the file unchanged.

Also notice the  line. This specific comment receives special consideration in that:

There will never be a newline between it and the next node.
There will always be a newline between it and the previous node.

If you're running prettier after remark, you must surround the comments around which you want to preserve tightened spacing with  and .

API

Detailed interface information can be found under docs/.

remark-tight-comments — remove unnecessary newlines around comments.

Contributing and Support

New issues and pull requests are always welcome and greatly appreciated! 🤩 Just as well, you can star 🌟 this project to let me know you found it useful! ✊🏿 Thank you!

See CONTRIBUTING.md and SUPPORT.md for more information.