@it-service-npm/remark-include Remark plugin

With this plugin, you can use ::include{file=./included.md} GitLab transclusion syntax statements to compose markdown files together.

Additional features:

• GitLab include directives inside the included file are ignored, but this plugin support recursive transclusion
• It is possible to use globs (::include{file=./included*.md}) in file attribute
• New attribute optional, which disable fatal directive error when file does not exists
• Relative images and links in the imported files will have their paths rewritten to be relative the original document rather than the imported file (with @it-service-npm/remark-relative-url-adjustment)
• An imported markdown file will “inherit” the heading levels. If the ::include{file=./included.md} statement happens under Heading 2, for example, any heading 1 in the included file will be “translated” to have header level 3 (with @it-service-npm/remark-heading-adjustment)

This plugin is a modern version of remark-import plugin and remark-include plugin, written in Typescript, and compatible with Remark v15.

There are two plugins: remarkInclude (preferred) and remarkIncludeSync.

[!IMPORTANT] remark-directive plugin expected before @it-service-npm/remark-include.

This package provides two plugins presets:

• remarkIncludePreset. This preset contains:

  • remarkInclude
  • remarkDirective
  • remarkHeadingsAdjustment
  • remarkRelativeUrlsAdjustment
  • remarkRelativeCodePathsAdjustment

• remarkIncludePresetSync. This preset contains:

  • remarkIncludeSync
  • remarkDirective
  • remarkHeadingsAdjustment
  • remarkRelativeUrlsAdjustment
  • remarkRelativeCodePathsAdjustment

Contents

• @it-service-npm/remark-include Remark plugin
  • Contents
  • Install
  • Examples
    • Transclusion or including markdown sub-documents for reuse
    • Recursive transclusion
    • Adjust the heading levels
    • Include multiple files with glob
    • Updating relative path for links, images
    • Updating relative path for code files
  • API
  • License

Install

npm install --save-dev @it-service-npm/remark-include

Examples

Transclusion or including markdown sub-documents for reuse

@it-service-npm/remark-include can include sub-documents in markdown document.

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

export async function remarkDirectiveUsingExample(
  filePath: string
): Promise<VFile> {
  return remark()
    .use(remarkIncludePresetSync)
    .process(await vFile.read(filePath));
};

Source files:

main.md:

Hello. I am an main markdown file with `::include` directive.

::include{file=./included.md}

_That_ should do it!

included.md:

Hello. I am the included.

Remark output:

Hello. I am an main markdown file with `::include` directive.

Hello. I am the included.

*That* should do it!

Recursive transclusion

@it-service-npm/remark-include directive supported in included files.

Source files:

main.md:

Hello. I am an main markdown file with `::include` directive.

::include{file=./included1.md}

_That_ should do it!

included1.md:

Hello. I am the included1.

::include{file=./included2.md}

included2.md:

Hello. I am the included2.

Remark output:

Hello. I am an main markdown file with `::include` directive.

Hello. I am the included1.

Hello. I am the included2.

*That* should do it!

Adjust the heading levels

@it-service-npm/remark-include adjust the heading levels within the included content.

Source files:

main.md:

# Main file

Hello. I am an main markdown file with `::include` directive.

::include{file=./included1.md}

## in main file

_That_ should do it!

included1.md:

# included1 file

Hello. I am the included1.

## in included1 file

::include{file=./included2.md}

## in included 1 file after included2

text text text.

included2.md:

# included2 file

Hello. I am the included2.

Remark output:

# Main file

Hello. I am an main markdown file with `::include` directive.

## included1 file

Hello. I am the included1.

### in included1 file

#### included2 file

Hello. I am the included2.

### in included 1 file after included2

text text text.

## in main file

*That* should do it!

Include multiple files with glob

@it-service-npm/remark-include support glob as file attribute value.

Source files:

main.md:

# main file

Hello. I am an main markdown file with `::include` directive.

::include{file=./included*.md}

_That_ should do it!

included1.md:

# included 1

Hello. I am the included1.

included2.md:

# included 2

Hello. I am the included2.

included3.md:

# included 3

Hello. I am the included3.

Remark output:

# main file

Hello. I am an main markdown file with `::include` directive.

## included 1

Hello. I am the included1.

## included 2

Hello. I am the included2.

## included 3

Hello. I am the included3.

*That* should do it!

Updating relative path for links, images

Relative images and links in the imported files will have their paths rewritten to be relative the original document rather than the imported file.

Source files:

main.md:

Hello. I am an main markdown file with `::include` directive.

::include{file=./subfolder1/included.md}

_That_ should do it!

included.md:

Hello. I am the included. Test image:

![Test local image](test-image.png)

![Test local image with space](test%20image.png)

![Test web image](https://img.shields.io/badge/github-repo-blue?logo=github)

Remark output:

Hello. I am an main markdown file with `::include` directive.

Hello. I am the included. Test image:

![Test local image](subfolder1/test-image.png)

![Test local image with space](subfolder1/test%20image.png)

![Test web image](https://img.shields.io/badge/github-repo-blue?logo=github)

*That* should do it!

Updating relative path for code files

Relative images and links in the imported files will have their paths rewritten to be relative the original document rather than the imported file.

Source files:

main.md:

Hello. I am an main markdown file with `::include` directive.

::include{file=./subfolder1/included.md}

_That_ should do it!

included.md:

Hello. I am the included. Test for code file path rebasing:

```typescript file=../../example.ts
import { remark } from 'remark';
import * as vFile from 'to-vfile';
import remarkDirective from 'remark-directive';
import { remarkInclude } from '@it-service-npm/remark-include';
import type { VFile } from 'vfile';

export async function remarkDirectiveUsingExample(
  filePath: string
): Promise<VFile> {
  return remark()
    .use(remarkDirective)
    .use(remarkInclude)
    .process(await vFile.read(filePath));
};

```

Code with file path with spaces and lines range:

```typescript file=code\ with\ spaces.ts#L11-L15
  return remark()
    .use(remarkDirective)
    .use([codeImport])
    .use(remarkInclude)
    .process(await vFile.read(filePath));
```

And code without file attribute:

```typescript
import { remark } from 'remark';
import * as vFile from 'to-vfile';
import remarkDirective from 'remark-directive';
import { remarkInclude } from '@it-service-npm/remark-include';
import type { VFile } from 'vfile';
```

Remark output:

Hello. I am an main markdown file with `::include` directive.

Hello. I am the included. Test for code file path rebasing:

```typescript file=../example.ts
import { remark } from 'remark';
import * as vFile from 'to-vfile';
import remarkDirective from 'remark-directive';
import { remarkInclude } from '@it-service-npm/remark-include';
import type { VFile } from 'vfile';

export async function remarkDirectiveUsingExample(
  filePath: string
): Promise<VFile> {
  return remark()
    .use(remarkDirective)
    .use(remarkInclude)
    .process(await vFile.read(filePath));
};

```

Code with file path with spaces and lines range:

```typescript file=subfolder1/code\ with\ spaces.ts#L11-L15
  return remark()
    .use(remarkDirective)
    .use([codeImport])
    .use(remarkInclude)
    .process(await vFile.read(filePath));
```

And code without file attribute:

```typescript
import { remark } from 'remark';
import * as vFile from 'to-vfile';
import remarkDirective from 'remark-directive';
import { remarkInclude } from '@it-service-npm/remark-include';
import type { VFile } from 'vfile';
```

*That* should do it!

API

Please, read the API reference.

License

MIT © Sergei S. Betke