Publish specs at specs.opentelemetry.io, an exploratory proposal

[chalin]

This issue is an exploratory proposal to publish the main OTel and semantic convention specs from a dedicated specs site, such as https://specs.opentelemetry.io.

Why:

• Simplify and speed up the main opentelemetry.io build
• Make it clearer that specs are not currently an i18n target of the main site.
• Let spec maintainers publish without depending on the main site build; they would only need to ensure that the specs site builds correctly.
• Support cleaner, more self-contained Markdown for agent-friendly docs.
• Give OTel specs and semantic conventions focused navigation while keeping a unified OTel look.

Initial idea:

• Keep existing opentelemetry.io/docs/specs/ pages as redirects or link-outs.
• Publish OTel and semantic convention specs from simpler Hugo + Docsy builds.
• Use top-level paths such as specs.opentelemetry.io/otel/ and specs.opentelemetry.io/semconv/ for differentiation. An alternative is separate subdomains, but that may be overkill and could complicate UX.

Open questions:

• Ownership and publishing responsibilities. Initially, the Comms SIG could be custodians.
• Exact URL structure.
• Unified styling and navigation expectations.
• Impact on Ask AI / docs AI features.

Suggested next steps:

• Gather feedback from spec maintainers and other stakeholders.
• Once there is general consensus, build a small proof of concept to validate the approach before fully committing.

/cc @open-telemetry/docs-maintainers @open-telemetry/specs-semconv-maintainers

Related:

• [chore] [editoral] switch to md frontmatter semantic-conventions#2971

[jsuereth]

I like this a lot!

[thompson-tomo]

I like and would add to the list of open questions is how can we support versioning of specs.

I also would add opamp, declarative config & telemetry schema to the list of specs.

[svrnm]

I think this is a great idea, how can we make progress on that, what would we need to do next, @chalin ?

[thompson-tomo]

Perhaps @chalin can confirm but i believe we would need to transition the markdown files to frontmatter so that we dont need to post-process them.

For which i have:

• [chore] [editoral] switch to md frontmatter semantic-conventions#2971 / [chore] [editorial] Switch registry docs to pre-processed frontmatter semantic-conventions#3671
• chore: Switch to doctoc #5153 the frontmatter switched is blocked until that is merged.

[chalin]

Regarding spec versions: I think that we'd need stats to determine whether it's justified to support version beyond what I consider the low hanging fruit of redirecting to the repo for older versions of the spec, since the spec is designed to be readable from the repo. Other additions make sense. I will get to the front-matter PRs as soon as I have the time: they're part of the spec-support overhaul.

[svrnm]

@chalin can you take a fresh look here and let us know if you are still open to raise the PR for it?