Skip to content

GLFM HTML formatting Part 2: Styling, numbering, and table of contents

Chad Woolley requested to merge caw-glfm-format-html-part-2 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 2 of multiple MRs to implement this formatting. In this part, we add logic for:

  • Basic styling to match the CommonMark spec
  • Formatting markdown+html examples in two columns to match the CommonMark spec
  • Adding numbered example names, with consistent numbering of examples across all separate specification files (see comments in code for details).
  • Adding anchors for headers and a Table of Contents

This also eliminates the 'golden master snapshot style' assertion for the rendered HTML in the describe 'writing output html files' of spec/scripts/lib/glfm/update_specification_spec.rb, which was brittle and hard to maintain as the GLFM markdown rendering logic evolved on the backend. Now, we do more minimal and targeted regex-based testing of the HTML. This is also explained in more detail in code comments).

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 HTML should render with all the new features as described above.

MR acceptance checklist

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

Merge request reports