Add `generate-node-sdk-pages` script for making polished Node SDK pages by myarmolinsky · Pull Request #3348 · balena-io/docs

myarmolinsky · 2026-03-24T00:24:37Z

Fibery: https://balena.fibery.io/Work/Project/Identify-the-next-steps-for-improving-growing-our-docs-2317
Improvement: https://balena.fibery.io/Work/Improvement/SDKs-(and-probably-other-generated-external-doc-pages)-Internal-linking-is-not-working-3947
Change-type: patch

Please make sure to read the CONTRIBUTING document before opening the PR for relevant information on contributing to the documentation. Thanks!

Change-type: patch

Change-type: minor

Change-type: patch

drskullster · 2026-04-07T20:21:14Z

+const inputPath = path.resolve(nodeSDKDocsDir);
+const outputDir = path.join(__dirname, '../pages/reference/sdk/node-sdk');
+const outputPath = path.resolve(outputDir);
+const semver = require('semver'); // If you have semver installed, otherwise use a regex split


leftover AI comment

klutchell · 2026-04-08T17:19:55Z

+				},
+			);
+
+			// Some auth model methods have a md links hardcoded as `#balena.models.auth.X`
+			// This should correct them to `#X`
+			sectionContent = sectionContent.replace(
+				/\[([^\]]+)\]\(#balena\.(?:.*\.)?([^.)]+)\)/g,
+				'[$1](#$2)',


The content splitting relies on hardcoded string markers (\n## Modules, \n## balena-sdk\n, <a name="balena"></a>, <a name="balena.errors"></a>). If the upstream SDK docs change the order of these sections, rename them, or alter the anchor formatting, the script will silently produce garbage output or crash.

Consider adding guards after each split to make failures explicit, e.g.:

if (firstSplitParts.length < 2) { console.error(`Expected "## Modules" marker not found in ${file}`); process.exit(1); }

Same for secondSplitParts, thirdSplitParts, and fourthSplitParts.

klutchell · 2026-04-08T17:20:34Z

+const inputPath = path.resolve(nodeSDKDocsDir);
+const outputDir = path.join(__dirname, '../pages/reference/sdk/node-sdk');
+const outputPath = path.resolve(outputDir);
+const semver = require('semver'); // If you have semver installed, otherwise use a regex split


Beyond removing that, require('semver') should be moved to the top of the file with the other requires rather than being buried after variable declarations.

klutchell · 2026-04-08T17:20:54Z

+
+	for (const item of items) {
+		if (item.name === 'README.md') {


At level === 0, items.sort(sortVersions) runs over all directory entries. If a non-version entry (stray .DS_Store, etc.) appears at this level, semver.rcompare will throw and fall through to the localeCompare fallback. Harmless today, but worth either filtering to directories-only before sorting, or adding a comment noting the assumption.

klutchell · 2026-04-08T17:21:15Z

+	let lines = content.split('\n');
+
+	return lines
+		.map((line) => {
+			const headingMatch = line.match(/^(#{2,6})\s(.*)/);
+			if (headingMatch) {


flattenHeadings converts anything deeper than ### into bold text. The comment says this is to stay within GitBook's hierarchy, but it means any #### (or deeper) headings in the SDK docs -- commonly used for method parameters and return values -- lose their semantic heading status and become unlinkable bold paragraphs.

Is that an acceptable tradeoff? If GitBook truly only supports 3 levels, it's fine, but worth confirming and documenting here.

klutchell · 2026-04-08T17:21:39Z

  "scripts": {
    "test": "npm run sync-external -- --dry-run && npm run renovate:validate",
-    "sync-external": "node tools/sync-external.js",
+    "sync-external": "node tools/sync-external.js && npm run generate-node-sdk-pages",


Chaining generate-node-sdk-pages into sync-external unconditionally means every sync-external invocation regenerates all SDK pages even if nothing in the SDK source docs changed.

Worth considering either making it a separate CI step that only triggers if the target is the Node SDK.

klutchell · 2026-04-08T17:24:44Z

+			// The regex captures the 3 specific pieces of data we need to build the new string
+			const anchorHeadingsPattern =
+				/(?:\*\s\*\s\*\s*)?<a name="([^"]+)"><\/a>\s*(#+)\s*([^\n\r]+)/g;
+
+			// The replacement string references those captured groups using $1, $2, and $3
+			sectionContent = sectionContent.replace(
+				anchorHeadingsPattern,
+				'$2 $1\n**$3**',
+			);


The content splitting here relies on hardcoded string markers (\n## Modules, \n## balena-sdk\n, <a name="balena"></a>, <a name="balena.errors"></a>). If the upstream SDK docs ever change the order, rename a section, or alter the anchor format, this will silently produce bad output or crash.

Would be good to add guards after each split, something like:

if (firstSplitParts.length < 2) { console.error(`Expected "## Modules" marker not found in ${file}`); process.exit(1); }

At least then failures are obvious instead of generating broken pages.

klutchell · 2026-04-08T17:28:33Z

+				idx > startIndex &&
+				line.trim().startsWith('* [') &&
+				!line.startsWith('    '), // Not deeply indented
+		);


The endIndex logic for finding where the Node SDK section ends is fragile. It looks for the next line starting with * [ that isn't indented by 4+ spaces, but if someone changes the indentation style in SUMMARY.md or adds a non-standard line, this could eat content from adjacent sections (like Python SDK).

Consider matching more specifically, e.g. looking for the next sibling-level entry at the exact same indent depth as the Node SDK line rather than relying on "not deeply indented."

klutchell · 2026-04-08T17:33:24Z

+		} else {
+			// The regex captures the 3 specific pieces of data we need to build the new string
+			const anchorHeadingsPattern =
+				/(?:\*\s\*\s\*\s*)?<a name="([^"]+)"><\/a>\s*(#+)\s*([^\n\r]+)/g;


This anchorHeadingsPattern regex and the subsequent multi-capture-group sectionContent.replace calls are doing non-trivial transformations. Some inline comments showing the before/after for each transform would help future maintainers understand what these are doing without having to mentally execute the regex. For example:

// Before: <a name="balena.auth.authenticate"></a> // ##### balena.auth.authenticate(credentials) ⇒ <code>Promise</code> // // After: ##### balena.auth.authenticate // **balena.auth.authenticate(credentials) ⇒ <code>Promise</code>**

klutchell · 2026-04-08T17:34:53Z

+function splitDocs(inputDir, outputDir) {
+	// Create base output directory if it doesn't exist
+	if (fs.existsSync(outputDir)) {
+		fs.rmSync(outputDir, { recursive: true, force: true });


The script rm -rfs the output directory and regenerates from scratch every time. The third commit commits the generated output, but there's nothing preventing someone from editing these files by hand and having their changes silently blown away on the next run.

Two suggestions:

Add a header comment to each generated file, e.g. 

Consider adding a note in a README or .gitattributes marking these as generated.

klutchell · 2026-04-08T17:36:38Z

+	return lines;
+}
+
+function flattenHeadings(content) {


flattenHeadings converts anything deeper than ### into bold text to fit GitBook's hierarchy constraints. Just want to confirm that's acceptable for the SDK docs, since any #### headings (e.g. for method parameters or return values) will lose their semantic heading status and won't be linkable.

myarmolinsky force-pushed the split-sdk-docs-into-pages branch 3 times, most recently from 0234eef to 81cd5ab Compare March 30, 2026 15:26

myarmolinsky force-pushed the split-sdk-docs-into-pages branch 15 times, most recently from 3ec4cd2 to 451d8af Compare April 7, 2026 19:05

myarmolinsky changed the title ~~generate-node-sdk-pages script~~ Add generate-node-sdk-pages script for making polished Node SDK pages Apr 7, 2026

myarmolinsky force-pushed the split-sdk-docs-into-pages branch from 451d8af to 12e34d2 Compare April 7, 2026 19:44

myarmolinsky added 3 commits April 7, 2026 16:32

Add dev dependency semver

182c079

Change-type: patch

Add generate-node-sdk-pages script for making polished Node SDK pages

d3b0375

Change-type: minor

Run generate-node-sdk-pages script

c6ec2dc

Change-type: patch

myarmolinsky force-pushed the split-sdk-docs-into-pages branch from 12e34d2 to c6ec2dc Compare April 7, 2026 20:33

drskullster reviewed Apr 8, 2026

View reviewed changes

klutchell reviewed Apr 8, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add `generate-node-sdk-pages` script for making polished Node SDK pages#3348

Add `generate-node-sdk-pages` script for making polished Node SDK pages#3348
myarmolinsky wants to merge 3 commits intomainfrom
split-sdk-docs-into-pages

myarmolinsky commented Mar 24, 2026 •

edited

Loading

Uh oh!

drskullster Apr 7, 2026

Uh oh!

klutchell Apr 8, 2026

Uh oh!

klutchell Apr 8, 2026

Uh oh!

klutchell Apr 8, 2026

Uh oh!

klutchell Apr 8, 2026

Uh oh!

klutchell Apr 8, 2026

Uh oh!

klutchell Apr 8, 2026

Uh oh!

klutchell Apr 8, 2026

Uh oh!

klutchell Apr 8, 2026

Uh oh!

klutchell Apr 8, 2026

Uh oh!

klutchell Apr 8, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Conversation

myarmolinsky commented Mar 24, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

myarmolinsky commented Mar 24, 2026 •

edited

Loading