https://github.com/target/markdown-inject
Add file or command output to markdown documents.
https://github.com/target/markdown-inject
cli documentation-generator markdown
Last synced: 7 months ago
JSON representation
Add file or command output to markdown documents.
- Host: GitHub
- URL: https://github.com/target/markdown-inject
- Owner: target
- License: other
- Created: 2021-07-21T13:50:24.000Z (almost 5 years ago)
- Default Branch: main
- Last Pushed: 2025-05-31T19:17:45.000Z (12 months ago)
- Last Synced: 2025-07-11T03:29:40.432Z (10 months ago)
- Topics: cli, documentation-generator, markdown
- Language: TypeScript
- Homepage:
- Size: 1.18 MB
- Stars: 12
- Watchers: 7
- Forks: 3
- Open Issues: 30
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.mdx
- License: LICENSE
Awesome Lists containing this project
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](https://github.com/typicode/husky) to automatically update markdown injection as part of your workflow.
## Usage
> Note: `markdown-inject` takes no action during pull request builds in CI.
~~~~~~~~~~bash
Usage: markdown-inject [options]
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 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](./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:
```
```
```
~~~~~~~~~~bash
File: .nvmrc
v20.10.0
~~~~~~~~~~
```
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 `: ` line is included by default, labeling the output.
- The command or file output.
Executing commands follows a similar syntax:
```
~~~~~~~~~~bash
$ echo hello world
hello world
~~~~~~~~~~
```
You can hide the `: ` comment from the generated output too:
```
~~~~~~~~~~bash
hello world
~~~~~~~~~~
```
### Environment
System environment is automatically passed to `command`s:
~~~~~~~~~~bash
$ 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](#usage). This creates output such as:
~~~~~~~~~~bash
$ 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:
```
```
The `environment` key can also be used to overwrite system environment variables with example values:
```
~~~~~~~~~~bash
$ echo "My password is: $MY_PASSWORD"
My password is:
~~~~~~~~~~
```
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`:
```
~~~~~~~~~~bash
$ echo "My home directory is: $HOME
My password is: $MY_PASSWORD"
My home directory is: /Users/me
My password is:
~~~~~~~~~~
```
## 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](/CONTRIBUTING.md) for more information.
## Similar Projects
- [embedme](https://github.com/zakhenry/embedme) - embed source files into markdown code blocks
- [mdsh](https://github.com/zimbatm/mdsh) - a similar tool but for the Rust ecosystem