{"_id":"@devrelkit/remark-include-code","_rev":"2-af9ea42d421ebe6a24c0d49307267715","name":"@devrelkit/remark-include-code","dist-tags":{"latest":"0.1.2"},"versions":{"0.1.1":{"name":"@devrelkit/remark-include-code","version":"0.1.1","keywords":["remark","remark-plugin","mdx","markdown","code","include","transclude","fumadocs","codehike","shiki"],"author":{"name":"catmcgee"},"license":"MIT","_id":"@devrelkit/remark-include-code@0.1.1","maintainers":[{"name":"catmcgee","email":"helloworld@mcgee.cat"}],"homepage":"https://github.com/catmcgee/remark-include-code#readme","bugs":{"url":"https://github.com/catmcgee/remark-include-code/issues"},"dist":{"shasum":"21134dc2e7bc1cff272334e24655aa30c4df7411","tarball":"https://registry.npmjs.org/@devrelkit/remark-include-code/-/remark-include-code-0.1.1.tgz","fileCount":9,"integrity":"sha512-gB8gIO1Axvfx0oqihO8i3bHEphUFDZf+/arJKc0fUTQyo6uSMO5IY1BpyJfn06JroNf4h/CwbGTPTCmGU7Q6SA==","signatures":[{"sig":"MEYCIQC/TiMTAv7Wshoe90S7TEkppez14IqhAHE33Lo1F2OjWgIhAJh8zsw11wzpWGcnSxF22AT66Sj8Iv7wRIURNB/gDAkr","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":68515},"main":"./dist/index.cjs","type":"module","types":"./dist/index.d.ts","module":"./dist/index.js","engines":{"node":">=18"},"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js","require":"./dist/index.cjs"}},"gitHead":"17657c07a98e0de2372be42cf1dcd9bc5f6b638f","scripts":{"dev":"tsup --watch","lint":"tsc --noEmit","test":"vitest run","build":"tsup","test:watch":"vitest","prepublishOnly":"pnpm build && pnpm test"},"_npmUser":{"name":"catmcgee","email":"helloworld@mcgee.cat"},"repository":{"url":"git+https://github.com/catmcgee/remark-include-code.git","type":"git"},"_npmVersion":"11.6.0","description":"Remark plugin to include code from external files into markdown/MDX, with region slicing and line-highlight passthrough.","directories":{},"_nodeVersion":"24.8.0","dependencies":{"unist-util-visit":"^5.0.0"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"tsup":"^8.3.5","vfile":"^6.0.3","remark":"^15.0.1","vitest":"^2.1.8","unified":"^11.0.5","remark-mdx":"^3.1.0","typescript":"^5.7.2","@types/node":"^22.10.0","@types/mdast":"^4.0.4"},"peerDependencies":{"unified":"^11.0.0"},"_npmOperationalInternal":{"tmp":"tmp/remark-include-code_0.1.1_1777630318652_0.4206896782582379","host":"s3://npm-registry-packages-npm-production"}},"0.1.2":{"name":"@devrelkit/remark-include-code","version":"0.1.2","description":"Remark plugin to include code from external files into markdown/MDX, with region slicing and line-highlight passthrough.","keywords":["remark","remark-plugin","mdx","markdown","code","include","transclude","fumadocs","codehike","shiki"],"license":"MIT","author":{"name":"catmcgee"},"repository":{"type":"git","url":"git+https://github.com/catmcgee/remark-include-code.git"},"bugs":{"url":"https://github.com/catmcgee/remark-include-code/issues"},"homepage":"https://github.com/catmcgee/remark-include-code#readme","type":"module","main":"./dist/index.cjs","module":"./dist/index.js","types":"./dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js","require":"./dist/index.cjs"}},"scripts":{"build":"tsup","dev":"tsup --watch","test":"vitest run","test:watch":"vitest","lint":"tsc --noEmit","prepublishOnly":"pnpm build && pnpm test"},"dependencies":{"unist-util-visit":"^5.0.0"},"devDependencies":{"@types/mdast":"^4.0.4","@types/node":"^22.10.0","remark":"^15.0.1","remark-mdx":"^3.1.0","tsup":"^8.3.5","typescript":"^5.7.2","unified":"^11.0.5","vfile":"^6.0.3","vitest":"^2.1.8"},"peerDependencies":{"unified":"^11.0.0"},"engines":{"node":">=18"},"publishConfig":{"access":"public"},"_id":"@devrelkit/remark-include-code@0.1.2","gitHead":"17657c07a98e0de2372be42cf1dcd9bc5f6b638f","_nodeVersion":"24.8.0","_npmVersion":"11.6.0","dist":{"integrity":"sha512-9vMz3sm9VsWefln38dPQ59gPrEmoa4SJjhrK+1WYzzCrtNZF0uYpeAFlCfZvbpaIw9/Oy057CRT2Dr1pzF5xUw==","shasum":"ff83c207b79ff32c3fe3de39fc9ba725a019f26c","tarball":"https://registry.npmjs.org/@devrelkit/remark-include-code/-/remark-include-code-0.1.2.tgz","fileCount":9,"unpackedSize":76174,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIC9S1QGnQTS3UGShObCcyCuYsOxpa+R8ODjOGfdxyms4AiBMmXXmStEZ6qobJMBrbenKRLxJcSXpvEwB0Q2kdcVdDQ=="}]},"_npmUser":{"name":"catmcgee","email":"helloworld@mcgee.cat"},"directories":{},"maintainers":[{"name":"catmcgee","email":"helloworld@mcgee.cat"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/remark-include-code_0.1.2_1779395941486_0.21921321665459303"},"_hasShrinkwrap":false}},"time":{"created":"2026-05-01T10:11:58.526Z","modified":"2026-05-21T20:39:01.869Z","0.1.1":"2026-05-01T10:11:58.803Z","0.1.2":"2026-05-21T20:39:01.663Z"},"bugs":{"url":"https://github.com/catmcgee/remark-include-code/issues"},"author":{"name":"catmcgee"},"license":"MIT","homepage":"https://github.com/catmcgee/remark-include-code#readme","keywords":["remark","remark-plugin","mdx","markdown","code","include","transclude","fumadocs","codehike","shiki"],"repository":{"type":"git","url":"git+https://github.com/catmcgee/remark-include-code.git"},"description":"Remark plugin to include code from external files into markdown/MDX, with region slicing and line-highlight passthrough.","maintainers":[{"name":"catmcgee","email":"helloworld@mcgee.cat"}],"readme":"# @devrelkit/remark-include-code\n\nA [remark](https://github.com/remarkjs/remark) plugin that includes code from external files into markdown / MDX, with named-region slicing and line-highlight passthrough.\n\nThe classic problem: code samples in docs drift out of sync with reality because they live as plain text inside the docs. This plugin lets you keep examples as **real source files that get tested in CI**, then transclude them into your docs at build time.\n\n## Install\n\n```sh\npnpm add -D @devrelkit/remark-include-code\n# or\nnpm install --save-dev @devrelkit/remark-include-code\n```\n\n## Usage\n\n```js\nimport { remark } from \"remark\";\nimport remarkIncludeCode from \"@devrelkit/remark-include-code\";\n\nconst file = await remark()\n  .use(remarkIncludeCode, {\n    /* options */\n  })\n  .process(markdown);\n```\n\nIn your markdown / MDX, replace inline code with a `file=` directive on the fence:\n\n````md\n```ts file=./examples/create-account.ts#region=create\n```\n````\n\nThe plugin reads `./examples/create-account.ts` (relative to the markdown file), extracts the `create` region, and replaces the codeblock body. The fence keeps its language tag, so downstream highlighters work normally.\n\n### Region markers\n\nRegions in source files use a comment style that's neutral across most languages:\n\n```ts\n// #region create\nconst account = createAccount({ payer, lamports });\n// #endregion create\n```\n\n```python\n# #region create\naccount = Account(payer=payer, lamports=1_000_000)\n# #endregion create\n```\n\nThe plugin picks the comment token (`//` or `#`) automatically based on the codeblock's language tag.\n\nSupported languages out of the box:\n- `//` — ts, tsx, typescript, js, jsx, javascript, rust, rs, c, cpp, go, java, swift, kotlin, scala, dart\n- `#` — py, python, sh, bash, zsh, ruby, yaml, toml, r, perl\n\nMultiple regions with the same name in one file are concatenated (separated by a blank line) — useful for stitching non-contiguous pieces into one example.\n\nThe common leading indent of the region body is stripped, so a region defined inside an indented block still renders flush-left.\n\n### Line highlighting\n\nAdd `highlight=` to mark lines for visual emphasis:\n\n````md\n```ts file=./examples/create-account.ts#region=create highlight=2-5,10\n```\n````\n\nBy default the ranges are appended to the codeblock meta as `{2-5,10}`, which is the convention used by **Shiki**, **rehype-pretty-code**, **VitePress**, and **Astro Starlight**. Configure `highlightStyle` for other renderers (see Options).\n\n### Whole-file include\n\nDrop the `#region=...` to include the whole file:\n\n````md\n```ts file=./examples/full-script.ts\n```\n````\n\n### Other meta fields pass through\n\nAnything other than `file=` and `highlight=` is preserved on the meta string:\n\n````md\n```ts title=\"Kit\" file=./examples/foo.ts#region=create\n```\n````\n\n→ output keeps `title=\"Kit\"` so renderers like CodeHike's `<CodeTabs>` see what they expect.\n\n## Options\n\n```ts\ninterface PluginOptions {\n  rootDir?: string;\n  highlightStyle?:\n    | \"fence-meta\"\n    | \"codehike\"\n    | ((ctx: HighlightContext) => HighlightResult);\n}\n```\n\n### `rootDir`\n\nResolution root for `file=` paths. Defaults to the directory of the markdown file being processed (recommended). Set this if you want to centralise examples in one location and reference them from anywhere with the same relative path.\n\n### `highlightStyle`\n\nHow `highlight=` ranges land in the output:\n\n- **`\"fence-meta\"`** (default): appends `{2-5,10}` to the codeblock meta string. Compatible with Shiki, rehype-pretty-code, VitePress, Astro Starlight, and most modern markdown highlighters.\n- **`\"codehike\"`**: injects `// !mark(N:M)` (or `# !mark(N:M)` for hash-comment languages) above each highlighted range, so [CodeHike](https://codehike.org)'s mark annotation handler picks them up.\n- **function**: receives the slice + ranges + lang + meta, returns the final code + meta. Use this for any other renderer or custom annotation format.\n\n```ts\nimport remarkIncludeCode, { type HighlightContext } from \"@devrelkit/remark-include-code\";\n\nremark().use(remarkIncludeCode, {\n  highlightStyle: (ctx: HighlightContext) => ({\n    code: ctx.code,\n    meta: `${ctx.meta} data-lines=${JSON.stringify(ctx.ranges)}`,\n  }),\n});\n```\n\n## Errors\n\nThe plugin throws (rather than silently producing wrong output) when:\n\n- `file=` path doesn't resolve to a readable file\n- `#region=...` doesn't exist in the source\n- `highlight=` range is malformed (`abc`, `5-2`, etc.)\n\nAll wrap as `IncludeError` with the markdown file path included, so build failures point you at the broken doc.\n\n## Why a remark plugin?\n\n[`remark`](https://github.com/remarkjs/remark) is the markdown half of the [`unified`](https://unifiedjs.com/) ecosystem. It parses markdown into an AST (`mdast`), runs plugins to transform that tree, then serialises back. MDX, Fumadocs, Docusaurus, Next.js, Astro, and most modern markdown stacks compose on top of it — so a remark plugin slots into all of them via a one-line `.use(...)` registration.\n\n## License\n\nMIT\n","readmeFilename":"README.md"}