Skip to content

GLFM HTML formatting Part 1: Split GLFM examples in rendered HTML

Chad Woolley requested to merge caw-glfm-format-html-part-1 into master

What does this MR do and why?

Related: Tracking Issue: Implement GLFM scripts per the ... (#361241)

Updates scripts/glfm/update-specification.rb logic for generating spec.html and snapshot_spec.html to use the similar standard formatting, e.g. example numbering, as the official CommonMark/GHFM rendered spec.html. This will require simulating the formatting of the Lua script and template from the CommonMark project

This MR is Part 1 of multiple MRs to implement this formatting. In this part, we add logic to split the code blocks for the standard backtick-delimited example blocks into two separate blocks, so they can be independently styled in the rendered HTML (via future MRs to add this styling).

Additional context and motivation for this formatting

Since we've realized that GitHub is not keeping their HTML rendered version up to date, we have no source of correctly-numbered rendered examples to refer to when writing and debugging the snapshot examples. This means the GitHub HTML-rendered spec's numbering is out of sync with our glfm_example_status.yml, which is our source of truth for driving all the snapshot testing.

So, my goal is to at least get enough formatting into our rendered HTML versions, so they have correctly numbered examples matching our glfm_example_status.yml, and look somewhat decent.

I also may need to get creative about how I approach the numbering, since the official spec.txt is now a subset of the snapshot_spec.md, but we also want the example numbers to still match up with the CommonMark and GitHub Flavored Markdown examples. I may end up starting the numbering our GLFM examples at a "high number", like 10000 or something, so there's no overlap with the CommonMark/GHFM example numbering.

References

See the GLFM Specification Guide development documentation for much more context on all of this work: https://docs.gitlab.com/ee/development/gitlab_flavored_markdown/specification_guide

How to set up and validate locally

  1. Run scripts/glfm/update-specification.rb and ensure it works. I.e. there should be no changes to committed version of spec.html and snapshot_spec.html, and the examples should be rendered as separate code blocks.

MR acceptance checklist

This checklist encourages us to confirm any changes have been analyzed to reduce risks in quality, performance, reliability, security, and maintainability.

Edited by Chad Woolley

Merge request reports