{"id":19911036,"url":"https://github.com/streetsidesoftware/inject-markdown","last_synced_at":"2025-05-03T03:30:57.399Z","repository":{"id":65146965,"uuid":"582038183","full_name":"streetsidesoftware/inject-markdown","owner":"streetsidesoftware","description":"Tool to inject files into markdown files.","archived":false,"fork":false,"pushed_at":"2025-04-27T07:23:04.000Z","size":1154,"stargazers_count":5,"open_issues_count":1,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-04-27T08:25:14.513Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/streetsidesoftware.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null},"funding":{"github":["streetsidesoftware"],"patreon":null,"open_collective":null,"ko_fi":null,"tidelift":null,"community_bridge":null,"liberapay":null,"issuehunt":null,"otechie":null,"lfx_crowdfunding":null,"custom":null}},"created_at":"2022-12-25T12:11:45.000Z","updated_at":"2025-04-27T07:21:06.000Z","dependencies_parsed_at":"2024-03-24T13:26:55.871Z","dependency_job_id":"37bebfc3-cb49-450b-942c-558117a9770d","html_url":"https://github.com/streetsidesoftware/inject-markdown","commit_stats":{"total_commits":126,"total_committers":5,"mean_commits":25.2,"dds":0.626984126984127,"last_synced_commit":"7da730462bd688b6733870e831a52253568eefaa"},"previous_names":[],"tags_count":15,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/streetsidesoftware%2Finject-markdown","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/streetsidesoftware%2Finject-markdown/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/streetsidesoftware%2Finject-markdown/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/streetsidesoftware%2Finject-markdown/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/streetsidesoftware","download_url":"https://codeload.github.com/streetsidesoftware/inject-markdown/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252137520,"owners_count":21700228,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-12T21:23:13.804Z","updated_at":"2025-05-03T03:30:56.916Z","avatar_url":"https://github.com/streetsidesoftware.png","language":"TypeScript","funding_links":["https://github.com/sponsors/streetsidesoftware"],"categories":[],"sub_categories":[],"readme":"# Markdown File Injector\n\n[![unit tests](https://github.com/streetsidesoftware/inject-markdown/actions/workflows/test.yml/badge.svg?branch=main)](https://github.com/streetsidesoftware/inject-markdown/actions)\n[![lint](https://github.com/streetsidesoftware/inject-markdown/actions/workflows/lint.yml/badge.svg?branch=main)](https://github.com/streetsidesoftware/inject-markdown/actions)\n[![codecov](https://codecov.io/gh/streetsidesoftware/inject-markdown/branch/main/graph/badge.svg?token=Dr4fi2Sy08)](https://codecov.io/gh/streetsidesoftware/inject-markdown)\n[![Coverage Status](https://coveralls.io/repos/github/streetsidesoftware/inject-markdown/badge.svg?branch=main)](https://coveralls.io/github/streetsidesoftware/inject-markdown)\n\nA Command line tool to inject files into Markdown files.\n\n## Justification\n\nSometimes it is necessary to assemble content into a static markdown file like `README.md`.\nManually copying and pasting content leads to duplication making it difficult to keep things in sync.\n\n## Usage\n\nUse HTML comments to mark where content will be injected.\n\n```markdown\n\u003c!--- @@inject: fixtures/sample-src.md ---\u003e\n```\n\n```sh\nnpx inject-markdown README.md\n```\n\n## `--help`\n\n```sh\nnpx inject-markdown --help\n```\n\n\u003c!--- @@inject: content/help.txt ---\u003e\n\n```\nUsage: inject-markdown [options] \u003cfiles...\u003e\n\nInject file content into markdown files.\n\nArguments:\n  files                 Files to scan for injected content.\n\nOptions:\n  --no-must-find-files  No error if files are not found.\n  --output-dir \u003cdir\u003e    Output Directory\n  --cwd \u003cdir\u003e           Current Directory\n  --clean               Remove the injected content.\n  --verbose             Verbose output.\n  --silent              Only output errors.\n  --no-stop-on-errors   Do not stop if an error occurs.\n  --write-on-error      write the file even if an injection error occurs.\n  --color               Force color.\n  --no-color            Do not use color.\n  --no-summary          Do not show the summary\n  --dry-run             Process the files, but do not write.\n  -V, --version         output the version number\n  -h, --help            display help for command\n```\n\n\u003c!--- @@inject-end: content/help.txt ---\u003e\n\n\u003c!--- @@inject: content/README.md ---\u003e\n\n# How to use Injections\n\n## Import Code\n\nAll non-markdown files will be imported as a code block.\n\n```markdown\n\u003c!--- @@inject: code.ts ---\u003e\n```\n\n```ts\nexport function sayHello(name: string): string {\n  return `Hello ${name}`;\n}\n```\n\n## Import `json` as `jsonc`\n\n### Syntax\n\n```markdown\n\u003c!--- @@inject-code: sample.json#lang=jsonc ---\u003e\n```\n\n### Example\n\n````markdown\n\u003c!--- @@inject-code: sample.json#lang=jsonc ---\u003e\n\n```jsonc\n{\n  \"name\": \"Sample\"\n}\n```\n\n\u003c!--- @@inject-end: sample.json#lang=jsonc ---\u003e\n````\n\n### Actual Result\n\n```jsonc\n{\n  \"name\": \"Sample\"\n}\n```\n\n## Import Markdown as Code\n\nIt is also possible to inject markdown:\n\n```markdown\n\u003c!--- @@inject-code: example.md ---\u003e\n```\n\n```markdown\n# Example\n\nThis is an example bit of markdown.\n\n- first\n- second\n- third\n```\n\n## Import a section from a Markdown file\n\n```markdown\n\u003c!--- @@inject: chapters.md#Chapter 3: Directives ---\u003e\n\nor\n\n\u003c!--- @@inject: chapters.md#heading=Chapter 3: Directives ---\u003e\n```\n\n\u003e ## Chapter 3: Directives\n\u003e\n\u003e - `@@inject: \u003cmarkdown_file.md\u003e[#heading]` and `@@inject-start:  \u003cmarkdown_file.md\u003e[#heading]` -- injects the contents of a markdown file.\n\u003e   - `\u003cmarkdown_file.md\u003e` -- the file to import\n\u003e   - `heading` -- optional heading to extract.\n\u003e   - `code` -- optional embed as a `markdown` code block\n\u003e   - `quote` -- optional embed as a block quote.\n\u003e - `@@inject: \u003cnon-markdown-file\u003e[#lang]`, `@@inject-start:  \u003cnon-markdown-file\u003e[#lang]`, and `@@inject-code: \u003cfile\u003e[#lang]`\n\u003e   - `\u003cnon-markdown-file\u003e`, `\u003cfile\u003e` -- the file to import\n\u003e   - `lang` -- optional language to use for the code bock.\n\u003e   - `quote` -- optional embed as a block quote.\n\n## Import from lines from GitHub\n\n\u003cimg width=\"711\" alt=\"image\" src=\"https://user-images.githubusercontent.com/3740137/210188786-28704fe3-cc2f-447c-97fc-d27715dabbdc.png\"\u003e\n\n```\n\u003c!--- @@inject: https://github.com/streetsidesoftware/inject-markdown/blob/d7de2f5fe/src/app.mts#L15-L19 ---\u003e\n```\n\n```typescript\nasync function version(): Promise\u003cstring\u003e {\n    const pathSelf = fileURLToPath(import.meta.url);\n    const pathPackageJson = path.join(path.dirname(pathSelf), '../package.json');\n    const packageJson = JSON.parse(await fs.readFile(pathPackageJson, 'utf8'));\n    return (typeof packageJson === 'object' \u0026\u0026 packageJson?.version) || '0.0.0';\n```\n\n\u003c!--- cspell:dictionaries typescript ---\u003e\n\n## Per Injections Options\n\nThe hash `#` portion of the file URL is used to set injection options. Each option is separated by a `\u0026`.\n\n| Option    | Code | Markdown | Description                                               |\n| --------- | ---- | -------- | --------------------------------------------------------- |\n| `heading` | ❌   | ✅       | Used to extract a section from a markdown file.           |\n| `code`    | ❌   | ✅       | Convert the injected markdown into a Code Block.          |\n| `lang`    | ✅   | ✅       | Used to set the language of the code block.               |\n| `quote`   | ✅   | ✅       | Used to inject the file as a block quote.                 |\n| `L1-L10`  | ✅   | ✅       | Used to inject only specified lines from the source file. |\n\n### Example 1\n\nExtract a few lines from a Markdown files and quote them.\n\n```markdown\n\u003c!--- @@inject: example.md#L5-L7\u0026quote ---\u003e\n```\n\n\u003e - first\n\u003e - second\n\u003e - third\n\n### Example 2\n\nExtract some lines from a code block in the source.\n\n```markdown\n\u003c!--- @@inject-code: code.md#L24-L26\u0026lang=js ---\u003e\n```\n\n\u003e ```js\n\u003e export function sayGoodbye(name) {\n\u003e   return `Goodbye ${name}`;\n\u003e }\n\u003e ```\n\n\u003c!--- @@inject-end: content/README.md ---\u003e\n\n\u003c!--- @@inject: static/footer.md ---\u003e\n\n\u003cbr/\u003e\n\n---\n\n\u003cp align=\"center\"\u003e\nBrought to you by \u003ca href=\"https://streetsidesoftware.com\" title=\"Street Side Software\"\u003e\n\u003cimg width=\"16\" alt=\"Street Side Software Logo\" src=\"https://i.imgur.com/CyduuVY.png\" /\u003e Street Side Software\n\u003c/a\u003e\n\u003c/p\u003e\n\n\u003c!--- @@inject-end: static/footer.md ---\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstreetsidesoftware%2Finject-markdown","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fstreetsidesoftware%2Finject-markdown","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstreetsidesoftware%2Finject-markdown/lists"}