Markdown File Injector

A Command line tool to inject files into Markdown files.

Justification

Sometimes it is necessary to assemble content into a static markdown file like README.md. Manually copying and pasting content leads to duplication making it difficult to keep things in sync.

Usage

Use HTML comments to mark where content will be injected.

<!--- @@inject: fixtures/sample-src.md --->

npx inject-markdown README.md

--help

npx inject-markdown --help

Usage: inject-markdown [options] <files...>

Inject file content into markdown files.

Arguments:
  files                 Files to scan for injected content.

Options:
  --no-must-find-files  No error if files are not found.
  --output-dir <dir>    Output Directory
  --cwd <dir>           Current Directory
  --clean               Remove the injected content.
  --verbose             Verbose output.
  --silent              Only output errors.
  --no-stop-on-errors   Do not stop if an error occurs.
  --write-on-error      write the file even if an injection error occurs.
  --color               Force color.
  --no-color            Do not use color.
  --no-summary          Do not show the summary
  --dry-run             Process the files, but do not write.
  -V, --version         output the version number
  -h, --help            display help for command

How to use Injections

Import Code

All non-markdown files will be imported as a code block.

<!--- @@inject: code.ts --->

export function sayHello(name: string): string {
  return `Hello ${name}`;
}

Import json as jsonc

Syntax

<!--- @@inject-code: sample.json#lang=jsonc --->

Example

<!--- @@inject-code: sample.json#lang=jsonc --->

```jsonc
{
  "name": "Sample"
}
```

<!--- @@inject-end: sample.json#lang=jsonc --->

Actual Result

{
  "name": "Sample"
}

Import Markdown as Code

It is also possible to inject markdown:

<!--- @@inject-code: example.md --->

# Example

This is an example bit of markdown.

- first
- second
- third

Import a section from a Markdown file

<!--- @@inject: chapters.md#Chapter 3: Directives --->

or

<!--- @@inject: chapters.md#heading=Chapter 3: Directives --->

Chapter 3: Directives

• @@inject: <markdown_file.md>[#heading] and @@inject-start: <markdown_file.md>[#heading] -- injects the contents of a markdown file.
  • <markdown_file.md> -- the file to import
  • heading -- optional heading to extract.
  • code -- optional embed as a markdown code block
  • quote -- optional embed as a block quote.
• @@inject: <non-markdown-file>[#lang], @@inject-start: <non-markdown-file>[#lang], and @@inject-code: <file>[#lang]
  • <non-markdown-file>, <file> -- the file to import
  • lang -- optional language to use for the code bock.
  • quote -- optional embed as a block quote.

Import from lines from GitHub

<!--- @@inject: https://github.com/streetsidesoftware/inject-markdown/blob/d7de2f5fe/src/app.mts#L15-L19 --->

async function version(): Promise<string> {
    const pathSelf = fileURLToPath(import.meta.url);
    const pathPackageJson = path.join(path.dirname(pathSelf), '../package.json');
    const packageJson = JSON.parse(await fs.readFile(pathPackageJson, 'utf8'));
    return (typeof packageJson === 'object' && packageJson?.version) || '0.0.0';

Per Injections Options

The hash # portion of the file URL is used to set injection options. Each option is separated by a &.

Option	Code	Markdown	Description
heading	❌	✅	Used to extract a section from a markdown file.
code	❌	✅	Convert the injected markdown into a Code Block.
lang	✅	✅	Used to set the language of the code block.
quote	✅	✅	Used to inject the file as a block quote.
L1-L10	✅	✅	Used to inject only specified lines from the source file.

Example 1

Extract a few lines from a Markdown files and quote them.

<!--- @@inject: example.md#L5-L7&quote --->

• first
• second
• third

Example 2

Extract some lines from a code block in the source.

<!--- @@inject-code: code.md#L24-L26&lang=js --->

export function sayGoodbye(name) {
  return `Goodbye ${name}`;
}

---

Brought to you by Street Side Software