Add support for nesting GLFM examples in H3s

What does this MR do and why?

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

Allows GitLab Flavored Markdown examples in the glfm_canonical_examples.txt file to be nested within H3 headings.

Previously they could only be nested with H2 headings.

Also adds a corresponding third-level to the automatic hierarchical numbering of examples in the GLFM Example Snapshot files.

See also docs on update-example-snapshots.rb script: https://docs.gitlab.com/ee/development/gitlab_flavored_markdown/specification_guide/#update-example-snapshotsrb-script

Tasks

• Add logic supporting H3s
• Update corresponding docs
• Update all existing example snapshot files to new format

How to set up and validate locally

1. Run scripts/glfm/update-example-snapshots.rb and ensure there are no failures or changes (expected changes to *.yml files may occur after a rebase).
2. Review documentation changes in the MR for correctness.

MR acceptance checklist

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

• I have evaluated the MR acceptance checklist for this MR.

changed milestone to %15.3

added GLFM backend devopscreate featureenhancement groupeditor [DEPRECATED] markdown sectiondev typefeature workflowpost-deploy-db-production labels

assigned to @cwoolley-gitlab

Suggested Reviewers (beta)

The individuals below may be good candidates to participate in the review based on various factors.

You can use slash commands in comments to quickly assign /assign_reviewer @user1.

Suggested Reviewers
@aqualls, @alyubenkov, @digitalmoksha, @ealcantara, @oregand

If you do not believe these suggestions are useful, please apply the label Bad Suggested Reviewer. You can also provide feedback for this feature on this issue: https://gitlab.com/gitlab-org/gitlab/-/issues/357923.

Automatically generated by Suggested Reviewers Bot - an experimental ML-based recommendation engine created by ~"group::applied ml".

added documentation label

	2 Warnings
	This merge request is definitely too big (6050 lines changed), please split it into multiple merge requests.
	14a71c2a: The commit subject must contain at least 3 words. For more information, take a look at our Commit message guidelines.

	2 Messages
	CHANGELOG missing: If you want to create a changelog entry for GitLab FOSS, add the Changelog trailer to the commit message you want to add to the changelog. If you want to create a changelog entry for GitLab EE, also add the EE: true trailer to your commit message. If this merge request doesn't need a CHANGELOG entry, feel free to ignore this message.
	This merge request adds or changes documentation files. A review from the Technical Writing team before you merge is recommended. Reviews can happen after you merge.

Documentation review

The following files require a review from a technical writer:

• doc/development/gitlab_flavored_markdown/specification_guide/index.md

The review does not need to block merging this merge request. See the:

• Metadata for the *.md files that you've changed. The first few lines of each *.md file identify the stage and group most closely associated with your docs change.
• The Technical Writer assigned for that stage and group.
• Documentation workflows for information on when to assign a merge request for review.

Reviewer roulette

Changes that require review have been detected!

Please refer to the table below for assigning reviewers and maintainers suggested by Danger in the specified category:

Category	Reviewer	Maintainer
backend	John Mason (@john-mason) (UTC-4, 3 hours ahead of @cwoolley-gitlab)	Doug Stull (@dstull) (UTC-4, 3 hours ahead of @cwoolley-gitlab)

To spread load more evenly across eligible reviewers, Danger has picked a candidate for each review slot, based on their timezone. Feel free to override these selections if you think someone else would be better-suited or use the GitLab Review Workload Dashboard to find other available reviewers.

To read more on how to use the reviewer roulette, please take a look at the Engineering workflow and code review guidelines. Please consider assigning a reviewer or maintainer who is a domain expert in the area of the merge request.

Once you've decided who will review this merge request, assign them as a reviewer! Danger does not automatically notify them for you.

Uncategorized files

These files couldn't be categorized, so Danger was unable to suggest a reviewer. Please consider creating a merge request to add support for them.

• glfm_specification/example_snapshots/examples_index.yml
• glfm_specification/example_snapshots/html.yml
• glfm_specification/example_snapshots/markdown.yml
• glfm_specification/example_snapshots/prosemirror_json.yml
• glfm_specification/input/gitlab_flavored_markdown/glfm_example_normalizations.yml
• glfm_specification/input/gitlab_flavored_markdown/glfm_example_status.yml

If needed, you can retry the danger-review job that generated this comment.

Generated by Danger

added 1 commit

• 1eb932e9 - Run scripts/glfm/update-example-snapshots.rb

Compare with previous version

marked the checklist item Update all existing example snapshot files to new format as completed

added docs-review label

removed workflowpost-deploy-db-production label

marked this merge request as ready

mentioned in issue #361241 (closed)

changed the description

@morefice Would you like to take the first review for this, since you have already looked at this code before in Add some clarification to GLFM fixture (!94905 - merged)?

Note that there's only small amount of logic changes to two files, and the corresponding specs.

All of the other changes in *.yml files are due to the third level of hierarchy numbering being added for the examples. These are separated in a second commit for clarity (but this can be squashed down when merged).

requested review from @morefice

added 1288 commits

• 1eb932e9...043d3fac - 1286 commits from branch master
• 58624d8d - Add support for GLFM examples in H3s
• 462b09e2 - Run scripts/glfm/update-example-snapshots.rb

Compare with previous version

marked the checklist item I have evaluated the MR acceptance checklist for this MR. as completed

changed the description

@cwoolley-gitlab

Thanks this LGTM

Note that there's only small amount of logic changes to two files, and the corresponding specs.

It would be great to prioritize the refactoring of this class in smaller methods for better maintainability, looks like this is already on your radar.

---

@dstull could you review this MR please?

approved this merge request

requested review from @dstull and removed review request for @morefice

@morefice, thanks for approving this merge request.

This is the first time the merge request is approved. To ensure full test coverage, a new pipeline has been started.

For more info, please refer to the following links:

• rspec minimal jobs
• jest minimal jobs
• merging a merge request.

mentioned in commit 812ed197

added 122 commits

• 462b09e2...f2e75fe6 - 120 commits from branch master
• 812ed197 - Add support for GLFM examples in H3s
• 70888a3d - Run scripts/glfm/update-example-snapshots.rb

Compare with previous version

I see a few test failures came up with the last rebase, I'll be fixing these shortly.

mentioned in commit 4091bd02

added 2 commits

• 4091bd02 - Add support for GLFM examples in H3s
• 61eebd74 - Run scripts/glfm/update-example-snapshots.rb

Compare with previous version

mentioned in commit 50fa424e

added 2 commits

• 50fa424e - Add support for GLFM examples in H3s
• 14a71c2a - Run scripts/glfm/update-example-snapshots.rb

Compare with previous version

approved this merge request

resolved all threads

enabled an automatic merge when the pipeline for 09b163a0 succeeds

merged

mentioned in commit b0f9cbc8

mentioned in commit b2248031

resolved all threads

added workflowstaging-canary label

added workflowcanary label and removed workflowstaging-canary label

mentioned in commit pradosh987/gitlab@7fa8f5bd

added workflowstaging label and removed workflowcanary label

added workflowproduction label and removed workflowstaging label

added workflowpost-deploy-db-staging label and removed workflowproduction label

added workflowpost-deploy-db-production label and removed workflowpost-deploy-db-staging label

mentioned in commit 8ef9a8e2