Add optional GitHub Markdown styling

[stephen-clark-bbc]

Summary

• Adds build-time syntax highlighting and improved code-block presentation.

• Adds line-level highlighting for standard and language-specific diffs.

• Adds an optional GitHub-style presentation mode while preserving Morty Docs’ original styling as the default.

• Adds GitHub-style alerts—including icons and background treatments for notes, tips, warnings, cautions, and important content.

• Preserves lightweight, browser-rendered Mermaid diagrams in both presentation modes.

See

Diff highlighting

What changed

• Adds markdownStyle: 'github' as an opt-in presentation mode.

• Preserves the original Morty Docs presentation when the option is omitted or set to original.

• Adds syntax highlighting during site generation using Highlight.js.

  • Highlight.js is installed as a pinned npm dependency.
  • Highlighted HTML is generated before the page reaches the browser.
  • Generated pages do not load syntax-highlighting JavaScript or depend on an external syntax-highlighting CDN.

• Provides syntax highlighting in both presentation modes.

• Adds line-level highlighting for standard and language-specific diff blocks, such as diff yaml.

• Includes support and test coverage for JavaScript, YAML, C#, and other supported languages.

• Preserves Mermaid diagram rendering in both presentation modes.

  • Mermaid remains browser-rendered and is not added as a Morty Docs dependency.
  • Production retains the existing /morty-docs/mermaid.min.js hosting contract.
  • Local previews provision a pinned, checksum-verified Mermaid runtime in the ignored www directory.

• Adds GitHub-style headings, permalinks, alerts, tables, code blocks, and responsive presentation.

• Preserves separate paragraphs within Markdown alerts.

• Documents the code-wrapping differences between the original and GitHub presentation modes.

• Includes the Highlight.js BSD licence in the published npm package.

• Preserves intentional dotfiles and dot-directories while excluding .DS_Store metadata.

Usage

transform(inputObjects, {
contentTitle: 'My documentation',
basePath: '/docs',
markdownStyle: 'github'
})

The original presentation remains the default:

transform(inputObjects, {
contentTitle: 'My documentation',
basePath: '/docs',
markdownStyle: 'original'
})

The markdownStyle option can also be omitted.

Local preview

To preview the GitHub-style presentation:

markdownStyle=github npm start

Then open:

http://localhost:8080/morty-docs/some-repo/github-markdown-style.html

To preview the original presentation:

npm start

Then open the same URL.

The local preview downloads a pinned Mermaid browser runtime and verifies its SHA-256 checksum. This asset remains inside
the ignored www directory and is not committed or included in the published package.

Security and reliability

• Syntax highlighting happens during generation rather than in the browser.
• Unknown and oversized code blocks remain safely escaped.
• Limits are applied to the amount of code passed to Highlight.js.
• Typed diff metadata is handled by the Markdown renderer without rewriting the source Markdown.
• Mermaid uses its strict security mode.
• Local Mermaid preview assets are pinned and checksum-verified.
• Regression coverage includes nested fences, unsafe language identifiers, oversized blocks, checksum failures, and
  cumulative highlighting limits.

Verification

• 90 tests passing.
• 19 snapshots passing.
• Lint passing.
• Production build passing.
• Production dependency audit reports no known vulnerabilities.
• Generated output checked with GitHub styling enabled and disabled.
• Syntax highlighting, diff highlighting, alerts, and Mermaid diagrams verified in both modes.
• Mermaid rendering verified in a browser engine from a clean local preview.
• npm package dry run verified, including the Highlight.js licence notice and no bundled Mermaid payload.