{"id":25595482,"url":"https://github.com/polywrap/doc-snippets","last_synced_at":"2026-03-11T14:37:37.822Z","repository":{"id":63687255,"uuid":"569892560","full_name":"polywrap/doc-snippets","owner":"polywrap","description":"Extract and inject snippets from code into markdown files","archived":false,"fork":false,"pushed_at":"2023-09-26T17:40:53.000Z","size":142,"stargazers_count":3,"open_issues_count":1,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-10-30T20:51:02.558Z","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/polywrap.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-11-23T21:24:17.000Z","updated_at":"2023-02-17T11:47:34.000Z","dependencies_parsed_at":"2025-02-21T11:40:38.997Z","dependency_job_id":null,"html_url":"https://github.com/polywrap/doc-snippets","commit_stats":null,"previous_names":[],"tags_count":8,"template":false,"template_full_name":null,"purl":"pkg:github/polywrap/doc-snippets","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/polywrap%2Fdoc-snippets","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/polywrap%2Fdoc-snippets/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/polywrap%2Fdoc-snippets/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/polywrap%2Fdoc-snippets/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/polywrap","download_url":"https://codeload.github.com/polywrap/doc-snippets/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/polywrap%2Fdoc-snippets/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30384092,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-11T14:10:17.325Z","status":"ssl_error","status_checked_at":"2026-03-11T14:09:37.934Z","response_time":84,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"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":"2025-02-21T11:29:18.595Z","updated_at":"2026-03-11T14:37:37.801Z","avatar_url":"https://github.com/polywrap.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# doc-snippets\n\n`doc-snippets` is a simple tool that allows you to extract and inject snippets from code into markdown files.\n\n# Installation\n\nUsing NPM:\n\n```bash\nnpm install --save-dev doc-snippets\n```\n\nUsing Yarn:\n\n```bash\nyarn add -D doc-snippets\n```\n\n# Usage\n\n## Marking and injecting\n\n`doc-snippets` extracts and injects snippets by using tokens:\n\n- To mark a snippet:\n  - `$start: snippet-name` - The start of a snippet and its name (required)\n  - `$end` - The end of a snippet.\n- To inject a snippet:\n  - `$snippet: snippet-name` - This gets replaced by the snippet with the given name.\n\n### The snippet name\n\nThe snippet name is a string containing **any characters except whitespace**. \n\nAs soon as `doc-snippets` encounters any form of whitespace (space, tab, newline), the snippet name capture ends.\n\n## Configuration\n\nThe `doc-snippets` CLI is configured using a JSON file that contains a `doc-snippets` object. By default, this file is `package.json`.\n\nThe configuration object has the following structure (and default values):\n\n```JSON\n\"doc-snippets\": {\n  \"extract\": {\n    \"include\": \"./**/*.{js,ts,json,yaml,txt,md,graphql,cue}\",\n    \"ignore\": \"./**/node_modules/**\",\n    \"dir\": \"./src\"\n  },\n  \"inject\": {\n    \"include\": \"./**/*.md\",\n    \"ignore\": [],\n    \"dir\": \"./src/docs\"\n  },\n  \"startTokens\": [\n    {\n      \"pattern\": \"$start: \",\n      \"inline\": false\n    }\n  ],\n  \"endTokens\": [\n    {\n      \"pattern\": \"$end\",\n      \"inline\": false\n    }\n  ],\n  \"injectToken\": \"$snippet: \",\n  \"outputDir\": \"./docs\"\n}\n```\n\n### `extract` and `inject`\n\nThe `extract` and `inject` objects both have the same structure:\n\n- `include` - a string or array of strings containing paths to include. The paths are formatted as Glob patterns following the [node-glob specification](https://github.com/isaacs/node-glob)\n- `ignore` - same as `include`, this is a string or array of strings containing paths to ignore. It follows the same Glob pattern specification as `include`\n- `dir` - the base directory for injection and extraction. `include` and `ignore` use this directory as their base when searching for files.\n\nThe `extract` object specifies which files will be parsed for snippets to extract.\n\nThe `inject` object specifies which files will be copied into `outputDir` and have snippets injected into them.\n\n**Example `extract` object:**\n\n```JSON\n\"extract\": {\n  \"include\": [\"sample.sql\", \"./**/*.{js,ts}\"],\n  \"ignore\": \"./**/node_modules/**\",\n  \"dir\": \"./src\"\n}\n```\n\nIn this example, `extract` will perform its search within the `./src` directory.\n\nIt will include:\n\n- `./src/sample.sql`\n- All files within `./src` and its subdirectories ending in `.js` and `.ts`\n\nIt will ignore:\n\n- All directories and subdirectories of any `node_modules` directory found within `./src` and its subdirectories.\n\nThe same principles apply for the `inject` object.\n\n### Extraction tokens (`startTokens` and `endTokens`)\n\nExtraction tokens mark the beginning and end of our snippets.\n\nThe tokens have two properties:\n- `pattern` - the **exact string** that denotes the token\n- `inline` - defines whether the token is a **regular** or **inline** extraction token\n\n#### Regular and inline extraction tokens\n\nBy default, extraction tokens are designed to be written within their own lines. Anything else written within the token's line will be ignored when extracting snippets.\n\nLet's take a look at an example:\n\n```typescript\n// $start: hello-snippet we can add comments here\nconst greeting = \"Hello World!\";\nconsole.log(greeting);\n// $end\n```\n\nUsing the default configuration, this code will yield a snippet called `hello-snippet` with the following contents:\n```\nconst greeting = \"Hello World!\";\nconsole.log(greeting);\n```\n\nTo allow for more flexible snippet extraction, we can use **inline** extraction tokens.\n\nFor example, let's configure our extraction tokens as follows:\n\n```json\n{\n  //...\n  \"startTokens\": [\n    {\n      \"pattern\": \"/* #start: {SNIPPET_NAME} */\",\n      \"inline\": true\n    }\n  ],\n  \"endTokens\": [\n    {\n      \"pattern\": \"/* #end */\",\n      \"inline\": true\n    }\n  ]\n}\n```\n\nNote that there is a special token within the start token's `pattern` property: **`{SNIPPET_NAME}`**. This denotes where in the inline token the snippet name will appear.\n\nIn addition, let's assume that we have a file with the following code:\n\n```typescript\nconst greeting = /* #start: hello-inline-snippet */\"Hello World!\";\nconsole.log(greeting);/* #end */\n```\n\nSnippet extraction would now yield a snippet named `hello-inline-snippet` with the following contents:\n```\n\"Hello World!\";\nconsole.log(greeting);\n```\n\nInline extraction tokens can be useful when you need to extract only part of your line.\n\nRegular and inline extraction tokens can be used at the same time, and snippet extraction will always search for **any** end token after it encounters **any** start token.\n\nFor reference:\n- When a  **regular start token** is encoutered, snippet extraction starts at the beginning of the next line.\n- When an **inline start token** is encountered, snippet extraction starts immediately after the token ends.\n- When a **regular end token** is encountered, snippet extraction ends at the end of the previous line.\n- When an **inline end token** is encountered, snippet extraction ends at the beginning of the token.\n\n**:warning: Regular and inline snippets containing the same substring :warning:**\n\nIf we have the following configuration for our end tokens:\n\n```json\n\"endTokens\": [\n  {\n    \"pattern\": \"$end\"\n  }\n  {\n    \"pattern\": \"/* $end */\",\n    \"inline\": true\n  }\n],\n```\n\nthe `$end` regular token will **always** match before the inline `/* $end */` token due to the way Regex matching works in Javascript.\n\nTo avoid these collisions, make sure to specify inline extraction tokens which don't contain any of your regular injection tokens as exact substrings within them.\n\nAn easy remedy for the above configuration is simply replacing `/* $end */` with `/* #end */`:\n\n```json\n\"endTokens\": [\n  {\n    \"pattern\": \"$end\"\n  }\n  {\n    \"pattern\": \"/* #end */\",\n    \"inline\": true\n  }\n],\n```\n\n### `injectionToken`\n\nThe `injectionToken` is the **exact string** which will be replaced by your snippet during injection. The snippet must follow immediately after the `injectionToken`.\n\nFor example, if you have the following `injectionToken`:\n\n```json\n{\n  // Note the space character at the end\n  \"injectionToken\": \"$snippet: \"\n}\n```\n\nthe following text would be replaced by a snippet called `hello-snippet`:\n\n```md\n$snippet: hello-snippet\n```\n\n### `outputDir`\n\nThe `outputDir` is the output directory for the documentation injected with snippets.\n\n## Running `doc-snippets`\n\n`doc-snippets` comes with a CLI tool which is designed to handle most scenarios.\n\nThe CLI `combine` is the only currently supported command, and can be used as follows:\n\n```bash\ndoc-snippets combine\n```\n\nThe `combine` command reads a `\"doc-snippets\"` section from a configuration file (by default this is `package.json`) and performs snippet extraction and injection, and outputs documentation with injected snippets into an `outputDir`.\n\nAll configuration options can be overridden using `combine`'s command options.\n\n### 'combine' command options\n\n- `-c --config \u003cpath\u003e` - Path to configuration file (default: './package.json')\n- `-o --output-dir \u003cpath\u003e` - Combined documentation output directory\n- `--extract-dir \u003cpath\u003e` - The base directory within which to search for snippets\n- `--extract-include \u003cpaths...\u003e` - Include specified paths or glob patterns in snippet extraction\n- `--extract-ignore \u003cpaths...\u003e` - Ignore specified paths or glob patterns in snippet extraction\n- `--inject-dir \u003cpath\u003e` - The base directory within which to search for injectable files\n- `--inject-include \u003cpaths...\u003e` - Include specified paths or glob patterns in snippet injection\n- `--inject-ignore \u003cpaths...\u003e` - Ignore specified paths or glob patterns in snippet injection\n- `--start-tokens \u003ctokens...\u003e` - Tokens marking the start of the snippet\n- `--end-tokens \u003ctokens...\u003e` - Tokens marking the end of the snippet\n- `--inline-start-tokens \u003ctokens...\u003e` - Inline Tokens marking the start of the snippet\n- `--inline-end-tokens \u003ctokens...\u003e` - Inline Tokens marking the end of the snippet\n- `--inject-token \u003ctoken\u003e` - Token marking the point of snippet injection\n\n\n## In your own code\n\nIf you want to use `doc-snippets` programatically, it offers two exported functions:\n\n```typescript\nimport { extractSnippets, injectSnippetsIntoFile } from \"doc-snippets\";\n\nconst searchOptions = {\n  include: [\"sample.sql\", \"./**/*.{js,ts}\"],\n  ignore: \"./**/node_modules/**\",\n  dir: \"./src\",\n};\n\n//Returns snippets as `Record\u003cstring, string\u003e`.\nconst startTokens = [\n  {\n    pattern: \"$start: \"\n  },\n  {\n    pattern: \"/* #start: {SNIPPET_NAME} */\",\n    inline: true\n  }\n];\n\nconst endTokens = [\n  {\n    pattern: \"$end\"\n  },\n  {\n    pattern: \"/* #end */\",\n    inline: true\n  }\n];\n\nconst snippets = await extractSnippets(searchOptions, startTokens, endTokens);\n\n//Injects `snippets` into `./dest/readme.md` replacing all instances of `$snippet: snippet-name` with the appropriate snippet\nawait injectSnippetsIntoFile(snippets, \"./dest/readme.md\", \"$snippet: \");\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpolywrap%2Fdoc-snippets","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpolywrap%2Fdoc-snippets","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpolywrap%2Fdoc-snippets/lists"}