streetsidesoftwareMarkdown 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 importheading-- optional heading to extract.code-- optional embed as amarkdowncode 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.
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"e --->
- 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