[editorial] Inline Hugo front matter

open-telemetry / opentelemetry-specification

Specifications for OpenTelemetry

https://opentelemetry.io

Apache License 2.0

3.64k stars 870 forks source link

[editorial] Inline Hugo front matter #4046

Open chalin opened 1 month ago

chalin commented 1 month ago

Fixes #4029
Replacement solution for #4021
Notes & questions:
- I kept "Hugo front matter used to generate the website version of this page" as a YAML comment. Shall I drop those lines now that it's official Markdown front matter?
- Because markdownlint actually recognizes front-matter titles, I've disabled that feature so that it doesn't report an error (due to the title also appearing in the page)

/cc @reyang @carlosalberto @svrnm

chalin commented 1 month ago

I'm looking into the markdown-toc GH action failure.

chalin commented 1 month ago

Hmm, the markdown-toc tool seems to be cleaning up more than just the TOC. It strips the comment from the front matter and removes any blank lines between the title and the front matter 🤷🏼‍♂️. I'll commit the change so that you can see.

Yes, I confirm that it's a known issue:

https://github.com/jonschlinkert/markdown-toc/issues/151

chalin commented 1 month ago

So strange, markdown-toc is also adding blank lines at the end of files!

chalin commented 1 month ago

Ok, well ... due to unresolved bugs in markdown-toc, we can't inline Hugo front matter 🤷🏼‍♂️ Ref.: https://github.com/jonschlinkert/markdown-toc/issues/151#issuecomment-2105313699.

chalin commented 1 month ago

I've removed the commits that contained the markdown-toc mangled content. So there should be only one GH action failure, the markdown-toc check.

So, it seems that this can't be merged until markdown-toc is fixed. :-/

chalin commented 1 month ago

I could modify the markdown-toc make rule to temporarily comment out the front matter, but I'm not sure that it's worth it. WDYT @reyang et all?

jsuereth commented 1 month ago

Approved pending TOC fix.

chalin commented 1 month ago

Ok, I'll tackle on the markdown-toc workaround as soon as I can.

github-actions[bot] commented 1 month ago

This PR was marked stale due to lack of activity. It will be closed in 7 days.

chalin commented 1 month ago

Nope, not stale, I was OOO.

chalin commented 3 weeks ago

Heads up that I'm really swamped atm, so I'm unsure when I'll be able to get to this.

github-actions[bot] commented 2 weeks ago

This PR was marked stale due to lack of activity. It will be closed in 7 days.

chalin commented 2 weeks ago

This is still relevant and I'll get to it as soon as I can.

chalin commented 2 weeks ago

Just curious if you've considered use of https://www.npmjs.com/package/doctoc instead? I'll investigate this as a possible less buggy alternative, and/or propose a workaround.

github-actions[bot] commented 1 week ago

This PR was marked stale due to lack of activity. It will be closed in 7 days.

chalin commented 2 days ago

Still valid. Will get to it eventually 😄.