[chore] [editoral] switch to md front matter

[thompson-tomo]

Closes #1976

Progresses #1821

Changes

This switches to use github front matter syntax rather than embedding the front matter in comments. Currently these comments need to be processed before they can be used on the website version.

This change will also help in reviews as the link title etc are front and center.

By switching to front matter directly it enables turning on the first line h1 check.

Note the awk/sed command are necessary so that the document still passes the lint rules and we don't have a formatter to format it.

Question's:

• Do we need to keep # Hugo front matter used to generate the website version of this page? Or can it be removed? Has been removed due to TOC issues and needing to use grep/awk for formatting

Important

Pull requests acceptance are subject to the triage process as described in Issue and PR Triage Management.
PRs that do not follow the guidance above, may be automatically rejected and closed.

Merge requirement checklist

• CONTRIBUTING.md guidelines followed.
• Change log entry added, according to the guidelines in When to add a changelog entry.
  • If your PR does not need a change log, start the PR title with [chore]
• Links to the prototypes or existing instrumentations (when adding or changing conventions)

[thompson-tomo]

Build issue due to current toc generator having known issues with front matter syntax & isn't mantained. Will need to be addressed by switching to https://www.npmjs.com/package/doctoc

[thompson-tomo]

@chalin finally found a way to keep the build process happy. The one thing which i am not sure on is if the aliases in resource-and-entities.md are still valid. If not we could switch to a redirect

[chalin]

Nice! Thanks @thompson-tomo. I'll get back to you as soon as I can (it's a very busy EOM).

[thompson-tomo]

No worries, I will fix the formatting which is causing the build to fail very soon.

[Copilot]

Pull request overview

This PR migrates documentation front matter from HTML comment syntax (<!--- ... --->) to standard YAML front matter delimited by ---. This change enables better tooling support, makes front matter metadata visible during reviews, and allows enabling the first-line h1 markdown lint check. The migration affects over 140 markdown files across the documentation and 3 Jinja2 templates.

Key changes:

• Converts all front matter from HTML comments to YAML format (delimited by ---)
• Updates CONTRIBUTING.md documentation to reflect new front matter syntax
• Enables first-line-h1 markdownlint rule (previously disabled)
• Adds Makefile commands to ensure proper formatting after front matter closing delimiter

Reviewed changes

Copilot reviewed 161 out of 161 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
templates/registry/markdown/*.j2	Convert template front matter to YAML format
docs/**/*.md	Convert all documentation front matter from HTML comments to YAML
CONTRIBUTING.md	Update front matter documentation example
.markdownlint.yaml	Enable first-line-h1 check
Makefile	Add awk/sed commands to format documents after TOC generation

[trask]

By switching to front matter directly it enables turning on the first line h1 check.

Note the awk/sed command are necessary so that the document still passes the lint rules and we don't have a formatter to format it.

can these be done in a follow-up PR? if so, please revert those changes to keep this large mechanical PR easy to review

[chalin]

A first few questions and comments:

• Spec and semconv folks expressedly asked me to include the comment "Hugo front matter used to generate the website version of this page" so that all contributors know why the front matter is there (and hopefully realize that it's important to keep it up to date). Maybe this preference has changed. I'll let @open-telemetry/specs-maintainers @open-telemetry/specs-semconv-maintainers comment about this. I'm ok either way.
• Why not keep the (inline) array syntax for aliases?

[chalin]

The one thing which i am not sure on is if the aliases in resource-and-entities.md are still valid. If not we could switch to a redirect

Yes the alias is valid, but I'd rather keep the inline array syntax, esp. in these cases that have a single entry.

[chalin]

FYI, I haven't had the time to look into this more, but in support of #1821 and open-telemetry/opentelemetry.io#6101. We probably will need to have a title field in the front matter too.

I'm wrapping up and will be OOO so I won't be able to get back to this until the new year (FYI).

[thompson-tomo]

Spec and semconv folks expressedly asked me to include the comment "Hugo front matter used to generate the website version of this page" so that all contributors know why the front matter is there (and hopefully realize that it's important to keep it up to date). Maybe this preference has changed. I'll let @open-telemetry/specs-maintainers @open-telemetry/specs-semconv-maintainers comment about this. I'm ok either way.

The issue I ran into was that this causing issues with the toc plugin. If necessary I can look to put it back and hope the current awk/sed commands keep it happy or possibly extend it.

Why not keep the (inline) array syntax for aliases?

This is being caused by the necessity to process the docs with awk/sed after toc generation to keep linting happy. I would've preferred to keep them unchanged as well.

We probably will need to have a title field in the front matter too.

Yeap am aware and that would be tackled by seperate PR.

[chalin]

Build issue due to current toc generator having known issues with front matter syntax & isn't mantained. Will need to be addressed by switching to https://www.npmjs.com/package/doctoc

OMG, the last update was 8 years ago in NPM. doctoc seems like an interesting choice; https://npm-compare.com/doctoc,markdown-toc

Maybe it would be worth switching toc tools before working further on this PR?

/cc @vitorvasc

[thompson-tomo]

I certainly am open to switching tools. If I remember correctly there was issues using do toc. What I found was:

• Skip h1 from being included in toc thlorenz/doctoc#278
• Increased compatability when front matter is used thlorenz/doctoc#279

So doctoc would only work if we removed comments from front matter then & also remove the h1.

Note doc toc also has not had a release in years.

[chalin]

Hmm. Ok, maybe another tool then.
(Creating a markdownlint rule to handle tocs might be a fun project ;))

[thompson-tomo]

Let's see if I can a feature into doctoc to ignore level 1 headings as i wasn't having much luck finding an alternative.

[chalin]

Btw, if you still need to massage the files, rathr than awk & sed, I'd suggest using Perl because it is more portable across OSs and container environments in my experience (esp. if you avoid Perl modules that don't ship with Perl).