{"id":13683300,"url":"https://github.com/zakhenry/embedme","last_synced_at":"2025-04-07T19:58:15.676Z","repository":{"id":34932881,"uuid":"192130655","full_name":"zakhenry/embedme","owner":"zakhenry","description":"Utility for embedding code snippets into markdown documents","archived":false,"fork":false,"pushed_at":"2024-10-06T18:59:26.000Z","size":1075,"stargazers_count":232,"open_issues_count":31,"forks_count":36,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-03-16T13:03:00.677Z","etag":null,"topics":["embedme","markdown","multi-language","snippets"],"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/zakhenry.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":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2019-06-15T22:58:01.000Z","updated_at":"2025-02-08T19:26:25.000Z","dependencies_parsed_at":"2024-01-14T16:10:52.671Z","dependency_job_id":"0d19eda9-588e-4169-ba52-12d3fdec21c7","html_url":"https://github.com/zakhenry/embedme","commit_stats":null,"previous_names":[],"tags_count":27,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zakhenry%2Fembedme","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zakhenry%2Fembedme/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zakhenry%2Fembedme/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zakhenry%2Fembedme/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/zakhenry","download_url":"https://codeload.github.com/zakhenry/embedme/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247721895,"owners_count":20985084,"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":["embedme","markdown","multi-language","snippets"],"created_at":"2024-08-02T13:02:06.837Z","updated_at":"2025-04-07T19:58:15.656Z","avatar_url":"https://github.com/zakhenry.png","language":"TypeScript","funding_links":[],"categories":["TypeScript","markdown"],"sub_categories":[],"readme":"# EmbedMe\n\nSimple utility to embed source files into markdown code blocks \u003csup\u003e[why tho?](#why)\u003c/sup\u003e\n\n[![npm version](https://badge.fury.io/js/embedme.svg)](https://www.npmjs.com/package/embedme)\n[![Build Status](https://travis-ci.org/zakhenry/embedme.svg?branch=master)](https://travis-ci.org/zakhenry/embedme)\n[![Commitizen friendly](https://img.shields.io/badge/commitizen-friendly-brightgreen.svg)](https://commitizen.github.io/cz-cli/)\n\n![Demo](readme/asciinema/demo.svg)\n\n## Usage\n\nWith a `README.md` in your current working directory, add a code block for one of the\n[supported file types](#multi-language) and start the code block simply with a comment with the path to a\nfile. For example\n\n\u003c!-- embedme-ignore-next --\u003e\n\n    This is a *markdown* document with a code block:\n\n    ```ts\n    // example.ts\n    ```\n\nNext, run the following\n\n```bash\nnpx embedme README.md\n```\n\nEt voilà! Your README.md file will be updated with the content of your source file:\n\n\u003c!-- prettier-ignore --\u003e\n    This is a *markdown* document with a code block:\n\n    ```ts\n    // example.ts\n    \n    export function helloWorld(name: string): string {\n      return `Hello ${name}!, how are you today?`;\n    }\n    \n    ```\n\nAs the comment is preserved, you can happily re-run `embedme` and it will run again but there will be no changes.\n\n## Features\n\n\u003c!-- embedme readme/help-output.txt --\u003e\n\u003c!-- prettier-ignore --\u003e\n```txt\n$ embedme --help\nUsage: embedme [options] [...files]\n\nOptions:\n  -V, --version              output the version number\n  --verify                   Verify that running embedme would result in no\n                             changes. Useful for CI\n  --dry-run                  Run embedme as usual, but don't write\n  --source-root [directory]  Directory your source files live in in order to\n                             shorten the comment line in code fence\n  --silent                   No console output\n  --stdout                   Output resulting file to stdout (don't rewrite\n                             original)\n  --strip-embed-comment      Remove the comments from the code fence. *Must* be\n                             run with --stdout flag\n  -h, --help                 display help for command\n\n```\n\n### Partial Snippets\n\nVery often you only want to highlight a small part of a file, to do so simply suffix the filename with the GitHub line\nnumber syntax, e.g. `path/to/my/file.ts#L20-L30`.\n\n### Multi Language\n\n`embedme` simply uses the file type hint in a code fence to choose a strategy for finding the commented filename in the\nfirst line of the code block. This is a relatively trivial regular expression, so many more languages can be supported\nin future\n\nHere's a list of file types supported by this utility, if you have a need for another language please feel free to\ncontribute, it is easy!\n\n```ts\n// src/embedme.lib.ts#L44-L82\n\nenum SupportedFileType {\n  PLAIN_TEXT = 'txt',\n  TYPESCRIPT = 'ts',\n  JAVASCRIPT = 'js',\n  REASON = 're',\n  SCSS = 'scss',\n  RUST = 'rust',\n  JAVA = 'java',\n  CPP = 'cpp',\n  C = 'c',\n  HTML = 'html',\n  XML = 'xml',\n  MARKDOWN = 'md',\n  YAML = 'yaml',\n  JSON = 'json',\n  JSON_5 = 'json5',\n  PYTHON = 'py',\n  BASH = 'bash',\n  SHELL = 'sh',\n  POWERSHELL = 'ps1',\n  GOLANG = 'go',\n  OBJECTIVE_C = 'objectivec',\n  PHP = 'php',\n  C_SHARP = 'cs',\n  SWIFT = 'swift',\n  RUBY = 'rb',\n  KOTLIN = 'kotlin',\n  SCALA = 'scala',\n  CRYSTAL = 'cr',\n  PLANT_UML = 'puml',\n  MERMAID = 'mermaid',\n  CMAKE = 'cmake',\n  PROTOBUF = 'proto',\n  SQL = 'sql',\n  HASKELL = 'hs',\n  ARDUINO = 'ino',\n  JSX = 'jsx',\n  TSX = 'tsx',\n}\n```\n\n### Alternate embedding syntax\n\nIt is recommended to use the syntax described above as it is a good hint for readers and maintainers where the source of\nthis file is, however in some situations you may want to omit the comment in the code block, but still benefit from the\nembedding behaviour of embedme.\n\nThis can be achieved by preceding the code block with a markdown comment in the form of `\u003c!-- embedme path/to/your/file.txt --\u003e`\n\nFor example:\n\n\u003c!-- embedme-ignore-next --\u003e\n\n    \u003c!-- embedme example.ts --\u003e\n    This is a *markdown* document with a code block:\n\n    ```ts\n    ```\n\nWill result in the following output\n\n    \u003c!-- embedme example.ts --\u003e\n    This is a *markdown* document with a code block:\n\n    ```ts\n    export function helloWorld(name: string): string {\n      return `Hello ${name}!, how are you today?`;\n    }\n\n    ```\n\n### Glob matching\n\nIf you want to run `embedme` over multiple files, you can use glob matching, i.e.\n\n```bash\nembedme \"src/**/*.md\"\n```\n\nNote embedme supports both quoted globbing and unquoted. Be careful using unquoted\nglobbing as this can lead to behaviour that is not portable between different\noperating systems.\n\nIf you're using Windows, you must use forward slashes (`/`) to denote path separators.\n\nYou can also pass multiple separate glob patterns to match multiple sets of files\n\nexample:\n\n```bash\nembedme \"src/**/*.md\" \"docs/**/*.markdown\"\n```\n\n### CI Checks\n\nIf you're using continuous integration, you can pass the flag `--verify` to `embedme` to check that there are no changes\nexpected to your files. This is useful for repositories with multiple contributors who may not know about `embedme`, and\nalso for yourself as a sanity check that you remembered to run it after updating sample code!\n\n### Output to stdout\n\nDon't want to rewrite the file in-place? That's ok too - you can pass the flag `--stdout` to have the output pass to\nstdout - this will allow you to redirect the output to another file.\n\nAdditionally, in this mode a `--strip-embed-comment` flag is available, which allows embedme to exclude the matched\ncomment from the output. This isn't generally recommended as the comment is generally unobtrusive, and will really help\nmaintainers to know where they should go to update the file.\n\nExample\n\n```sh\n# readme/output-to-std-out.sh\n\nembedme --stdout README.template.md \u003e README.md\n\n```\n\nNote that with `--stdout` flag the log output from embedme is redirected to stderr so you can still see the logs but the\noutput can be redirected.\n\n### Ignoring files\n\nBy default `embedme` uses the local `.gitignore` file to exclude any files that match your input but are ignored. You\ncan customise this ignore behavior by creating a `.embedmeignore` file, which uses the same syntax as `.gitignore`. This\nfile will be used _instead of_ `.gitignore`, not merged.\n\n## Why?\n\n\u003e Why do I want this utility? Writing code in a markdown document is not difficult?\n\nTrue, however it is difficult to know when your documentation files become out of date - if you're introducing a\nbreaking change, having your example code _actually using your library_ guarantees it will be correct.\n\n\u003e How can just having my examples in the language give me guarantees?\n\nFor starters if you're using a typesafe language (e.g. Typescript) you will get compiler errors, and secondarily you\nreally should be writing unit tests on your example code. As simple as it might be, how embarrassing is it if your\nexample doesn't even work?!\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzakhenry%2Fembedme","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fzakhenry%2Fembedme","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzakhenry%2Fembedme/lists"}