remark plugin to selectively remove newlines around comments
[![Black Lives Matter!][x-badge-blm-image]][x-badge-blm-link]
[![Last commit timestamp][x-badge-lastcommit-image]][x-badge-repo-link]
[![Codecov][x-badge-codecov-image]][x-badge-codecov-link]
[![Source license][x-badge-license-image]][x-badge-license-link]
[![Uses Semantic Release!][x-badge-semanticrelease-image]][x-badge-semanticrelease-link]
[![NPM version][x-badge-npm-image]][x-badge-npm-link]
[![Monthly Downloads][x-badge-downloads-image]][x-badge-downloads-link]
# remark-tight-comments
This is a [unified][1] ([remark][2]) plugin that allows you to selectively
remove unnecessary newlines around Markdown comments.
This plugin is useful for preserving the structure of auto-generated content,
e.g. [all-contributors][3], [doctoc][4], etc. You might also be interested in
[remark-ignore][5], which lets you instruct remark not to transform parts of
your Markdown documents. For a live example of these two plugins in action,
check the source of [this very README.md file][6]. ✨
---
- [Install](#install)
- [Usage](#usage)
- [Via API](#via-api)
- [Via remark-cli](#via-remark-cli)
- [Via unified configuration](#via-unified-configuration)
- [API](#api)
- [Examples](#examples)
- [Related](#related)
- [Appendix](#appendix)
- [Published Package Details](#published-package-details)
- [License](#license)
- [Contributing and Support](#contributing-and-support)
- [Contributors](#contributors)
## Install
> Due to the nature of the unified ecosystem, this package is ESM only and
> cannot be `require`'d.
To install:
```shell
npm install --save-dev remark-tight-comments
```
## Usage
For maximum flexibility, there are several ways this plugin can be invoked.
### Via API
```typescript
import { read } from 'to-vfile';
import { remark } from 'remark';
import remarkTightComments from 'remark-tight-comments';
const file = await remark()
.use(remarkTightComments)
.process(await read('example.md'));
console.log(String(file));
```
### Via [remark-cli](https://xunn.at/docs-remark-cli)
```shell
remark -o --use tight-comments README.md
```
### Via [unified configuration](https://xunn.at/docs-unified-configuration)
In `package.json`:
```javascript
/* … */
"remarkConfig": {
"plugins": [
"remark-tight-comments"
/* … */
]
},
/* … */
```
In `.remarkrc.js`:
```javascript
module.exports = {
plugins: [
// …
'tight-comments'
]
};
```
In `.remarkrc.mjs`:
```javascript
import remarkTightComments from 'remark-tight-comments';
export default {
plugins: [
// …
remarkTightComments
]
};
```
## API
Detailed interface information can be found under [`docs/`][x-repo-docs].
## Examples
See [mdast-util-tight-comments][7] for example outputs.
## Related
- [remark-ignore][5] — use comments to exclude one or more nodes from
[transformation][8].
- [mdast-util-tight-comments][9] — selectively remove newlines around comment
nodes during serialization.
## Appendix
Further documentation can be found under [`docs/`][x-repo-docs].
### Published Package Details
This is an [ESM-only package][x-pkg-esm-wine] 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.
Expand details
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][x-pkg-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]`][x-repo-package-json] object includes one or more [export
conditions][x-pkg-exports-conditions]. These entries may or may not include: an
[`exports[ENTRY].types`][x-pkg-exports-types-key] condition pointing to a type
declaration file for TypeScript and IDEs, a
[`exports[ENTRY].module`][x-pkg-exports-module-key] 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][x-pkg-exports-conditions] not enumerated here. Check the
[package.json][x-repo-package-json] file to see which export conditions are
supported.
Note that, regardless of the [`{ "type": "..." }`][x-pkg-type] specified in
[`package.json`][x-repo-package-json], any JavaScript files written in ESM
syntax (including distributables) will always have the `.mjs` extension. Note
also that [`package.json`][x-repo-package-json] may include the
[`sideEffects`][x-pkg-side-effects-key] key, which is almost always `false` for
optimal [tree shaking][x-pkg-tree-shaking] where appropriate.