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.
Due to the nature of the unified ecosystem, this package is ESM only and cannot be
require'd.
npm install mdast-util-tight-commentsSuppose 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:
- 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
<!-- prettier-ignore-start -->and<!-- prettier-ignore-end -->.
Detailed interface information can be found under docs/.
- remark-tight-comments — remove unnecessary newlines around comments.
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.
See the table of contributors.