The @it-service-npm/remark-include-code package allows you
to embed code files within your Markdown documents.
With this plugin, you can use ::include-code{file="./included.ts"}
syntax to include code to markdown.
Additional features:
- Attribute
languagefor select code language - Support for various code file encodings
with
encodingattribute (utf8by default). WithuseEditorConfigattribute or plugin parametercharsetproperty value from.editorconfigfile used forencoding - Boolean attribute
optional. This attribute prevents fatal errors from occurring when the file specified by thefileattribute does not exists - Deleting the last blank line
(with boolean
trimFinalNewlineattribute or plugin parameter) - Inserting a range of lines from a file
(with integer
fromLineandtoLineattributes) - Replacing tabs with a specified number (
tabWidthattribute) of spaces. WithuseEditorConfigattribute or plugin parametertab_widthproperty value from.editorconfigused fortabWidth - Removing the extra indentation for a block of code
with
trimExtraIndentattribute or parameter. (tabWidthvalue expected!)
There are two plugins: remarkIncludeCode (preferred) and remarkIncludeCodeSync.
Important
remark-directive plugin expected before
@it-service-npm/remark-include-code.
This package provides two plugins presets:
-
remarkIncludeCodePreset. This preset contains:remarkIncludeCoderemarkDirective
-
remarkIncludePresetSync. This preset contains:remarkIncludeCodeSyncremarkDirective
Tip
This plugin has two named entry points:
- ‘sync’ ('@it-service-npm/remark-include-code/sync’)
- ‘async’ ('@it-service-npm/remark-include-code/async’)
With sync and async plugin function and preset.
npm install --save-dev @it-service-npm/remark-include-codeThe @it-service-npm/remark-include-code package allows you
to embed code files within your Markdown documents.
Async plugin using example:
import { remark } from 'remark';
import * as vFile from 'to-vfile';
import remarkDirective from 'remark-directive';
import { remarkIncludeCode } from '@it-service-npm/remark-include-code/async';
import type { VFile } from 'vfile';
export async function remarkDirectiveUsingExample(
filePath: string
): Promise<VFile> {
return remark()
.use(remarkDirective)
.use(remarkIncludeCode)
.process(await vFile.read(filePath));
};
Source files:
main.md:
Hello. I am an main markdown file with `::include-code` directives.
::include-code{file=./included1.ts}
After first file.
::include-code{file="./included 2.ts"}
After second file.
_That_ should do it!
included1.ts:
export function functionInIncluded1File(): void {
console.info('file #1');
};
included 2.ts:
export function functionInIncluded2File(): void {
console.info('file #2');
};
Remark output:
Hello. I am an main markdown file with `::include-code` directives.
```
export function functionInIncluded1File(): void {
console.info('file #1');
};
```
After first file.
```
export function functionInIncluded2File(): void {
console.info('file #2');
};
```
After second file.
*That* should do it!
You can define the code language with language attribute.
Source files:
main.md:
Hello. I am an main markdown file with `::include-code` directive.
::include-code{file="./included1.ts" language="typescript"}
_That_ should do it!
included1.ts:
export function functionInIncluded1File(): void {
console.info('file #1');
};Remark output:
Hello. I am an main markdown file with `::include-code` directive.
```typescript
export function functionInIncluded1File(): void {
console.info('file #1');
};
```
*That* should do it!
You can define the code file encoding with encoding attribute.
Default — 'utf8'.
Important
With useEditorConfig attribute or plugin parameter
charset property value from .editorconfig file used for encoding
Source files:
main.md:
Hello. I am an main markdown file with `::include-code` directive.
::include-code{file="./included1.bat" language="batchfile" encoding="CP866"}
included1.bat:
echo "Кириллический текст"
Remark output:
Hello. I am an main markdown file with `::include-code` directive.
```batchfile
echo "Кириллический текст"
```
Or You can use charset property value for encoding from .editorconfig file with
useEditorConfig attribute or parameter.
main.md:
Hello. I am an main markdown file with `::include-code` directive.
::include-code{file="./included1.bat" language="batchfile"}
example.ts:
import { remark } from 'remark';
import * as vFile from 'to-vfile';
import remarkDirective from 'remark-directive';
import { remarkIncludeCode } from '@it-service-npm/remark-include-code/async';
import type { VFile } from 'vfile';
export async function remarkDirectiveUsingExample(
filePath: string
): Promise<VFile> {
return remark()
.use(remarkDirective)
.use(remarkIncludeCode, { useEditorConfig: true })
.process(await vFile.read(filePath));
};You can trim final newline with trimFinalNewline attribute.
Source files:
main.md:
Hello. I am an main markdown file with `::include-code` directive.
::include-code{file="./included1.ts" language="typescript" trimFinalNewline}
_That_ should do it!
included1.ts:
export function inFileWithFinalNewline(): void {
console.info('file #1');
};Remark output:
Hello. I am an main markdown file with `::include-code` directive.
```typescript
export function inFileWithFinalNewline(): void {
console.info('file #1');
};
```
*That* should do it!
And You can trim final newline for all ::include-code directives with
plugin options without trimFinalNewline attribute.
Remark settings (.remarkrc.mjs):
import remarkDirective from 'remark-directive';
import { remarkIncludeCode } from '@it-service-npm/remark-include-code/async';
export default {
plugins: [
remarkDirective,
[remarkIncludeCode, {
trimFinalNewline: true
}],
],
settings: {
bullet: '-'
}
}or without config file:
import { remark } from 'remark';
import * as vFile from 'to-vfile';
import remarkDirective from 'remark-directive';
import { remarkIncludeCode } from '@it-service-npm/remark-include-code/async';
import type { VFile } from 'vfile';
export async function remarkDirectiveUsingExample(
filePath: string
): Promise<VFile> {
return remark()
.use(remarkDirective)
.use(remarkIncludeCode, {
trimFinalNewline: true
})
.process(await vFile.read(filePath));
};Important
Package presets remarkIncludeCodePreset and remarkIncludePresetSync
enables trimFinalNewline setting by default.
You can insert a specified range of lines from a file
with fromLine and toLine attributes.
Source files:
main.md:
Hello. I am an main markdown file with `::include-code` directive.
::include-code{file="./included.ts" language="typescript" fromLine=9 toLine=-1}
::include-code{file="./included.ts" language="typescript" fromLine=9 toLine=11}
_That_ should do it!
included.ts:
import { remark } from 'remark';
import * as vFile from 'to-vfile';
import { remarkIncludeCodePreset } from '@it-service-npm/remark-include-code/async';
import type { VFile } from 'vfile';
export async function remarkDirectiveUsingExample(
filePath: string
): Promise<VFile> {
return remark()
.use(remarkIncludeCodePreset)
.process(await vFile.read(filePath));
};Remark output:
Hello. I am an main markdown file with `::include-code` directive.
```typescript
return remark()
.use(remarkIncludeCodePreset)
.process(await vFile.read(filePath));
```
```typescript
return remark()
.use(remarkIncludeCodePreset)
.process(await vFile.read(filePath));
```
*That* should do it!
::include-code replace tabs in code with spaces if tabWidth attribute specified.
Important
With useEditorConfig attribute or plugin parameter
tab_width property value from .editorconfig
used for tabWidth.
Source files:
main.md:
Hello. I am an main markdown file with `::include-code` directive.
::include-code{file="./example.json" language="json" tabWidth=4}example.json:
{
"extends": "./tsconfig.json",
"include": [
"./src"
],
"compilerOptions": {
"composite": true,
"noEmit": false,
"allowImportingTsExtensions": false,
"outDir": "./dist",
"rootDir": "./src"
}
}Remark output:
Hello. I am an main markdown file with `::include-code` directive.
```json
{
"extends": "./tsconfig.json",
"include": [
"./src"
],
"compilerOptions": {
"composite": true,
"noEmit": false,
"allowImportingTsExtensions": false,
"outDir": "./dist",
"rootDir": "./src"
}
}
```Or You can use tab_width property value from .editorconfig file with
useEditorConfig attribute or parameter.
main.md:
Hello. I am an main markdown file with `::include-code` directive.
::include-code{file="./example.json" language="json"}example.ts:
import { remark } from 'remark';
import * as vFile from 'to-vfile';
import remarkDirective from 'remark-directive';
import { remarkIncludeCode } from '@it-service-npm/remark-include-code/async';
import type { VFile } from 'vfile';
export async function remarkDirectiveUsingExample(
filePath: string
): Promise<VFile> {
return remark()
.use(remarkDirective)
.use(remarkIncludeCode, { useEditorConfig: true })
.process(await vFile.read(filePath));
};You can remove extra indentation with trimExtraIndent attribute or parameter
(for example, if You insert a specified range of lines from a file
with fromLine and toLine attributes).
Important
tabWidth value expected
(or tab_width property value from .editorconfig
with useEditorConfig attribute or parameter).
Source files:
main.md:
Hello. I am an main markdown file with `::include-code` directive.
Code fragment with extra indent,
removed with `trimExtraIndent` attribute (two spaces):
::include-code{file="./included.ts" language="typescript" fromLine=9 toLine=-1 tabWidth=2 trimExtraIndent}
Code fragment without extra indent:
::include-code{file="./included.ts" language="typescript" fromLine=6 tabWidth=2 trimExtraIndent}
included.ts:
import { remark } from 'remark';
import * as vFile from 'to-vfile';
import { remarkIncludeCodePreset } from '@it-service-npm/remark-include-code/async';
import type { VFile } from 'vfile';
export async function remarkDirectiveUsingExample(
filePath: string
): Promise<VFile> {
return remark()
.use(remarkIncludeCodePreset)
.process(await vFile.read(filePath));
};Remark output:
Hello. I am an main markdown file with `::include-code` directive.
Code fragment with extra indent,
removed with `trimExtraIndent` attribute (two spaces):
```typescript
return remark()
.use(remarkIncludeCodePreset)
.process(await vFile.read(filePath));
```
Code fragment without extra indent:
```typescript
export async function remarkDirectiveUsingExample(
filePath: string
): Promise<VFile> {
return remark()
.use(remarkIncludeCodePreset)
.process(await vFile.read(filePath));
};
```
Please, read the API reference.
Do not edit this file. It is a report generated by API Extractor.
import type { Plugin } from 'unified';
import type { Preset } from 'unified';
import type { Root } from 'mdast';
// @public
export interface IParameters {
readonly optional?: boolean;
readonly trimExtraIndent?: boolean;
readonly trimFinalNewline?: boolean;
readonly useEditorConfig?: boolean;
}
// @public
export const remarkIncludeCode: Plugin<[IParameters?], Root>;
// @public
const remarkIncludeCodePreset: Preset;
export default remarkIncludeCodePreset;
export { remarkIncludeCodePreset }
// @public
export const remarkIncludeCodePresetSync: Preset;
// @public
export const remarkIncludeCodeSync: Plugin<[IParameters?], Root>;