markdown-inject
v4.1.7
Published
Add file or command output to markdown documents.
Downloads
39
Readme
markdown-inject
Add file or command output to markdown documents.
Installation
markdown-inject
is written in TypeScript and distributed as a node module on the npm ecosystem. It exposes a bin executable, making it a command line offering.
Download and invoke in one command:
npx markdown-inject
Local npm installation:
npm install markdown-inject --save-dev
or with Yarn:
yarn add markdown-inject --dev
Optionally, wire up markdown-inject
to a git pre-commit hook tool like husky to automatically update markdown injection as part of your workflow.
Usage
Note:
markdown-inject
takes no action during pull request builds in CI.
Usage: markdown-inject [options] <glob pattern | -a>
Examples:
$ npx markdown-inject -a
$ npx markdown-inject 'README.md'
$ npx markdown-inject './**/*.{md,mdx}'
Add file or command output to markdown documents.
Options:
-v, --version output the version number
-a, --all applies a globPattern of './**/*.md'
(default: false)
-b, --block-prefix <prefix> specifies the prefix for START and END HTML
comment blocks (default: "CODEBLOCK")
-n, --no-follow-symbolic-links prevents globs from following symlinks
-q, --quiet emits no console log statements (default:
false)
-e, --no-system-environment prevents "command"s from receiving system
environment
-h, --help display help for command
markdown-inject
expands a given glob for markdown files. Then it discovers the below CODEBLOCK
HTML or MDX (as shown in CONTRIBUTING.mdx) comments within each markdown file, performs the appropriate action (in this case, reading another local file), and writes content back into the markdown file:
<!-- CODEBLOCK_START {"value": ".nvmrc"} -->
<!-- CODEBLOCK_END -->
<!-- CODEBLOCK_START {"value": ".nvmrc"} -->
<!-- prettier-ignore -->
~~~~~~~~~~bash
File: .nvmrc
v20.10.0
~~~~~~~~~~
<!-- CODEBLOCK_END -->
Output is written between the CODEBLOCK_START and CODEBLOCK_END comments. Output includes:
- A prettier ignore comment introducing the output so that prettier does not further alter existing code.
- A markdown codeblock is opened with the language specified via configuration.
- The
<type>: <value>
line is included by default, labeling the output. - The command or file output.
Executing commands follows a similar syntax:
<!-- CODEBLOCK_START {"value": "echo hello world", "type": "command"} -->
<!-- prettier-ignore -->
~~~~~~~~~~bash
$ echo hello world
hello world
~~~~~~~~~~
<!-- CODEBLOCK_END -->
You can hide the <type>: <value>
comment from the generated output too:
<!-- CODEBLOCK_START {"value": "echo hello world", "type": "command", "hideValue": true} -->
<!-- prettier-ignore -->
~~~~~~~~~~bash
hello world
~~~~~~~~~~
<!-- CODEBLOCK_END -->
Environment
System environment is automatically passed to command
s:
$ echo "My home directory is: $HOME"
My home directory is: /Users/me
In some scenarios, passing system environment to command
s may be undesirable. This functionality can be disabled using the --no-system-environment
CLI flag. This creates output such as:
$ echo "My password is: $MY_PASSWORD"
My password is:
Sometimes commands need a little extra nudging via environment to receive a usable output. Environment variables can be added using the environment
key:
<!--
CODEBLOCK_START
{
"type": "command",
"value": "node ./deploy.js --dry-run",
"environment": {
"SKIP_PRECHECK": "true"
}
}
-->
<!-- CODEBLOCK_END -->
The environment
key can also be used to overwrite system environment variables with example values:
<!--
CODEBLOCK_START
{
"type": "command",
"value": "echo \"My password is: $MY_PASSWORD\"",
"environment": {
"MY_PASSWORD": "<insert password here>"
}
}
-->
<!-- prettier-ignore -->
~~~~~~~~~~bash
$ echo "My password is: $MY_PASSWORD"
My password is: <insert password here>
~~~~~~~~~~
<!-- CODEBLOCK_END -->
Environment variables with values which follow bash variable naming rules will be substituted into the command
environment whether or not --no-system-environment
is enabled. This can be useful for re-introducing necessary environment variables that would be omitted by --no-system-environment
:
<!--
CODEBLOCK_START
{
"type": "command",
"value": "echo \"My home directory is: $HOME\nMy password is: $MY_PASSWORD\"",
"environment": {
"HOME": "$HOME"
}
}
-->
<!-- prettier-ignore -->
~~~~~~~~~~bash
$ echo "My home directory is: $HOME
My password is: $MY_PASSWORD"
My home directory is: /Users/me
My password is:
~~~~~~~~~~
<!-- CODEBLOCK_END -->
Codeblock Configuration
The CODEBLOCK_START
HTML comment config block has the following properties:
| Name | Type | Required | Default | Description |
| ------------- | --------------------- | -------- | --------------------------------------------------- | -------------------------------------------------------------- |
| value
| string
| true
| | Command to execute or file to retrieve |
| environment
| object
| false
| {}
| Run command
executions with the given environment values |
| hideValue
| boolean
| false
| false
| Do not display File: foo.js
or $ npx foo
on the first line |
| language
| string
| false
| command
: bash
, file
: File extension | Syntax highlighting language |
| trim
| boolean
| false
| true
| Trim whitespace from the ends of file or command output |
| type
| 'command' \| 'file'
| false
| 'file'
| Type of execution |
Contributing
See CONTRIBUTING.md for more information.