markdown-code-example-insertion

Syncs markdown documentation with code examples.

Install

Via npm:

npm i -D markdown-code-example-inserter

It's recommended to install this package as a dev dependency as it is a build-step operation.

Usage

Markdown files

Add an HTML comment that starts with the following text: example-link:. Then after that text, include a file path to the example file:

<!-- example-link: src/readme-examples/do-thing.ts -->

Here's an example from the GitHub repo. And here is the same file with the code examples inserted.

CLI

npx md-code file1.md file2.md [...moreFiles]

Any of the file names can be a glob. Put the glob in quotes if you wish to prevent your shell from expanding it (this package will expand the glob):

npx md-code "./*.md"

Check only

Use --check.

Check if the given files are updated, don't write anything.

npx md-code file1.md --check

Force an index file

Use --index.

Force an index file for imports that should be rewritten with your package name:

npx md-code file1.md --index path/to/index.ts file2.md [...moreFiles]

The index file is used to replace relative imports with package name imports. Like changing import from '../../index' to import from 'my-package'.

Ignore a pattern

Use --ignore.

npx md-code "./**/*.md" --ignore "./test-files/**/*"

Multiple --ignore patterns can be used:

npx md-code "./**/*.md" --ignore "./test-files/**/*" -ignore "./test-files/**/*"

node_modules is automatically ignored.

Turn off logging

Use --silent

npx md-code --silent file1.md