A Command line tool to inject files into Markdown files.
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.
Use HTML comments to mark where content will be injected.
<!--- @@inject: fixtures/sample-src.md --->
npx inject-markdown README.md
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
All non-markdown files will be imported as a code block.
<!--- @@inject: code.ts --->
export function sayHello(name: string): string {
return `Hello ${name}`;
}
<!--- @@inject-code: sample.json#lang=jsonc --->
<!--- @@inject-code: sample.json#lang=jsonc --->
```jsonc
{
"name": "Sample"
}
```
<!--- @@inject-end: sample.json#lang=jsonc --->
{
"name": "Sample"
}
It is also possible to inject markdown:
<!--- @@inject-code: example.md --->
# Example
This is an example bit of markdown.
- first
- second
- third
<!--- @@inject: chapters.md#Chapter 3: Directives --->
or
<!--- @@inject: chapters.md#heading=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 importheading
-- optional heading to extract.code
-- optional embed as amarkdown
code blockquote
-- 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 importlang
-- optional language to use for the code bock.quote
-- optional embed as a block quote.
<!--- @@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';
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. |
Extract a few lines from a Markdown files and quote them.
<!--- @@inject: example.md#L5-L7"e --->
- first
- second
- third
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