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.

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