Broken links on the Style Guide page

[savulchik]

The following links in the Services section are broken:

1. Create Unique Protos per Method
2. Don’t Include Primitive Types in a Top-level Request or Response Proto
3. Define Messages in Separate Files

I believe 1 and 2 should point to api.md and 3 to dos-donts.md

[marcindulak]

There is a more general problem with the documentation at https://protobuf.dev/, as shown by the existing, still open older issues

#198
#199
#206

Changes are made to the repository, but the outcome is not fully tested, and the existing issues not reviewed.

I'll tag the most recent committer @Logofile

[mjanczykowski]

What happened to the Best Practices links in the documentation? The pages were moved to another directory in this commit: c236fd6#diff-427836c1ebed9070e3b9891826e00c8e6696fe6179188facd2c7535f1ac9bb3d
and now can only be access from github: https://github.com/protocolbuffers/protocolbuffers.github.io/blob/main/eng/doc/devguide/proto/best-practices/dos-donts.md

[Logofile]

Thanks for raising this issue. I reorganized several topics into a subsection because the section has grown and will continue to grow as I capture more best practices into new topics. I apparently didn't update the metadata needed for the TOC to be updated with the move to the subdirectory. I'll work on this today.

[marcindulak]

Is the doc content md only?
If this is the case, would you accept adding a dead link checker of the internal md pages, as an additional github action workflow? Using https://github.com/UmbrellaDocs/linkspector or possibly the older https://github.com/tcort/markdown-link-check.
Checking for internet links will be probably too flaky.

[marcindulak]

https://github.com/UmbrellaDocs/linkspector does not support hugo markdown.

It appears that hugo does not support checking for dead links natively gohugoio/hugo#5080.
See medic/cht-docs#266 which uses https://github.com/raviqqe/muffet as a dead link checker.

[Logofile]

I took a pass through all of the docs to remove .md extensions to address #209. The same publish (later this week) will also be addressing this restructure bug. I plan to run a third-party link-checker on the rendered output after the publish to make sure links are all functional.

Thanks for the helpful suggestions!

[Logofile]

Oops, I meant to address #198, not #209. This issue is #209. 🫣