Resolve content-related warnings (kramdown, markdown warnings, path conflicts)

All content changes required for Hugo that are common, supported patterns are part of the scripted migration, but there are a few one-offs that we need to fix by hand. We can remove/refactor these at any time before we launch the new site.

This includes certain Kramdown tags, unexpected YAML front matter data, unexpected content within certain shortcodes, and paths that will conflict when the site is generated with Hugo.

How to fix

Warning: Disclaimer alert(s) found with invalid inner content

• Fix: Edit the source page(s) and replace the DISCLAIMER alert type with INFO, or WARN if that makes more sense.
• Why: The DISCLAIMER alert type should only be used with specific text we've had reviewed by the Legal team. Other alerts should use the other styles of alert boxes.

`Error processing file whatever.md: [WARN] No valid YAML front matter found

• Fix: Add our normal front matter (https://docs.gitlab.com/ee/development/documentation/metadata.html).
• Why: All pages should have this. We need it to exist in order to update it programmatically.

Kramdown: options tags

• Fix: These tags indicate that the page includes HTML within the markdown file, and the file includes a kramdown tag like this: {::options parse_block_html="true" /}. Check the file(s) for raw HTML. If none exists, we can just remove the kramdown tag. If there is necessary HTML (e.g, the deprecations page), we will need to see if it can be refactored to not use that HTML, and if not, we need to make sure it works on the Hugo site (and if it doesn't, we need a new issue to investigate more; the deprecations page already has its own issue in the Hugo project).
• Why: Hugo does not require special tags to use HTML, but generally, it is not recommended to hand-code HTML within docs content at all (it's hard to edit, maintain, troubleshoot, test, etc). The tags need to be dropped regardless, and HTML should be evaluated to see if we can replace it with something more supported.

Kramdown: attribute tags

• Fix: These tags indicate the page is providing a custom CSS class for something, and the file includes a Kramdown tag like this: {: .alert .alert-warning} (this one adds those classes to the element above it). We should remove these tags. This example should use an alert box rather than custom CSS classes; most others likely have no effect at all.
• Why: Hugo won't process these with our current configuration. This is intentional. Authors should not need to add CSS classes to content. If content needs a specific visual style, we should use shortcodes instead.

Kramdown: nomarkdown tags

• Fix: These were used in a few blueprint pages in order to create lists within tables. This is not supported in Kramdown/Nanoc, but these work fine without these tags in Hugo.

Duplicate paths

• We can detect these with hugo --printPathWarnings. For example:

  • https://docs.gitlab.com/ee/administration/analytics.html
  • https://docs.gitlab.com/ee/administration/analytics/

  Hugo renders the above two pages at the same path, meaning one gets overwritten.

• Fix: Work with writers assigned to these pages to rename or move conflicting pages.

Newlines in history blocks

• Fix: Adjust content so that each list item is on a single line.
• Why: These don't migrate cleanly (see https://gitlab.com/gitlab-org/technical-writing-group/gitlab-docs-hugo/-/merge_requests/176#note_2077960591).