codinj

Inject code snippets

Use codinj CLI to build documentation files by injecting code snippets.

Imagine this use case:

you have a code snippet, you want to include it in the README.md of your repo.

The code lives in its own file which can be indented, linted, even tested as any other source file. Then it is automatically injected in your documentation.

First of all you need to add markers to your source code.

Launch the codinj CLI passing the file or folder to process.

codinj path/to/file/or/folder

Or call it via API in your script.

import { processPath } from 'codinj'

await processPath('path/to/file/or/folder')

Markers are read by codinj to connect a source file to a snippet source.

Markers have the form

START|END snippet <JSON_OBJECT>

Where JSON_OBJECT is a flat JSON object on a single line, and in some cases it can be omitted.

Start with a marker like this:

START snippet {"file":"relative/path/to/code/snippet"}
END snippet

Optionally, but almost always necessary, add instructions about how to surround the snippet. Ah, and of course, markers will be inside comments. So for example in a README.md file

<!-- START snippet {"file":"examples/hello_world.ts","surround":"```ts"} -->
<!-- END snippet {"surround":"```"} -->

By default, the whole snippet file will be injected. Optionally, snippet files can also have markers to indicate which part of the snippet to include, like:

START snippet

... code to include ...

END snippet

MIT