![Black Lives Matter!][x-badge-blm-image] [![Last commit timestamp][x-badge-lastcommit-image]][x-badge-repo-link] ![Codecov][x-badge-codecov-image] [![Source license][x-badge-license-image]][x-badge-license-link] ![Monthly Downloads][x-badge-downloads-image] ![NPM version][x-badge-npm-image] [![Uses Semantic Release!][x-badge-semanticrelease-image]][x-badge-semanticrelease-link]
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][3], 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 <!--| 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 -->
.
API
Detailed interface information can be found under docs/
.
Related
- remark-tight-comments — remove unnecessary newlines around comments.
Contributing and Support
[New issues][x-repo-choose-new-issue] and pull requests are always welcome and greatly appreciated! 🤩 Just as well, you can [star 🌟 this project][x-badge-repo-link] 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.
[x-badge-blm-image]: https://xunn.at/badge-blm 'Join the movement!'
[x-badge-codecov-image]: https://img.shields.io/codecov/c/github/xunnamius/unified-utils/main?style=flat-square&token=HWRIOBAAPW 'Is this package well-tested?'
[x-badge-downloads-image]: https://img.shields.io/npm/dm/mdast-util-tight-comments?style=flat-square 'Number of times this package has been downloaded per month' [x-badge-lastcommit-image]: https://img.shields.io/github/last-commit/xunnamius/unified-utils?style=flat-square 'Latest commit timestamp' [x-badge-license-image]: https://img.shields.io/npm/l/mdast-util-tight-comments?style=flat-square "This package's source license" [x-badge-license-link]: https://github.com/Xunnamius/unified-utils/blob/main/packages/mdast-util-tight-comments/LICENSE [x-badge-npm-image]: https://xunn.at/npm-pkg-version/mdast-util-tight-comments 'Install this package using npm or yarn!'
[x-badge-repo-link]: https://github.com/xunnamius/unified-utils/blob/main/packages/mdast-util-tight-comments [x-badge-semanticrelease-image]: https://img.shields.io/badge/%20%20%F0%9F%93%A6%F0%9F%9A%80-semantic--release-e10079.svg?style=flat-square 'This repo practices continuous integration and deployment!' [x-badge-semanticrelease-link]: https://github.com/semantic-release/semantic-release [x-repo-choose-new-issue]: https://github.com/xunnamius/unified-utils/issues/new/choose
[3]: https://github.com/xunnamius/unified-utils/blob/main/packages/remark-tight-comments