[CI] Check links in README etc

[chalin]

Originally posted by @theletterf in https://github.com/open-telemetry/opentelemetry.io/issues/3914#issuecomment-1919599282

Wouldn't test-and-fix from the CLI also perform that check?

"That check" is:

$ npm run _check:links--md

I see a few options:

• [ ] Add _check:links--md to test-and-fix as @theletterf suggested. Pros: quick to add Cons: relies on devs running test-and-fix in order to catch issues.
• [ ] Adapt our NPM scripts so that _check:links--md also gets run during CI. Pros: quick to add Cons: slows down CI more than I think is worth it.
• [ ] Publish all top-level *.md files to the website under, say, /site somewhere and use our existing & blazing fast htmtest-based link checking to check links Pros: seemless and uniform checking of *.md file links along with other site pages Cons: will take a bit more time to setup.

@svrnm @theletterf - WDYT?

[svrnm]

I have no strong preference, we are not changing those pages that often, but I lean towards (3)

[theletterf]

I like 3, too. Cleaner, and would be a nice way of kickstarting /site.

Would that include the README, too, though? Or we'd still treat that one as an exception?

[chalin]

I prefer (3) as well. Yes, I'd include the README, even if that might seem a bit strange -- I guess that it'll depend on where we place the files. E.g., it could just be under /site/repo where the index page for that section mentions that the section is just a convenient place to publish the repo's top-level markdown files.

[theletterf]

From https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-readmes:

If you put your README file in your repository's hidden .github, root, or docs directory, GitHub will recognize and automatically surface your README to repository visitors. If a repository contains more than one README file, then the file shown is chosen from locations in the following order: the .github directory, then the repository's root directory, and finally the docs directory.

By moving the README, we leave the repo blank when entering it. Could we have a text only README with no links perhaps?

[svrnm]

From docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-readmes:

If you put your README file in your repository's hidden .github, root, or docs directory, GitHub will recognize and automatically surface your README to repository visitors. If a repository contains more than one README file, then the file shown is chosen from locations in the following order: the .github directory, then the repository's root directory, and finally the docs directory.

By moving the README, we leave the repo blank when entering it. Could we have a text only README with no links perhaps?

We are not moving the README, hugo has tooling for that.

[cartermp]

Hrm, publishing the README to the site feels kind of odd, but where would it go?

[theletterf]

Will we end up moving the README?

[chalin]

We're not moving the README, we'd only be using Hugo features to ensure that it gets processed during the site build. Like Severin, my preference is for option (3), but I won't have time to work on this for a while (it isn't a pressing matter -- again as Severin pointed out, we don't change those files often). Can we just keep this open for now?