@forgen/remark-remote-code
@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-codeSetup
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 tofalse.removeRedundantIndentations: boolean: Trim unnecessary indentations in the imported code.allowImportingFromOutside: boolean: Allow file imports from outside the specifiedrootDir. 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
@forgen/remark-remote-code is a versatile tool for enhancing documentation and instructional content, ensuring code examples are always up-to-date and relevant.