allow linkification of different heading levels

pngwn · pngwn · commit cac2d00a8796 · 2021-04-11T16:56:40.000+01:00
diff --git a/src/format/fixtures/generateFixtures.ts b/src/format/fixtures/generateFixtures.ts
@@ -19,6 +19,7 @@ async function run() {
 		project: "svelte",
 		docs_type: "docs",
 		dir: "docs",
+		level: 3,
 	});
 	await fs.writeFile(output_path, `export default ${JSON.stringify(contents)}`);
 }
diff --git a/src/format/format_api.test.ts b/src/format/format_api.test.ts
@@ -47,6 +47,7 @@ console.log('boo')
 		project: "svelte",
 		docs_type: "docs",
 		dir: "docs/boo",
+		level: 3,
 	});
 
 	// console.log(x);
diff --git a/src/format/format_api.ts b/src/format/format_api.ts
@@ -38,6 +38,7 @@ interface Format {
 	docs_type: docs_type;
 	dir: string;
 	seen_slugs?: Map<string, number>;
+	level: number;
 }
 
 // MDAST == Markdown AST
@@ -82,6 +83,7 @@ export async function format({
 	docs_type,
 	dir,
 	seen_slugs = new Map(),
+	level,
 }: Format): Promise<custom_vfile> {
 	const sections: section[] = [];
 	const section_title = file.toLowerCase().endsWith("readme.md")
@@ -103,7 +105,8 @@ export async function format({
 			dir,
 			file_type: file.toLowerCase().endsWith("readme.md") ? "readme" : "other",
 			docs_type,
-			prev_level: 3,
+			base_level: level,
+			prev_level: level,
 			slugs: [],
 		},
 	});
