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
• Appendix
  • Published Package Details
  • License
• Contributing and Support
  • Contributors

Install

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

To install:

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.

Appendix

Further documentation can be found under docs/.

Published Package Details

This is an ESM-only package built by Babel for use in Node.js versions that are not end-of-life. For TypeScript users, this package supports both "Node10" and "Node16" module resolution strategies.

That means ESM source will load this package via import { ... } from ... or await import(...) and CJS source will load this package via dynamic import(). This has several benefits, the foremost being: less code shipped/smaller package size, avoiding dual package hazard entirely, distributables are not packed/bundled/uglified, and a drastically less complex build process.

The glaring downside, which may or may not be relevant, is that CJS consumers cannot require() this package and can only use import() in an asynchronous context. This means, in effect, CJS consumers may not be able to use this package at all.

Each entry point (i.e. ENTRY) in package.json's exports[ENTRY] object includes one or more export conditions. These entries may or may not include: an exports[ENTRY].types condition pointing to a type declaration file for TypeScript and IDEs, a exports[ENTRY].module condition pointing to (usually ESM) source for Webpack/Rollup, a exports[ENTRY].node and/or exports[ENTRY].default condition pointing to (usually CJS2) source for Node.js require/import and for browsers and other environments, and other conditions not enumerated here. Check the package.json file to see which export conditions are supported.

Note that, regardless of the { "type": "..." } specified in package.json, any JavaScript files written in ESM syntax (including distributables) will always have the .mjs extension. Note also that package.json may include the sideEffects key, which is almost always false for optimal tree shaking where appropriate.

License

See LICENSE.

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! ✊🏿 Or buy me a beer, I'd appreciate it. Thank you!

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

Contributors

See the table of contributors.