@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

• @it-service-npm/remark-heading-adjustment Remark plugin
  • Contents
  • Install
  • Examples
    • Adjustment headings depth when topHeadingDepth specified
    • Does nothing if topHeadingDepth is not 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 (shift they 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.

Does nothing if topHeadingDepth is not specified

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

Without additional processor or file data this plugin does nothing.

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(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.

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

This plugin works with remark CLI to standardize heading levels, ensuring that the top-level heading depth is always 1.

.remarkrc.mjs:

import {
  remarkAdjustTopHeadingToH1
} from '@it-service-npm/remark-heading-adjustment';

export default {
  plugins: [
    remarkAdjustTopHeadingToH1
  ]
}

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