remark-inline-local-code-snippets

This package is a unified (remark) plugin to replace links to a github code snippet with the code snippet itself.

Installation

npm install remark-inline-local-code-snippets

Usage

If you have a markdown file like this:

My blog post about code has snippets:

[inline](./index.ts#L8-L23)

This is the `.prettierrc.json` file:

[inline](./.prettierrc.json#L1-L7)

With a configuration like this

import * as path from "path";
import { read } from "to-vfile";
import remark from "remark";
import gfm from "remark-gfm";
import remarkRehype from "remark-rehype";
import rehypeStringify from "rehype-stringify";

import remarkInlinLocalCodeSnippet from "remark-inline-local-code-snippet";

main();

async function main() {
  const file = await remark()
    .use(gfm)
    .use(remarkInlinLocalCodeSnippet, {
      rootPath: path.resolve(__dirname, "src")),
      inlineMarker: "inline",
      originComment: "Source of this code snippet: <url>"
    })
    .use(remarkRehype)
    .use(rehypeStringify)
    .process(await read("example.md"));
}

We get an output equivalent to this Markdown:

My blog post about code has snippets:

\`\`\`typescript
export type Options = {
  // If this string is detected in a link text, the link will be replaced with a code snippet
  // Default: "inline"
  inlineMarker?: string;
  // The comment placed on top of the linked code snippet, <url> will be replaced with the URL
  // of the link. If undefined, no comment will be added.
  // Default: undefined
  originComment?: string;
  // Function that gets called with an error if a fetch fails. If undefined, the error will be
  // ignored.
  // Default: undefined
  logError?: (error: Error) => void;
  // The root path of the project, used to resolve relative paths. Ideally use an absolute path.
  // Default: process.cwd()
  rootPath?: string;
};
\`\`\`

This is the `.prettierrc.json` file:

\`\`\`json
{
  "bracketSpacing": true,
  "trailingComma": "all",
  "tabWidth": 2,
  "printWidth": 96
}
\`\`\`

Please note that you need the starting and ending line numbers in the URL to get the correct code snippet.

Options

rootPath

The base path that is used to resolve relative paths. Default: process.cwd().

inlineMarker

The string that is used to identify links that should be replaced with code snippets. Default: inline.

originComment

A comment that is placed on top of the linked code snippet. The string <url> will be replaced with the URL of the link. Default: undefined.

Supported languages

• JavaScript
• TypeScript
• Python
• Shell
• JSON
• YAML
• Terraform
• HCL
• Go

Adding a new language is easy, feel free to open a PR if your favorite language is missing.

License

MIT License © DanielMSchmidt