[chore] [editoral] switch to md frontmatter

[thompson-tomo]

Progresses #1821

Changes

This switches the manual docs 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.

The docs now have an explicit title front matter property which should match h1.

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 based on feedback

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 when you get a change could you circle back and review this. Note I have split the auto generated docs out into #3671. This should make it easier to review as the pages are auto-generated by the templates.

[github-actions]

This PR has been labeled as stale due to lack of activity. It will be automatically closed if there is no further activity over the next 7 days.

[thompson-tomo]

@open-telemetry/specs-semconv-maintainers can we re-open as we await @chalin or someone else to review. Key thing is this is needed to improve website publishing process & is a pre-requiste for introducing specs.opentelemetry.io.

[chalin]

@thompson-tomo - can you ensure that this is up to date, and I'll start final tests on the otel.io side to ensure that this can land smoothly.

[chalin]

@thompson-tomo - FYI, I'll be making some progress on this this month. See inline comments for a tweak and question.

Btw, what's in place to ensure that the Hugo fm title and page title match. I thought that we had a checker in place, but I'm not seeing that in the scope of this PR.

[chalin]

As clarified via #3843 (comment), there should be no linkTitle entry when it matches the title. This applies to many changes in this commit.

[thompson-tomo]

My mistake. Have reverted that.

[thompson-tomo]

I have just updated the branch and completed an audit so it is up to date. Note #3671 will update the files under the registry directory as they are 100% auto generated.

So currently there is nothing in place to keep them in sync. I did previously have a custom textlint rule in-place.

Note I already have a pr open to perform the textlint corrections for casing etc #3747 & a draft pr to enforce textlint in ci. #3578.

[chalin]

I have just updated the branch and completed an audit so it is up to date.

How did you "complete the audit"? Do you have a script? Is it a part of this repo already?

So currently there is nothing in place to keep them in sync ...

I'm ok landing this earlier and brining in the sync check later.

... I did previously have a custom textlint rule in-place.

Right, that rings a bell. Where is that work? Is textlint already a part of this repo's toolchain? I vaguely recall commenting on this (in this repo or the main spec repo?); possibly even mentioning that I'd more likely favor use of markdownlint instead. (Nm, found the context) In any case, we can land the changes first so that this PR isn't delayed.

[thompson-tomo]

How did you "complete the audit"? Do you have a script? Is it a part of this repo already?

I manually went through checking that each page under docs except the registry section. had both a title & linkTitle. The titles were previously all set via a script which I doubt I have anymore. Link titles were mostly already there.

[joaopgrassi]

Before even reviewing this, I'd like us to have a mechanism to:

1. Check that each page has the frontmatter
2. That it matches the header

Without it this will become stale, so I think it needs to be done together and not as a follow up.

[thompson-tomo]

@joaopgrassi based on your request for linting of content to ensure that frontmatter is present & matches h1. Can you review #3578 which adds textlint (used in otel.io & spec) to do the linting and then in this pr we would configure the additional linting rules/plugins.

[thompson-tomo]

@chalin i have committed the textlint rules to https://github.com/wemicroit/textlint-rules and hope to have 1 if not both published within the next few days. By publishing it we can use the same rule in the other spec repos.

[thompson-tomo]

@chalin the scenarios of linkTitle being the same as title has been addressed.

Note #3671 should be a quick pr to review as those markdown files are all system generated from 1 of 4 templates.

[opentelemetry-pr-dashboard]

Pull request dashboard status

Status last refreshed: 2026-07-25 20:56:27 UTC.

• Waiting on: Reviewers
• Next step: Review the latest changes.

This automated status or its linked feedback items may be incorrect. If something looks wrong, please report it with the result you expected.