remark-plugin-code-snippets
Remark plugin for creating sourcing code snippets from local files.
Installation
# npm
npm install remark-plugin-code-snippets
# yarn
yarn add remark-plugin-code-snippetsOptions
| Option | Type | Default | Description |
|---|---|---|---|
basePath |
string |
base path for sourcing files. If not defined, sources files relative to the file they're referenced from. | |
normalizeIndent |
bool |
true |
normalize snippets to smallest indentation level while keeping relative indentation intact |
basePath
If specified, basePath should be relative to the project root; file paths are then sourced relative to basePath. If not specified, files paths are sourced relative to the file they're referenced from
trim
Leading and trailing lines of purely whitespace can be trimmed out based on how this option is configured.
normalizeIndent
Code snippets can have their indentation normalized in the code block while retaining relative indentation. This is particularly useful when sourcing only sections of a file.
Warning: may have unexpected behavior in the case of a mix of both tabs and spaces.
Syntax
Basic Usage
Source a file into a code block using file="path/to/file/from/basepath" in the metastring of the code block.
Both single quotes and double quotes can be used, but they must match and one of them must be present.
# valid
```md file='README.md'
```
# also valid
```md file="README.md"
```
Embedding with other text
All instances of the string {{ FILE }} in the code block's contents are replaced by the file contents. This string must be on its own line, with nothing else but leading and/or trailing whitespace.
Sourcing parts of a file
Append :#-# to specify a range of lines to source from the file, rather than the entirety of the file. Leading zeros are not recognized. To source only a single line, omit the ending -#. To source from a line to the end of the file, omit the ending #.
```js file="index.js":2
```
```js file="index.js":2-3
{{ FILE:1 }}
{{ FILE }}
{{ FILE:4- }}
```
Inferring language
Use the require('remark-plugin-code-snippets).inferLanguage Remark plugin to be able to specify the file to be sourced in the node's language and infer the syntax highlighting for it based on the file extension.