{"id":28098635,"url":"https://github.com/target/markdown-inject","last_synced_at":"2025-10-27T22:40:14.010Z","repository":{"id":39626652,"uuid":"388131918","full_name":"target/markdown-inject","owner":"target","description":"Add file or command output to markdown documents.","archived":false,"fork":false,"pushed_at":"2025-05-31T19:17:45.000Z","size":1237,"stargazers_count":12,"open_issues_count":30,"forks_count":3,"subscribers_count":7,"default_branch":"main","last_synced_at":"2025-07-11T03:29:40.432Z","etag":null,"topics":["cli","documentation-generator","markdown"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/target.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.mdx","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2021-07-21T13:50:24.000Z","updated_at":"2025-04-29T06:05:34.000Z","dependencies_parsed_at":"2023-12-21T19:43:01.063Z","dependency_job_id":"6899169c-fe74-49e9-8dd9-84176938a7cc","html_url":"https://github.com/target/markdown-inject","commit_stats":{"total_commits":67,"total_committers":6,"mean_commits":"11.166666666666666","dds":0.5671641791044777,"last_synced_commit":"00e8e22975859729b8ff4f1411d8a1a5e8f454fd"},"previous_names":[],"tags_count":28,"template":false,"template_full_name":null,"purl":"pkg:github/target/markdown-inject","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/target%2Fmarkdown-inject","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/target%2Fmarkdown-inject/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/target%2Fmarkdown-inject/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/target%2Fmarkdown-inject/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/target","download_url":"https://codeload.github.com/target/markdown-inject/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/target%2Fmarkdown-inject/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":265121267,"owners_count":23714500,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cli","documentation-generator","markdown"],"created_at":"2025-05-13T17:58:29.404Z","updated_at":"2025-10-27T22:40:08.978Z","avatar_url":"https://github.com/target.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# markdown-inject\n\nAdd file or command output to markdown documents.\n\n\u003cimg src=\"./demo.gif\" alt=\"Functionality Demo\" height=\"600\" /\u003e\n\n## Installation\n\n`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.\n\nDownload and invoke in one command:\n\n```\nnpx markdown-inject\n```\n\nLocal npm installation:\n\n```\nnpm install markdown-inject --save-dev\n```\n\nor with Yarn:\n\n```\nyarn add markdown-inject --dev\n```\n\nOptionally, 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.\n\n## Usage\n\n\u003e Note: `markdown-inject` takes no action during pull request builds in CI.\n\n\u003c!--\n  CODEBLOCK_START\n  {\n    \"type\": \"command\",\n    \"value\": \"npm run --silent markdown-inject -- --help\",\n    \"hideValue\": true\n  }\n--\u003e\n\u003c!-- prettier-ignore --\u003e\n~~~~~~~~~~bash\nUsage: markdown-inject [options] \u003cglob pattern | -a\u003e\n\nExamples:\n  $ npx markdown-inject -a\n  $ npx markdown-inject 'README.md'\n  $ npx markdown-inject './**/*.{md,mdx}'\n\nAdd file or command output to markdown documents.\n\nOptions:\n  -v, --version                   output the version number\n  -a, --all                       applies a globPattern of './**/*.md'\n                                  (default: false)\n  -b, --block-prefix \u003cprefix\u003e     specifies the prefix for START and END HTML\n                                  comment blocks (default: \"CODEBLOCK\")\n  -n, --no-follow-symbolic-links  prevents globs from following symlinks\n  -q, --quiet                     emits no console log statements (default:\n                                  false)\n  -e, --no-system-environment     prevents \"command\"s from receiving system\n                                  environment\n  -h, --help                      display help for command\n~~~~~~~~~~\n\n\u003c!-- CODEBLOCK_END --\u003e\n\n`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:\n\n\u003c!-- CODEBLOCK_START_USAGE {\"ignore\": true} --\u003e\n\n```\n\u003c!-- CODEBLOCK_START {\"value\": \".nvmrc\"} --\u003e\n\u003c!-- CODEBLOCK_END --\u003e\n```\n\n\u003c!-- CODEBLOCK_END_USAGE --\u003e\n\n```\n\u003c!-- CODEBLOCK_START {\"value\": \".nvmrc\"} --\u003e\n\u003c!-- prettier-ignore --\u003e\n~~~~~~~~~~bash\nFile: .nvmrc\n\nv20.10.0\n~~~~~~~~~~\n\n\u003c!-- CODEBLOCK_END --\u003e\n```\n\nOutput is written between the CODEBLOCK_START and CODEBLOCK_END comments. Output includes:\n\n- A prettier ignore comment introducing the output so that prettier does not further alter existing code.\n- A markdown codeblock is opened with the language specified via configuration.\n- The `\u003ctype\u003e: \u003cvalue\u003e` line is included by default, labeling the output.\n- The command or file output.\n\nExecuting commands follows a similar syntax:\n\n```\n\u003c!-- CODEBLOCK_START {\"value\": \"echo hello world\", \"type\": \"command\"} --\u003e\n\u003c!-- prettier-ignore --\u003e\n~~~~~~~~~~bash\n$ echo hello world\n\nhello world\n~~~~~~~~~~\n\n\u003c!-- CODEBLOCK_END --\u003e\n```\n\nYou can hide the `\u003ctype\u003e: \u003cvalue\u003e` comment from the generated output too:\n\n```\n\u003c!-- CODEBLOCK_START {\"value\": \"echo hello world\", \"type\": \"command\", \"hideValue\": true} --\u003e\n\u003c!-- prettier-ignore --\u003e\n~~~~~~~~~~bash\nhello world\n~~~~~~~~~~\n\n\u003c!-- CODEBLOCK_END --\u003e\n```\n\n### Environment\n\nSystem environment is automatically passed to `command`s:\n\n\u003c!--\n  CODEBLOCK_START\n  {\n    \"type\": \"command\",\n    \"value\": \"echo \\\"My home directory is: $HOME\\\"\",\n    \"environment\": {\n      \"comment\": \"Be careful with these or you'll leak your actual home dir\",\n      \"HOME\": \"/Users/me\"\n    }\n  }\n--\u003e\n\u003c!-- prettier-ignore --\u003e\n~~~~~~~~~~bash\n$ echo \"My home directory is: $HOME\"\n\nMy home directory is: /Users/me\n~~~~~~~~~~\n\n\u003c!-- CODEBLOCK_END --\u003e\n\nIn 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:\n\n\u003c!-- CODEBLOCK_START\n  {\n    \"type\": \"command\",\n    \"value\": \"echo \\\"My password is: $MY_PASSWORD\\\"\",\n    \"environment\": {\n      \"comment\": \"just in case?\",\n      \"MY_PASSWORD\": \"\"\n    }\n  }\n--\u003e\n\u003c!-- prettier-ignore --\u003e\n~~~~~~~~~~bash\n$ echo \"My password is: $MY_PASSWORD\"\n\nMy password is:\n~~~~~~~~~~\n\n\u003c!-- CODEBLOCK_END --\u003e\n\nSometimes commands need a little extra nudging via environment to receive a usable output. Environment variables can be added using the `environment` key:\n\n\u003c!-- CODEBLOCK_START_EXAMPLE_PASSED_ENVIRONMENT {\"ignore\": true} --\u003e\n\n```\n\u003c!--\n  CODEBLOCK_START\n  {\n    \"type\": \"command\",\n    \"value\": \"node ./deploy.js --dry-run\",\n    \"environment\": {\n      \"SKIP_PRECHECK\": \"true\"\n    }\n  }\n--\u003e\n\u003c!-- CODEBLOCK_END --\u003e\n```\n\n\u003c!-- CODEBLOCK_END_EXAMPLE_PASSED_ENVIRONMENT --\u003e\n\nThe `environment` key can also be used to overwrite system environment variables with example values:\n\n```\n\u003c!--\n  CODEBLOCK_START\n  {\n    \"type\": \"command\",\n    \"value\": \"echo \\\"My password is: $MY_PASSWORD\\\"\",\n    \"environment\": {\n      \"MY_PASSWORD\": \"\u003cinsert password here\u003e\"\n    }\n  }\n--\u003e\n\u003c!-- prettier-ignore --\u003e\n~~~~~~~~~~bash\n$ echo \"My password is: $MY_PASSWORD\"\n\nMy password is: \u003cinsert password here\u003e\n~~~~~~~~~~\n\n\u003c!-- CODEBLOCK_END --\u003e\n```\n\nEnvironment 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`:\n\n\u003c!-- CODEBLOCK_START_EXAMPLE_MAP_ENV {\"ignore\": true} --\u003e\n\n```\n\u003c!--\n  CODEBLOCK_START\n  {\n    \"type\": \"command\",\n    \"value\": \"echo \\\"My home directory is: $HOME\\nMy password is: $MY_PASSWORD\\\"\",\n    \"environment\": {\n      \"HOME\": \"$HOME\"\n    }\n  }\n--\u003e\n\u003c!-- prettier-ignore --\u003e\n~~~~~~~~~~bash\n$ echo \"My home directory is: $HOME\nMy password is: $MY_PASSWORD\"\n\nMy home directory is: /Users/me\nMy password is:\n~~~~~~~~~~\n\n\u003c!-- CODEBLOCK_END --\u003e\n```\n\n\u003c!-- CODEBLOCK_END_EXAMPLE_MAP_ENV --\u003e\n\n## Codeblock Configuration\n\nThe `CODEBLOCK_START` HTML comment config block has the following properties:\n\n| Name          | Type                  | Required | Default                                             | Description                                                    |\n| ------------- | --------------------- | -------- | --------------------------------------------------- | -------------------------------------------------------------- |\n| `value`       | `string`              | `true`   |                                                     | Command to execute or file to retrieve                         |\n| `environment` | `object`              | `false`  | `{}`                                                | Run `command` executions with the given environment values     |\n| `hideValue`   | `boolean`             | `false`  | `false`                                             | Do not display `File: foo.js` or `$ npx foo` on the first line |\n| `language`    | `string`              | `false`  | `command`:\u0026nbsp;`bash`, `file`:\u0026nbsp;File extension | Syntax highlighting language                                   |\n| `trim`        | `boolean`             | `false`  | `true`                                              | Trim whitespace from the ends of file or command output        |\n| `type`        | `'command' \\| 'file'` | `false`  | `'file'`                                            | Type of execution                                              |\n\n## Contributing\n\nSee [CONTRIBUTING.md](/CONTRIBUTING.md) for more information.\n\n## Similar Projects\n\n- [embedme](https://github.com/zakhenry/embedme) - embed source files into markdown code blocks\n- [mdsh](https://github.com/zimbatm/mdsh) - a similar tool but for the Rust ecosystem\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftarget%2Fmarkdown-inject","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftarget%2Fmarkdown-inject","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftarget%2Fmarkdown-inject/lists"}