Fix Documentation Heading Hierarchy

[gxjansen]

Overview

This PR introduces an automated fix for heading levels across our documentation files. The script ensures proper heading hierarchy by making the highest-level heading in the content H2 (since H1 is reserved for the page title in frontmatter) and adjusting all subsequent heading levels accordingly.

Besides the script, it was also applied, resulting in:

• Total files checked: 6270
• Files that needed heading changes: 35
• Total headings adjusted: 233

Implementation

Added fix-headings.js script that:

• Preserves frontmatter and code blocks (and any other text that is not a header)
• Detects the current highest heading level in each file
• Shifts heading levels to start at H2
• Maintains relative heading hierarchy
• Can process specific files or all markdown files in /docs/

Why?

SEO, accessibility, consistency and of course to improve our Conductor scores... 😅

Testing

The script includes validation and error handling:

• Preserves files that already have correct heading hierarchy
• Skips files without headings
• Maintains code blocks unchanged
• Provides detailed processing statistics after the script has run (total files checked, total files changed, total headings changed)

Usage

Run without arguments to process all markdown files in /docs/:node _scripts/fix-headings.js

Or specify particular files:node _scripts/fix-headings.js path/to/file.md

Checklist

• I agree with the Code Contribution License Agreement in CONTRIBUTING.md

[andriitserkovnyi]

Was merged in #2994