Package Exports

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (inject-markdown) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

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 Logo Street Side Software

inject-markdown