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
• Usage
• API
• Related
• Contributing and Support
  • Contributors

Install

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

1npm install mdast-util-tight-comments

Usage

Suppose we have the following Markdown file example.md:

1<!-- prettier-ignore-start -->
2<!-- remark-ignore-start -->
3<!-- START doctoc generated TOC please keep comment here to allow auto update -->
4<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
5
6- [Install remark](#install)
7- [Usage](#usage)
8- [API](#api)
9- [Related](#related)
10- [Contributing and Support](#contributing-and-support)
11  - [Contributors](#contributors)
12
13<!-- END doctoc generated TOC please keep comment here to allow auto update -->
14<!-- remark-ignore-end -->
15<!-- prettier-ignore-end -->
16
17<!-- Begin the documentation section -->
18
19<!-- TODO: add another section here -->
20
21<!-- remark-ignore -->
22
23# 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:

1import fs from 'node:fs';
2import { unified } from 'unified';
3import remarkParse from 'remark-parse';
4import { toMarkdown } from 'mdast-util-to-markdown';
5
6const doc = fs.readFileSync('example.md');
7const tree = unified().use(remarkParse).parse(doc);
8
9console.log(toMarkdown(tree));

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

1<!-- prettier-ignore-start -->
2
3<!-- remark-ignore-start -->
4
5<!-- START doctoc generated TOC please keep comment here to allow auto update -->
6
7<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
8
9- [Install remark](#install)
10- [Usage](#usage)
11- [API](#api)
12- [Related](#related)
13- [Contributing and Support](#contributing-and-support)
14  - [Contributors](#contributors)
15
16<!-- END doctoc generated TOC please keep comment here to allow auto update -->
17
18<!-- remark-ignore-end -->
19
20<!-- prettier-ignore-end -->
21
22<!-- Begin the documentation section -->
23
24<!-- TODO: add another section here -->
25
26<!-- remark-ignore -->
27
28# 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:

1import fs from 'node:fs';
2import { unified } from 'unified';
3import remarkParse from 'remark-parse';
4import { toMarkdown } from 'mdast-util-to-markdown';
5import { joinTightComments } from 'mdast-util-tight-comments';
6
7const doc = fs.readFileSync('example.md');
8const tree = unified().use(remarkParse).parse(doc);
9
10console.log(toMarkdown(tree, { join: [joinTightComments] }));

Then we would get the following output:

1<!-- prettier-ignore-start -->
2<!-- remark-ignore-start -->
3<!-- START doctoc generated TOC please keep comment here to allow auto update -->
4<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
5
6- [Install](#install)
7- [Usage](#usage)
8- [API](#api)
9- [Related](#related)
10- [Contributing and Support](#contributing-and-support)
11  - [Contributors](#contributors)
12
13<!-- END doctoc generated TOC please keep comment here to allow auto update -->
14<!-- remark-ignore-end -->
15<!-- prettier-ignore-end -->
16
17<!-- Begin the documentation section -->
18<!-- TODO: add another section here -->
19
20<!-- remark-ignore -->
21
22# 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:

1<!-- prettier-ignore-start -->
2<!-- remark-ignore-start -->
3<!-- START doctoc generated TOC please keep comment here to allow auto update -->
4<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
5
6- [Install remark](#install)
7- [Usage](#usage)
8- [API](#api)
9- [Related](#related)
10- [Contributing and Support](#contributing-and-support)
11  - [Contributors](#contributors)
12
13<!-- END doctoc generated TOC please keep comment here to allow auto update -->
14<!-- remark-ignore-end -->
15<!-- prettier-ignore-end -->
16
17<!--| Begin the documentation section |-->
18
19<!-- TODO: add another section here -->
20
21<!-- remark-ignore -->
22
23# Install [remark](https://npm.im/remark)

Notice the <!--| Begin the documentation section |--> 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 <!-- remark-ignore --> line. This specific comment receives special consideration in that:

1. There will never be a newline between it and the next node.
2. 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 <!-- prettier-ignore-start --> and <!-- prettier-ignore-end -->.

API

Detailed interface information can be found under docs/.

Related

• 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.

Contributors

See the table of contributors.