[editorial] Fix doc page titles and add Hugo front matter

[chalin]

• Closes Consistent page title form and capitalization #169
• Closes [editorial] docs/rpc/json-rpc: fix title and in-page hypenation #170 because it supersedes it (either, really, can be merged first)
• Adds the necessary Hugo front matter to be able to publish pages on the OTel website

/cc @svrnm @cartermp @jsuereth @joaopgrassi

[jsuereth]

Thanks for doing all this work!

I have a meta-question related to how we keep this hugo matter up to date, given the pace at which we've been adding docs.

TL;DR; we either need a guide on how/what to fill out and when or for some of this can we move it into the docs adjust-pages.pl script?

[chalin]

@jsuereth - you make good points about some of the front matter. To answer your questions:

• One of my goals is to eliminate the adjust-pages.pl script, and replace it by a very simple and generic Gulp task that only activates the front matter and little else.
• I agree that embedding the path_base_for_github_subdir isn't ideal. Yes, that could be handled by the Gulp task.

Would it be ok for this PR to land, and we address your concerns (regarding path_base_for_github_subdir etc) iteratively?

[chalin]

I've rebased and re-normalized the new and updated doc pages.

[jsuereth]

@chalin

Would it be ok for this PR to land, and we address your concerns (regarding path_base_for_github_subdir etc) iteratively?

Yes, depending on the answer to this question:

If we add new markdown files that do NOT include appropriate hugo frontmatter/github redirect, does it fundamentally break the website?

If the answer is YES, I think we should add a CONTRIBUTING.md section requiring hugo front matter of linkTitle.

[chalin]

@jsuereth - no, not having front matter for new files will not break the website build, and the page will get published. The linkTitle field is mainly to define a shorter title name that gets used in the left-side nav and breadcrumbs -- so it's a "nice to have". For example, with the link titles added by this PR, the left sidenav now looks like the same as the list of pages shown in the docs landing page. It's nice to have that correspondence.

[jsuereth]

Great! Thanks for all the fixes, this looks good to go.