add more docs, a few renames

Author: pngwn

src/format/highlight.test.ts renamed to src/format/code.test.ts

@@ -5,7 +5,7 @@ import type { Root, Paragraph } from "mdast";
 import unified from "unified";
 import markdown from "remark-parse";
 
-import { highlight, highight_code_block } from "./highlight";
+import { highlight, highight_code_block } from "./code";
 
 const _highlight = suite("highlight");
 const highlight_block = suite("highight_code_block");

src/format/highlight.ts renamed to src/format/code.ts

@@ -19,6 +19,9 @@ enum LanguageMap {
 	"" = "",
 }
 
+/**
+ * Custom highlighting for code blocks using PrismJS.
+ */
 export function highlight(source: string, lang?: language): string {
 	const plang = lang === "" ? "" : LanguageMap[lang];
 	const highlighted = plang
@@ -31,12 +34,18 @@ export function highlight(source: string, lang?: language): string {
 	return `<div class="code-block"><pre class='language-${plang}'><code>${highlighted}</code></pre></div>`;
 }
 
+/**
+ * Custom highlighting for code blocks using PrismJS.
+ */
 export function highight_code_block(): Transformer {
 	return function transformer(tree) {
 		visit(tree, "code", (node: Code) => {
 			node.value = highlight(node.value, node.lang as language);
 			//@ts-ignore
 			node.data = {};
+			// data.code_block is set so we can differentiate between code blocks and other raw nodes
+			// this is utilised in a rehype plugin later in the pipeline (split-view)
+			// retaining this metadata requires a custom handler for raw nodes when converting MDAST -> HAST
 			node.data.code_block = true;
 			((node as unknown) as HTML).type = "html";
 		});

src/format/format_api.ts

@@ -17,12 +17,13 @@ import stringify from "rehype-stringify";
 import vFile from "vfile";
 
 import {
+	strip_h1,
 	linkify_headings,
 	validate_headings,
 	increment_headings,
 } from "./headings";
-import { links } from "./links";
-import { highight_code_block } from "./highlight";
+import { set_link_attributes } from "./links";
+import { highight_code_block } from "./code";
 import { parse_frontmatter } from "./frontmatter";
 import { split_view } from "./split_view";
 import { custom_vfile, section } from "./types";
@@ -38,10 +39,11 @@ const { process } = unified()
 	.use(extract_frontmatter)
 	//  MDAST transforms
 	.use(parse_frontmatter)
+	.use(strip_h1)
 	.use(increment_headings)
 	.use(validate_headings)
 	.use(linkify_headings)
-	.use(links)
+	.use(set_link_attributes)
 	.use(highight_code_block)
 	// MDAST -> HAST
 	.use(rehype, {

src/format/links.test.ts

@@ -5,9 +5,9 @@ import { Root, Paragraph } from "mdast";
 import unified from "unified";
 import markdown from "remark-parse";
 
-import { links } from "./links";
+import { set_link_attributes } from "./links";
 
-const processor = unified().use(markdown).use(links);
+const processor = unified().use(markdown).use(set_link_attributes);
 
 const _links = suite("links");
 

src/format/links.ts

@@ -3,7 +3,11 @@ import type { Link, HTML } from "mdast";
 
 import visit from "unist-util-visit";
 
-export function links(): Transformer {
+/**
+ * All links must have `rel="noopener noreferrer"` and external attributes
+ * 				must open in a new window.
+ */
+export function set_link_attributes(): Transformer {
 	return function transformer(tree) {
 		visit(tree, "link", (node: Link) => {
 			let target_attr = "";

src/format/split_view.test.ts

@@ -7,7 +7,7 @@ import rehype from "remark-rehype";
 import stringify from "rehype-stringify";
 import vFile from "vfile";
 
-import { highight_code_block } from "./highlight";
+import { highight_code_block } from "./code";
 import { split_view } from "./split_view";
 
 import u from "unist-builder";

src/format/split_view.ts

@@ -3,6 +3,16 @@ import type { Parent } from "unist";
 import { custom_vfile } from "./types";
 import visit from "unist-util-visit";
 
+/**
+ * The svelte docs have a special two-column display for code examples. This
+ * 				allows arbitrary content to appear alongside a highlighted code example.
+ *
+ * This formatting starts at `***` (a `hr`) and ends with the next fenced code block. All
+ * 				of this content is wrappeed in `<div class="side-by-side" />`. then there
+ * 				are two nested divs `<div class="copy" />` which contains the arbirtary
+ * 				content *up to* the code block and `<div class="code" />` which contains
+ * 				the code block itself.
+ */
 export function split_view(): Transformer {
 	return function (tree, vFile: custom_vfile) {
 		if (vFile.data.docs_type !== "docs") return;
@@ -23,16 +33,20 @@ export function split_view(): Transformer {
 					children: [],
 				};
 
+				// starting from the current node, we iterate the children of the parent
+				// when we find the next code block (which is a `raw` node at this point)
+				// we stop, as we have all of the content
 				for (let index = i + 1; index < parent.children.length; index++) {
 					const _node = parent.children[index];
 
 					if (!_node) break;
 
+					// data.code_block is set as meta data when highlight code blocks in another transform
 					if (_node.data && _node.data.code_block) {
 						const parts = parent.children.splice(i + 1, index - i);
-						parts.pop();
+
 						left.children = parts;
-						right.children.push(_node);
+						right.children.push(parts.pop());
 						break;
 					}
 				}