https://github.com/streetsidesoftware/inject-markdown
Tool to inject files into markdown files.
https://github.com/streetsidesoftware/inject-markdown
Last synced: about 1 month ago
JSON representation
Tool to inject files into markdown files.
- Host: GitHub
- URL: https://github.com/streetsidesoftware/inject-markdown
- Owner: streetsidesoftware
- License: mit
- Created: 2022-12-25T12:11:45.000Z (over 2 years ago)
- Default Branch: main
- Last Pushed: 2025-04-27T07:23:04.000Z (about 1 month ago)
- Last Synced: 2025-04-27T08:25:14.513Z (about 1 month ago)
- Language: TypeScript
- Size: 1.1 MB
- Stars: 5
- Watchers: 2
- Forks: 0
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Funding: .github/FUNDING.yml
- License: LICENSE
- Security: SECURITY.md
Awesome Lists containing this project
README
# Markdown File Injector
[](https://github.com/streetsidesoftware/inject-markdown/actions)
[](https://github.com/streetsidesoftware/inject-markdown/actions)
[](https://codecov.io/gh/streetsidesoftware/inject-markdown)
[](https://coveralls.io/github/streetsidesoftware/inject-markdown)
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.
```markdown
```
```sh
npx inject-markdown README.md
```
## `--help`
```sh
npx inject-markdown --help
```
```
Usage: inject-markdown [options]
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 Output Directory
--cwd 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.
```markdown
```
```ts
export function sayHello(name: string): string {
return `Hello ${name}`;
}
```
## Import `json` as `jsonc`
### Syntax
```markdown
```
### Example
````markdown
```jsonc
{
"name": "Sample"
}
```
````
### Actual Result
```jsonc
{
"name": "Sample"
}
```
## Import Markdown as Code
It is also possible to inject markdown:
```markdown
```
```markdown
# Example
This is an example bit of markdown.
- first
- second
- third
```
## Import a section from a Markdown file
```markdown
or
```
> ## Chapter 3: Directives
>
> - `@@inject: [#heading]` and `@@inject-start: [#heading]` -- injects the contents of a markdown file.
> - `` -- 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: [#lang]`, `@@inject-start: [#lang]`, and `@@inject-code: [#lang]`
> - ``, `` -- 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
```
```
```typescript
async function version(): Promise {
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.
```markdown
```
> - first
> - second
> - third
### Example 2
Extract some lines from a code block in the source.
```markdown
```
> ```js
> export function sayGoodbye(name) {
> return `Goodbye ${name}`;
> }
> ```
---
Brought to you by
Street Side Software