remark-heading-gap

!Buildbuild-badgebuild !Coveragecoverage-badgecoverage !Downloadsdownloads-badgedownloads !Sizesize-badgesize !Sponsorssponsors-badgecollective !Backersbackers-badgecollective !Chatchat-badgechat
remark plugin to adjust the gap between headings in markdown.

Contents

• What is this?
• When should I use this?
• Install
• Use
• API

*   [`unified().use(remarkHeadingGap[, options])`](#unifieduseremarkheadinggap-options)
*   [`Gap`](#gap)
*   [`Options`](#options)

• Examples

*   [Example: blank lines around first/last headings](#example-blank-lines-around-firstlast-headings)

• Types
• Compatibility
• Security
• Related
• Contribute
• License

What is this?

This package is a unified (remark) plugin that lets you change the gap (number of blank lines) between headings and surrounding text when formatting markdown.

When should I use this?

This project is useful when you want to adjust the gap around headings when formatting markdown. For example, when you want two blank lines before headings with a rank of 2 (## Like so). From personal experience, adding extra blank lines helps visualize breaks in sections, especially when quickly scanning documentation. The default when serializing markdown with remark-stringify is to always but a single blank line between blocks (headings, paragraphs, lists, code, etc).

Install

This package is ESM onlyesm. In Node.js (version 16+), install with npm:

npm install remark-heading-gap

In Deno with esm.shesmsh:

import remarkHeadingGap from 'https://esm.sh/remark-heading-gap@6'

In browsers with esm.shesmsh:

<script type="module">
  import remarkHeadingGap from 'https://esm.sh/remark-heading-gap@6?bundle'
</script>

Use

Say we have the following file example.md:

# Pluto

## Contents

## History

### Discovery

### Name and symbol

### Planet X disproved

## Orbit

…and a module example.js:

import {remark} from 'remark'
import remarkHeadingGap from 'remark-heading-gap'
import {read} from 'to-vfile'

const file = await remark()
  .use(remarkHeadingGap)
  .process(await read('example.md'))

console.log(String(file))

…then running node example.js yields:

# Pluto


## Contents


## History

### Discovery

### Name and symbol

### Planet X disproved


## Orbit

API

This package exports no identifiers. The default export is remarkHeadingGapapi-remark-heading-gap.

unified().use(remarkHeadingGap[, options])

Adjust the gap between headings.
There are no blank lines added if a heading is the first or last child of the document, list item, or block quote. For example, pass {1: {before: 2, after: 2}} to add two blank lines before and after the main heading. You can also set values to 0 to not add blank lines.

Parameters

• options (Optionsapi-options, default: {2: {before: 2}})

— configuration

Returns

Nothing (undefined).

Gap

Gap between a heading (TypeScript type).

Fields

• after (number, default: 1)

— blank lines after heading

• before (number, default: 1)

— blank lines before heading

Options

Configuration (TypeScript type).

Type

type Options = Partial<Record<1 | 2 | 3 | 4 | 5 | 6, Gap | null | undefined>>

Examples

Example: blank lines around first/last headings

This example shows that there are no blank lines added before the first and after the last heading in a container. Assuming we had example.md from before and changed it to contain this:

# Alpha

Bravo charlie.

> ## Delta
>
> Echo foxtrott.
>
> ## Golf

Then configuring this plugin in example.js like so:

@@ -3,7 +3,10 @@ import remarkHeadingGap from 'remark-heading-gap'
 import {read} from 'to-vfile'

 const file = await remark()
-  .use(remarkHeadingGap)
+  .use(remarkHeadingGap, {
+    1: {after: 3, before: 3},
+    2: {after: 2, before: 2}
+  })
   .process(await read('example.md'))

 console.log(String(file))

Then when running node example.js we’d get:

# Alpha



Bravo charlie.

> ## Delta
>
>
> Echo foxtrott.
>
>
> ## Golf

Types

This package is fully typed with TypeScript. It exports the additional types Gapapi-gap and Optionsapi-options.

Compatibility

Projects maintained by the unified collective are compatible with maintained versions of Node.js.
When we cut a new major release, we drop support for unmaintained versions of Node. This means we try to keep the current release line, remark-heading-gap@^6, compatible with Node.js 16.
This plugin works with remark-stringify version 9+ (remark version 13+). Version 3 of this plugin worked with remark-stringify version 8- (remark version 12-).

Security

Use of remark-heading-gap does not involve rehype (hast) or user content so there are no openings for cross-site scripting (XSS)wiki-xss attacks.

Related

• remarkjs/remark-normalize-headings

— make sure there is a single top level heading in a document by adjusting
heading ranks accordingly

Contribute

See contributing.mdcontributing in remarkjs/.githubhealth for ways to get started. See support.mdsupport for ways to get help.
This project has a code of conductcoc. By interacting with this repository, organization, or community you agree to abide by its terms.

License

MITlicense © Ben Briggsauthor