{"id":18039660,"url":"https://github.com/timbokz/markdown-dynamic-codeblock-loader","last_synced_at":"2026-04-15T09:31:49.321Z","repository":{"id":40763194,"uuid":"275478862","full_name":"TimboKZ/markdown-dynamic-codeblock-loader","owner":"TimboKZ","description":"A Webpack loader that can dynamically replace Markdown code blocks with snippets extracted from source files.","archived":false,"fork":false,"pushed_at":"2023-01-07T19:36:04.000Z","size":1947,"stargazers_count":1,"open_issues_count":17,"forks_count":0,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-03-30T16:01:29.652Z","etag":null,"topics":["documentation","documentation-generator","dynamic-loading","loader","markdown","typescript","webpack","webpack-loader"],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/markdown-dynamic-codeblock-loader","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/TimboKZ.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}},"created_at":"2020-06-28T00:50:41.000Z","updated_at":"2021-01-30T16:40:01.000Z","dependencies_parsed_at":"2023-02-07T23:00:38.272Z","dependency_job_id":null,"html_url":"https://github.com/TimboKZ/markdown-dynamic-codeblock-loader","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TimboKZ%2Fmarkdown-dynamic-codeblock-loader","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TimboKZ%2Fmarkdown-dynamic-codeblock-loader/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TimboKZ%2Fmarkdown-dynamic-codeblock-loader/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TimboKZ%2Fmarkdown-dynamic-codeblock-loader/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/TimboKZ","download_url":"https://codeload.github.com/TimboKZ/markdown-dynamic-codeblock-loader/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247271527,"owners_count":20911587,"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":["documentation","documentation-generator","dynamic-loading","loader","markdown","typescript","webpack","webpack-loader"],"created_at":"2024-10-30T14:09:59.980Z","updated_at":"2026-04-15T09:31:49.268Z","avatar_url":"https://github.com/TimboKZ.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# markdown-dynamic-codeblock-loader\n\n\u003cp\u003e\n  \u003ca href=\"https://www.npmjs.com/package/markdown-dynamic-codeblock-loader\" target=\"_blank\"\u003e\n    \u003cimg alt=\"NPM package\" src=\"https://img.shields.io/npm/v/markdown-dynamic-codeblock-loader.svg\"\u003e\n  \u003c/a\u003e\n  \u003ca href=\"https://travis-ci.com/github/TimboKZ/markdown-dynamic-codeblock-loader\" target=\"_blank\"\u003e\n    \u003cimg alt=\"Build status\" src=\"https://travis-ci.com/TimboKZ/markdown-dynamic-codeblock-loader.svg?branch=master\"\u003e\n  \u003c/a\u003e\n  \u003ca href=\"https://tldrlegal.com/license/mit-license\" style=\"margin-left: 5px;\" target=\"_blank\"\u003e\n    \u003cimg alt=\"MIT license\" src=\"https://img.shields.io/npm/l/markdown-dynamic-codeblock-loader\"\u003e\n  \u003c/a\u003e\n  \u003ca href=\"https://www.npmjs.com/package/markdown-dynamic-codeblock-loader\" style=\"margin-left: 5px;\" target=\"_blank\"\u003e\n    \u003cimg alt=\"NPM downloads\" src=\"https://img.shields.io/npm/dt/markdown-dynamic-codeblock-loader\"\u003e\n  \u003c/a\u003e\n  \u003ca href=\"https://github.com/TimboKZ/markdown-dynamic-codeblock-loader\" style=\"margin-left: 5px;\" target=\"_blank\"\u003e\n    \u003cimg alt=\"GitHub stars\" src=\"https://img.shields.io/github/stars/TimboKZ/markdown-dynamic-codeblock-loader\"\u003e\n  \u003c/a\u003e\n  \u003ca href=\"https://discord.gg/HT4ttdQ\" style=\"margin-left: 5px;\" target=\"_blank\"\u003e\n    \u003cimg alt=\"Chat on Discord\" src=\"https://img.shields.io/discord/696033621986770957?label=Chat%20on%20Discord\"\u003e\n  \u003c/a\u003e\n\u003c/p\u003e\n\n### What is this?\n\nA Webpack loader that can dynamically replace Markdown code blocks with snippets\nextracted from source files.\n\n### When is this useful?\n\nIt is useful for documentation websites generated using Webpack (e.g. React Storybook).\nUsing this loader, you can automatically embed type definitions into your Markdown docs\nat build-time. This way, the code snippets in your documentation will always be up to\ndate with the actual source code. [Chonky React file browser](https://github.com/TimboKZ/Chonky)\nis a good example of a project using this loader.\n\n### What are the limitations?\n\nAt the moment, only top-level declarations in JavaScript and TypeScript can be\nextracted.\n\n## The gist\n\nSuppose you have a TypeScript file, `types.ts`, that defines some interfaces:\n\n```ts\nexport interface Node {\n    value: number; // Value must be an integer!\n    left?: Node; // Left child\n    right?: Node; // Right child\n}\n\nexport type SomeUnrelatedType = string | null;\n```\n\nYou can use special syntax to reference the `Node` interface from `types.ts` in your\nMarkdown file:\n\n````markdown\n# Node documentation\n\nThe interface for nodes is defined as follows:\n\n```ts {\"file\": \"types.ts\", \"symbol\": \"Node\"}\n```\n````\n\nWhen you import the Markdown file above using this loader, it is transformed into:\n\n````markdown\n# Node documentation\n\nThe interface for nodes is defined as follows:\n\n```ts {\"file\": \"types.ts\", \"symbol\": \"Node\"}\nexport interface Node {\n    value: number; // Value must be an integer!\n    left?: Node; // Left child\n    right?: Node; // Right child\n}\n```\n````\n\n## Installation and usage\n\nInstall the main loader:\n\n```bash\nnpm install --save-dev markdown-dynamic-codeblock-loader\n```\n\nInstall any additional loaders you need to work with Markdown. This will depend on\nyour use case. For example, if you want to load Markdown files as plain text, you can\ninstall `raw-loader`:\n\n```bash\nnpm install --save-dev raw-loader\n```\n\nAdd relevant Markdown rules to your Webpack config. Make sure\n`markdown-dynamic-codeblock-loader` comes **last** in the list of loaders:\n\n```js\n// webpack.config.js\nconst path = require('path');\n\nmodule.exports = {\n    module: {\n        rules: [\n            {\n                test: /\\.mdx?$/,\n                use: [\n                    {\n                        // You can replace this with any loader\n                        // you want, e.g. `markdown-loader`\n                        loader: 'raw-loader',\n                    },\n                    {\n                        // This has to come last!\n                        loader: 'markdown-dynamic-codeblock-loader',\n                        options: {\n                            // Optionally, specify path mappings\n                            mappings: {\n                                'my-src': path.resolve(__dirname, '..', 'src'),\n                                // Can now reference files as `\u003cmy-src\u003e/script.ts`\n                            },\n                        },\n                    },\n                ],\n            },\n        ],\n    },\n};\n```\n\nNow you can create a Markdown file, e.g. `docs.md` that will reference some declaration\nin your code, e.g. `Colors` from `typedef.ts`,\n\n```typescript\n// typedef.ts\nexport enum Colors {\n    Black = 'black',\n}\n```\n\n````markdown\n# docs.md\n\nLook at my fancy colors enum:\n\n```ts {\"file\": \"typedef.ts\", \"symbol\": \"Colors\"}\n```\n````\n\nFinally, you can import the Markdown file in your code:\n\n```markdown\nimport docs from './docs.md';\n\nconsole.log(docs);\n```\n\nIn the output, you will see that the declaration for the `Colors` enum was embedded\ninto the Markdown source.\n\n## License\n\nMIT © [Tim Kuzhagaliyev](https://github.com/TimboKZ) 2020\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftimbokz%2Fmarkdown-dynamic-codeblock-loader","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftimbokz%2Fmarkdown-dynamic-codeblock-loader","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftimbokz%2Fmarkdown-dynamic-codeblock-loader/lists"}