markdown-dynamic-codeblock-loader

What is this?

A Webpack loader that can dynamically replace Markdown code blocks with snippets extracted from source files.

When is this useful?

It is useful for documentation websites generated using Webpack (e.g. React Storybook). Using this loader, you can automatically embed type definitions into your Markdown docs at build-time. This way, the code snippets in your documentation will always be up to date with the actual source code. Chonky React file browser is a good example of a project using this loader.

What are the limitations?

At the moment, only top-level declarations in JavaScript and TypeScript can be extracted.

The gist

Suppose you have a TypeScript file, types.ts, that defines some interfaces:

export interface Node {
    value: number; // Value must be an integer!
    left?: Node; // Left child
    right?: Node; // Right child
}

export type SomeUnrelatedType = string | null;

You can use special syntax to reference the Node interface from types.ts in your Markdown file:

# Node documentation

The interface for nodes is defined as follows:

```ts {"file": "types.ts", "symbol": "Node"}
```

When you import the Markdown file above using this loader, it is transformed into:

# Node documentation

The interface for nodes is defined as follows:

```ts {"file": "types.ts", "symbol": "Node"}
export interface Node {
    value: number; // Value must be an integer!
    left?: Node; // Left child
    right?: Node; // Right child
}
```

Installation and usage

Install the main loader:

npm install --save-dev markdown-dynamic-codeblock-loader

Install any additional loaders you need to work with Markdown. This will depend on your use case. For example, if you want to load Markdown files as plain text, you can install raw-loader:

npm install --save-dev raw-loader

Add relevant Markdown rules to your Webpack config. Make sure markdown-dynamic-codeblock-loader comes last in the list of loaders:

// webpack.config.js
const path = require('path');

module.exports = {
    module: {
        rules: [
            {
                test: /\.mdx?$/,
                use: [
                    {
                        // You can replace this with any loader
                        // you want, e.g. `markdown-loader`
                        loader: 'raw-loader',
                    },
                    {
                        // This has to come last!
                        loader: 'markdown-dynamic-codeblock-loader',
                        options: {
                            // Optionally, specify path mappings
                            mappings: {
                                'my-src': path.resolve(__dirname, '..', 'src'),
                                // Can now reference files as `<my-src>/script.ts`
                            },
                        },
                    },
                ],
            },
        ],
    },
};

Now you can create a Markdown file, e.g. docs.md that will reference some declaration in your code, e.g. Colors from typedef.ts,

// typedef.ts
export enum Colors {
    Black = 'black',
}

# docs.md

Look at my fancy colors enum:

```ts {"file": "typedef.ts", "symbol": "Colors"}
```

Finally, you can import the Markdown file in your code:

import docs from './docs.md';

console.log(docs);

In the output, you will see that the declaration for the Colors enum was embedded into the Markdown source.

License

MIT © Tim Kuzhagaliyev 2020