When writing an article that includes code snippets, it is often useful to have the complete code together in a file or a section at the end. But using markdown’s regular code blocks would mean a lot of duplicated text and possible discrepancies between the snippets and the final code (if I forget to update the code in both places).
There is already a Remark plugin to do this, but I wanted to be able to specify the code files in the frontmatter, which this plugin doesn’t support.
RemarkCodeSnippets
With my own plugin I can specify one or more code files in the frontmatter, as a string, a list of strings, or a dictionary.
---
code: "path/to/code.py"
---
<!-- or -->
---
code:
- "path/to/code.py"
- "path/to/code.R"
---
<!-- or -->
---
code:
py: "path/to/code.py"
r: "path/to/code.R"
---
And then I can reference the code in the markdown using :code:.
<!-- Gives the only/first code file -->
:code:
<!-- Gives the first code file -->
:code[0]:
<!-- Gives the code file named py -->
:code[py]:
It is also possible to reference a range of lines in the code file.
<!-- Gives lines 5-10 in the only/first code file -->
:code[5,10]:
<!-- Gives lines 5-10 in the first code file -->
:code[0][5,10]:
<!-- Gives lines 5-10 in the code file named py -->
:code[py][5,10]:
Example (this page)
---
title: A Remark Plugin for Easier Code Snippets
date: 2024-05-29
tags:
- remark
- markdown
code:
:code[5,10]:
<!-- Gives lines 5-10 in the first code file -->
:code[0][5,10]:
<!-- Gives lines 5-10 in the code file named py -->
Plugin Code
import { readFile } from "fs/promises";
import type { Code, Root, Text } from "mdast";
import { visit } from "unist-util-visit";
import type { VFile } from "vfile";
export default function remarkCodeSnippets() {
async function transform(tree: Root, file: VFile): Promise<void> {
// Get code file/s from Astro frontmatter
const fmCode = file.data.astro?.frontmatter?.code as
string | string[] | Record<string, string>;
// If no code file/s are specified, do nothing
if (!fmCode) return;
// Create an array to store the code file/s
const codeList: {
name: string;
path: string;
lines: string[];
ext: string;
}[] = [];
const readCodeFile = async (path: string, name?: string) => {
const fileContent = await readFile(path, "utf8");
return {
name: name || "default",
path: path,
ext: path.split(".").pop()?.toLowerCase() || "",
lines: fileContent.split("\n"),
};
};
if (typeof fmCode === "string") {
codeList.push(await readCodeFile(fmCode));
} else if (Array.isArray(fmCode)) {
codeList.push(
...(await Promise.all(fmCode.map((item) => readCodeFile(item)))),
);
} else {
codeList.push(
...(await Promise.all(
Object.entries(fmCode).map(([name, path]) =>
readCodeFile(path, name),
),
)),
);
}
const getSnippet = (listIndex?: string, start?: string, end?: string) => {
let codeItem;
if (!listIndex) {
// No index specified, use first
codeItem = codeList[0];
} else if (Number.isInteger(Number(listIndex)) && Number(listIndex) > 0) {
// Index is an integer
codeItem = codeList?.[Number(listIndex)] || codeList[0];
} else {
// Index is a string, use first item that matches, if no match use first
codeItem =
codeList.find((item) => item.name == listIndex) || codeList[0];
}
if (!start || !end)
return { snippet: codeItem.lines.join("\n"), ext: codeItem.ext };
const startNum = Math.max(0, +start - 1);
const endNum = Math.min(codeItem.lines.length, +end);
const snippet =
startNum < endNum
? codeItem.lines.slice(startNum, endNum).join("\n")
: "";
return { snippet, ext: codeItem.ext };
};
visit(tree, "text", (node: Text, index, parent) => {
const regex = /:code(?:\[(\w+)\])?(?:\[(\d+),(\d+)\])?:/g;
if (!node.value.match(regex) || !parent || index === undefined) return;
const parts = node.value.split(regex);
const newNodes: Array<Text | Code> = [];
for (let i = 0; i < parts.length; i += 4) {
if (parts[i]) newNodes.push({ type: "text", value: parts[i] });
if (i + 1 < parts.length) {
const { snippet, ext } = getSnippet(
parts[i + 1],
parts[i + 2],
parts[i + 3],
);
newNodes.push({
type: "code",
value: snippet,
lang: ext,
});
}
}
if (newNodes.length > 0) {
parent.children.splice(index, 1, ...newNodes);
}
});
}
return transform;
}