npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

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 commands:

$ echo "My home directory is: $HOME"

My home directory is: /Users/me

In some scenarios, passing system environment to commands 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 | commandbash, 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.

Similar Projects

  • embedme - embed source files into markdown code blocks
  • mdsh - a similar tool but for the Rust ecosystem