diff --git a/src/format/headings.test.ts b/src/format/headings.test.ts
@@ -38,9 +38,11 @@ _headings("transforms and formats headings", async () => {
 		contents: `### hello`,
 		data: {
 			dir: "blog",
+			docs_type: "docs",
 			sections,
 			section_stack: [sections],
 			section_title: "section",
+			base_level: 3,
 			prev_level: 3,
 			slugs: [],
 			seen_slugs: new Map(),
@@ -64,9 +66,11 @@ _headings("transforms and formats multi-level headings", async () => {
 `,
 		data: {
 			dir: "blog",
+			docs_type: "blog",
 			sections,
 			section_stack: [sections],
 			section_title: "section",
+			base_level: 3,
 			prev_level: 3,
 			slugs: [],
 			seen_slugs: new Map(),
@@ -94,9 +98,11 @@ _headings("transforms and formats multi-level headings", async () => {
 `,
 		data: {
 			dir: "blog",
+			docs_type: "blog",
 			sections,
 			section_stack: [sections],
 			section_title: "section",
+			base_level: 3,
 			prev_level: 3,
 			slugs: [],
 			seen_slugs: new Map(),
@@ -107,13 +113,13 @@ _headings("transforms and formats multi-level headings", async () => {
 
 	assert.equal(
 		output.contents,
-		`<h3><span id="section-subsection-1" class="offset-anchor"></span><a href="blog#section-subsection-1" class="anchor" aria-hidden></a>subsection</h3>
-<h4><span id="section-subsection-1-subsubsection" class="offset-anchor"></span><a href="blog#section-subsection-1-subsubsection" class="anchor" aria-hidden></a>subsubsection</h4>
-<h5><span id="section-subsection-1-subsubsection-subsubsubsection" class="offset-anchor" data-scrollignore></span><a href="blog#section-subsection-1-subsubsection-subsubsubsection" class="anchor" aria-hidden></a>subsubsubsection</h5>`
+		`<h3><span id="section-subsection" class="offset-anchor"></span><a href="blog#section-subsection" class="anchor" aria-hidden></a>subsection</h3>
+<h4><span id="section-subsection-subsubsection" class="offset-anchor"></span><a href="blog#section-subsection-subsubsection" class="anchor" aria-hidden></a>subsubsection</h4>
+<h5><span id="section-subsection-subsubsection-subsubsubsection" class="offset-anchor" data-scrollignore></span><a href="blog#section-subsection-subsubsection-subsubsubsection" class="anchor" aria-hidden></a>subsubsubsection</h5>`
 	);
 });
 
-_headings.only("transforms and formats multi-level headings", async () => {
+_headings("transforms and formats multi-level headings", async () => {
 	const sections: unknown[] = [];
 	const src = vFile({
 		contents: `### subsection
@@ -133,9 +139,11 @@ _headings.only("transforms and formats multi-level headings", async () => {
 `,
 		data: {
 			dir: "blog",
+			docs_type: "blog",
 			sections,
 			section_stack: [sections],
 			section_title: "section",
+			base_level: 3,
 			prev_level: 3,
 			slugs: [],
 			seen_slugs: new Map(),
@@ -156,6 +164,54 @@ _headings.only("transforms and formats multi-level headings", async () => {
 	);
 });
 
+_headings(
+	"transforms and formats multi-level headings: level 2 headings",
+	async () => {
+		const sections: unknown[] = [];
+		const src = vFile({
+			contents: `## subsection
+
+### subsubsection
+
+#### subsubsubsection
+
+## one
+
+### two
+
+#### three
+
+### four
+
+`,
+			data: {
+				dir: "blog",
+				docs_type: "blog",
+				sections,
+				section_stack: [sections],
+				section_title: "section",
+				base_level: 2,
+				prev_level: 2,
+				slugs: [],
+				seen_slugs: new Map(),
+			},
+		});
+
+		const output = await linkify_only(src);
+
+		assert.equal(
+			output.contents,
+			`<h2><span id="section-subsection" class="offset-anchor"></span><a href="blog#section-subsection" class="anchor" aria-hidden></a>subsection</h2>
+<h3><span id="section-subsection-subsubsection" class="offset-anchor"></span><a href="blog#section-subsection-subsubsection" class="anchor" aria-hidden></a>subsubsection</h3>
+<h4><span id="section-subsection-subsubsection-subsubsubsection" class="offset-anchor" data-scrollignore></span><a href="blog#section-subsection-subsubsection-subsubsubsection" class="anchor" aria-hidden></a>subsubsubsection</h4>
+<h2><span id="section-one" class="offset-anchor"></span><a href="blog#section-one" class="anchor" aria-hidden></a>one</h2>
+<h3><span id="section-one-two" class="offset-anchor"></span><a href="blog#section-one-two" class="anchor" aria-hidden></a>two</h3>
+<h4><span id="section-one-two-three" class="offset-anchor" data-scrollignore></span><a href="blog#section-one-two-three" class="anchor" aria-hidden></a>three</h4>
+<h3><span id="section-one-four" class="offset-anchor"></span><a href="blog#section-one-four" class="anchor" aria-hidden></a>four</h3>`
+		);
+	}
+);
+
 strip("strips leading level 1 headings", async () => {
 	const src = `
 	
diff --git a/src/format/headings.ts b/src/format/headings.ts
@@ -17,12 +17,14 @@ const make_slug = make_session_slug_processor({
 	separator: SLUG_SEPARATOR,
 });
 
+// TODO: This should use the `base_level` setting
 /**
  * The documentation only allows heading level from 3 to 5 inclusive. This plugin
  * 				validates that rule is always followed.
  */
 export function validate_headings(): Transformer {
-	return function transformer(tree) {
+	return function transformer(tree, { data }: custom_vfile) {
+		if (data.docs_type !== "docs") return;
 		visit(tree, "heading", (node: Heading) => {
 			if (node.depth < 3 || node.depth > 5)
 				throw new Error(
@@ -63,6 +65,8 @@ type Heading_with_hProps = Heading & {
 
 export function linkify_headings(): Transformer {
 	return function (tree, { data }: custom_vfile) {
+		if (data.docs_type !== "docs" && data.docs_type !== "blog") return;
+
 		visit(tree, "heading", (node: Heading_with_hProps) => {
 			const prev_section = data.section_stack[data.section_stack.length - 1];
 
@@ -75,7 +79,7 @@ export function linkify_headings(): Transformer {
 			const title_text = tree_to_string(node);
 
 			let slug = make_slug(
-				node.depth === 3
+				node.depth === data.base_level
 					? [data.section_title, title_text].join(" ")
 					: [data.slugs[data.slugs.length - 1], title_text].join(" "),
 				data.seen_slugs
@@ -85,6 +89,9 @@ export function linkify_headings(): Transformer {
 
 			// We keep a 'section_stack' to keep track of the section structure
 			if (node.depth > data.prev_level) {
+				// TODO: check that prev_section[prev_section.length - 1] exists
+				// skipping heading levels can cause problems here
+				// maybe check current level against prev_level to validate?
 				data.section_stack.push(
 					prev_section[prev_section.length - 1].sections || []
 				);
@@ -122,8 +129,9 @@ export function linkify_headings(): Transformer {
 				},
 			};
 
-			//@ts-ignore
-			if (node.depth > 4) span_node.properties["data-scrollignore"] = true;
+			if (node.depth > data.base_level + 1)
+				//@ts-ignore
+				span_node.properties["data-scrollignore"] = true;
 
 			node.data.hChildren = [span_node, a_node];
 
diff --git a/src/format/types.ts b/src/format/types.ts
@@ -14,6 +14,7 @@ export type custom_vfile = VFile & {
 	data: {
 		sections: section[];
 		section_stack: section[][];
+		base_level: number;
 		prev_level: number;
 		section_title: string;
 		section_slug: string;
diff --git a/src/fs/get_content.ts b/src/fs/get_content.ts
@@ -1,7 +1,7 @@
 import { promises as fs } from "fs";
 import * as path from "path";
 
-type SimpleFile = {
+export type SimpleFile = {
 	name: string;
 	content: SimpleFile[] | string;
 };
diff --git a/src/fs/index.ts b/src/fs/index.ts
@@ -1 +1 @@
-export { get_docs, DocFiles } from "./get_content";
+export { get_docs, DocFiles, SimpleFile } from "./get_content";
diff --git a/src/transform/docs.test.ts b/src/transform/docs.test.ts
@@ -8,7 +8,17 @@ import {
 	examples_out_list,
 } from "./fixtures/examples";
 
-import { transform_docs, transform_examples } from "./docs";
+import {
+	tutorials_in,
+	tutorials_out_list,
+	tutorials_out_full,
+} from "./fixtures/tutorials";
+
+import {
+	transform_docs,
+	transform_examples,
+	transform_tutorials,
+} from "./docs";
 
 const _docs = suite("transform_docs");
 
@@ -22,4 +32,10 @@ _docs("transforms examples", async () => {
 	assert.equal(output, { list: examples_out_list, full: examples_out_full });
 });
 
+_docs("transforms examples", async () => {
+	const output = await transform_tutorials(tutorials_in, "svelte");
+	// console.log(JSON.stringify(output.full, null, 2));
+	assert.equal(output, { list: tutorials_out_list, full: tutorials_out_full });
+});
+
 _docs.run();
diff --git a/src/transform/docs.ts b/src/transform/docs.ts
diff --git a/src/transform/fixtures/tutorials.ts b/src/transform/fixtures/tutorials.ts
diff --git a/src/types.ts b/src/types.ts

Original file line number	Diff line number	Diff line change
`@@ -19,6 +19,7 @@ async function run() {`
`19`	`19`	`project: "svelte",`
`20`	`20`	`docs_type: "docs",`
`21`	`21`	`dir: "docs",`
	`22`	`+ level: 3,`
`22`	`23`	`});`
`23`	`24`	await fs.writeFile(output_path, `export default ${JSON.stringify(contents)}`);
`24`	`25`	`}`
Original file line number	Diff line number	Diff line change
`@@ -1 +1 @@`
`1`		`-export { get_docs, DocFiles } from "./get_content";`
	`1`	`+export { get_docs, DocFiles, SimpleFile } from "./get_content";`