docs: Use relative links to site pages

[blake]

What type of PR is this?
/kind documentation

Background:

Currently when running mkdocs build or mkdocs serve, a flood of informational – and some warnings – are logged to the CLI. For example,

INFO    -  Doc file 'index.md' contains an absolute link '/concepts/roles-and-personas', it was left as is. Did you mean 'concepts/roles-and-personas.md'?
WARNING -  Doc file 'geps/gep-1323/index.md' contains a link '../reference/policy-attachment.md', but the target 'geps/reference/policy-attachment.md' is not found among documentation files.
INFO    -  Doc file 'geps/gep-1619/index.md' contains a link '#BackendLBPolicy-api', but there is no such anchor on this page.

This is because MkDocs recommends that relative paths be used when linking to pages instead of absolute URLs. Linking to relative paths allows MkDocs to identify and warn about broken links to non-existent pages and headings when it is building the site. MkDocs even has this warning about using absolute URLs.

Warning

Using absolute paths with links is not officially supported. Relative paths are adjusted by MkDocs to ensure they are always relative to the page. Absolute paths are not modified at all. This means that your links using absolute paths might work fine in your local environment but they might break once you deploy them to your production server.

A number of PRs have recently been submitted to this project to resolve several broken links or issues where links were not being properly rendered.

• Update httproute.md to add link for v1.SectionName #3485
• docs: fix broken gep status link #3626
• fix(docs): grpcroute name is not set #3639
• docs: Fix broken links on site #3655

Theoretically these issues could've been identified earlier if MkDocs's validation rules were configured to warn upon finding broken links, and strict was enabled.

What this PR does / why we need it:

This commit modifies the documentation to use relative links between pages on the site instead of absolute URLs in order to quell the messages in the logs, and set up the site for potentially using strict mode in the future.

This is a large PR with changes across many files. In order to ensure that the all links were correctly updated and nothing was fat fingered, I wrote a small GNU Awk (gawk) script to assist with modifying the Markdown files. https://gist.github.com/blake/78b166792cd262b6897b784a2dedccfa.

The changes were validated by comparing HTML output of the site when generated from the main branch to the output generated after the Markdown files had been modified by the aforementioned script. For example:

$ mkdocs build --site-dir site
<lots of output>
…

$ find geps/ site-src/ -name '*.md' -prune -not -path "site-src/geps/*" -type f -exec gawk -f modify-urls.awk -i inplace {} \;
<some warnings about non-existent files>

# Output the site into a different directory so that it can be
# compared to the site output prior these changes
$ mkdocs build --site-dir site2
<lots of output>
...

$ diff --recursive -u site site2

The diff is rather large, but much like the diff for this PR, it primarily consists of the generated URLs changing from absolute to relative.

Its important to note that this PR is strictly focused on rewriting internal URLs to align with the format recommended by MkDocs so that broken links and anchors can be easily detected. It is not intended to fix all of the existing broken URLs or broken anchors. Those will be addressed in a subsequent PR.

Which issue(s) this PR fixes:

Does this PR introduce a user-facing change?:

NONE

[k8s-ci-robot]

Hi @blake. Thanks for your PR.

I'm waiting for a kubernetes-sigs member to verify that this patch is reasonable to test. If it is, they should reply with /ok-to-test on its own line. Until that is done, I will not automatically test new commits in this PR, but the usual testing commands by org members will still work. Regular contributors should join the org to skip this step.

Once the patch is verified, the new status will be reflected by the ok-to-test label.

I understand the commands that are listed here.

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes-sigs/prow repository.

[robscott]

This is awesome, thanks for the work on this! Very cool to see the script behind this.

/ok-to-test
/lgtm
/approve

[k8s-ci-robot]

[APPROVALNOTIFIER] This PR is APPROVED

This pull-request has been approved by: blake, robscott

The full list of commands accepted by this bot can be found here.

The pull request process is described here

Needs approval from an approver in each of these files:

• geps/OWNERS [robscott]
• site-src/OWNERS [robscott]

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

[robscott]

No meaningful changes to GEPs, just fixing links. Removing the auto-hold.

/hold cancel