@it-service-npm/remark-heading-adjustment Remark plugin

This Remark plugin helps to adjust headings depth in markdown file.

When processor.data().topHeadingDepth is specified, this plugin adjusts all headings so that the depth of the top heading aligns with the given value.

If processor.data().topHeadingDepth is not set, the plugin remains inactive.

Contents

• Install
• Examples
  • Adjustment headings depth when topHeadingDepth specified
  • Adjustment headings depth when topHeadingDepth specified in settings
  • Adjust top heading depth to H1
• API
• License

Install

npm install --save-dev @it-service-npm/remark-heading-adjustment

Examples

Adjustment headings depth when topHeadingDepth specified

@it-service-npm/remark-heading-adjustment can help to adjust headings depth in markdown document.

When processor.data().topHeadingDepth is specified, this plugin adjusts all headings (by shifting them up or down) so that the depth of the top heading aligns with the given value.

import { remark } from 'remark';
import * as vFile from 'to-vfile';
import {
  remarkHeadingsAdjustment
} from '@it-service-npm/remark-heading-adjustment';
import type { VFile } from 'vfile';

export async function remarkUsingExample(
  filePath: string
): Promise<VFile> {
  return remark()
    .data('topHeadingDepth', 3)
    .use(remarkHeadingsAdjustment)
    .process(await vFile.read(filePath));
};

Source files:

main.md:

# main header (depth 1)

Text 1.

## header 2 (depth 2)

Text 2.

### header 3 (depth 3)

Text 3.

## header 4 (depth 2)

Text 4.

Remark output:

### main header (depth 1)

Text 1.

#### header 2 (depth 2)

Text 2.

##### header 3 (depth 3)

Text 3.

#### header 4 (depth 2)

Text 4.

Without additional processor or file data this plugin does nothing.

Adjustment headings depth when topHeadingDepth specified in settings

When processor.data().topHeadingDepth is not specified, this plugin accepts topHeadingDepth from settings.

import { remark } from 'remark';
import * as vFile from 'to-vfile';
import {
  remarkHeadingsAdjustment
} from '@it-service-npm/remark-heading-adjustment';
import type { VFile } from 'vfile';

export async function remarkUsingExample(
  filePath: string
): Promise<VFile> {
  return remark()
    .use({
      plugins: [remarkHeadingsAdjustment],
      settings: {
        topHeadingDepth: 1
      }
    })
    .process(await vFile.read(filePath));
};

Source files:

main.md:

## main header (depth 1)

Text 1.

### header 2 (depth 2)

Text 2.

#### header 3 (depth 3)

Text 3.

### header 4 (depth 2)

Text 4.

Remark output:

# main header (depth 1)

Text 1.

## header 2 (depth 2)

Text 2.

### header 3 (depth 3)

Text 3.

## header 4 (depth 2)

Text 4.

Adjust top heading depth to H1

The plugin exports a preset called remarkAdjustTopHeadingToH1. This preset includes the remarkHeadingsAdjustment plugin with settings {topHeadingDepth: 1}.

These are meant for use in .remarkrc files and help normalize the depth of the top-level heading.

.remarkrc.mjs:

import remarkDirective from 'remark-directive';
import {
  remarkAdjustTopHeadingToH1
} from '@it-service-npm/remark-heading-adjustment';
import { remarkIncludeCode } from '@it-service-npm/remark-include-code/async';

export default {
  plugins: [
    remarkDirective,
    remarkAdjustTopHeadingToH1,
    [remarkIncludeCode, {
      useEditorConfig: true,
      trimFinalNewline: true,
      trimExtraIndent: true
    }],
  ]
}

Source files:

main.md:

## top level header

Text 1.

### header 2

Text 2.

#### header 3

Text 3.

### header 4

Text 4.

Remark output:

# top level header

Text 1.

## header 2

Text 2.

### header 3

Text 3.

## header 4

Text 4.

API

Please, read the API reference.

License

MIT © Sergei S. Betke