@forgen/remark-remote-code

🔗 Enhance your Markdown files by dynamically importing code blocks from remote sources.

Important: As of version 1.0.0, @forgen/remark-remote-code is an ESM-only module. It requires Node.js version 12 or higher and must be used with import rather than require.

Installation

Use npm to install the package:

npm install -D @forgen/remark-remote-code

Setup

Import the plugin using named export; there is no default export:

import { remoteCode } from '@forgen/remark-remote-code';

For detailed instructions on using plugins, refer to the official documentation.

@forgen/remark-remote-code is compatible with various libraries like remark in MDX, Gatsby’s gatsby-plugin-mdx, and Storybook docs.

Usage

Convert a simple reference in your Markdown:

```js url=https://.../example-script.js
```

Into a full code block populated with content:

```js url=https://.../example-script.js
// Content of example-script.js
```

The file path is relative to the markdown file. Use <rootDir> to refer to a custom root directory defined in the options:

```js url=<rootDir>/script-in-root.js
```

Specify specific lines or ranges to include:

Only line 3:
```js url=https://.../example-script.js#L3
```

From line 3 to line 6:
```js url=https://.../example-script.js#L3-L6
```

From line 3 to the end of the file:
```js url=https://.../example-script.js#L3-
```

Escape file paths with spaces:

```js url=https://...//file\ with\ spaces.js
```

Options

• rootDir: string: Customize what <rootDir> points to.
• preserveTrailingNewline: boolean: Keep the trailing newline in imported code. Defaults to false.
• removeRedundantIndentations: boolean: Trim unnecessary indentations in the imported code.
• allowImportingFromOutside: boolean: Allow file imports from outside the specified rootDir. Disabled by default for security.

Integration with Gatsby

Available as a Gatsby remark plugin through the /gatsby endpoint:

{
  resolve: '@forgen/remark-remote-code/gatsby',
  options: {/* ... */}
}

Testing

Install dependencies with npm install. Run tests using npm test.

License

Forgen

MIT License

@forgen/remark-remote-code is a versatile tool for enhancing documentation and instructional content, ensuring code examples are always up-to-date and relevant.