Draft: refactor: edit links for markdown document navigation

[timothystone-knsl]

Improve navigation of the document with markdown compatible header anchor fragments. Markdown parsers "kebab-case" headers for navigation.

While some internal navigation support of named anchors remain, e.g., <a name="fooBar" ></a>, Markdown parsers generally auto-expand heading elements, e.g., h1, h2 in kebab-case. As such the "in GitHub navigation" doesn't work very well. This PR

refactor: update tables to improve markdown compatibility

Markdown parsers have varied table support. The use of "open-ended boundaries" over "pipe-ended boundaries" can lead to issues with visual rendering of tables. IDE support for tables is better supported as well, though visually, header rows are not attractive in the source code, IDEs manage this formatting very effectively.

chore: add macOS Desktop Services file to Git exclusions

Update .gitignore with the macOS .DS_Store file.

[timothystone-knsl]

Caught up on some of the discussions in some earlier issues. It's a) not clear how these are generated and b) there is not an appetite to update "published specs" (even for internal HTML navigation issues). This position, as an outsider, seems odd. I mean the spec isn't changing, the markdown is and then in support of Markdown parsers.

[MikeRalphson]

Caught up on some of the discussions in some earlier issues. It's a) not clear how these are generated and b) there is not an appetite to update "published specs" (even for internal HTML navigation issues). This position, as an outsider, seems odd. I mean the spec isn't changing, the markdown is and then in support of Markdown parsers.

Our preference is to stick to our stated policy of not amending published specifications, for any reason. This is in line with things like IETF practices.

My personal feeling is, @github should not have broken backwards compatiblity which users (such as ourselves) were depending upon. There is a relatively simple fix for them to restore our broken functionality.

[handrews]

@MikeRalphson earlier this year the TSC specifically approved fixing the links in place. We discussed it in March (#3183 (comment)) and while I cannot find a record of the decision, there is a reference to the fact that we made a decision to do this but were waiting on @webron to decide the logistics in April (#3253 (comment)).

I'm rather frustrated that it's a good six months later, with the number of PRs that various people have opened on this approaching double-digits (some are also closed), and we still haven't managed to do this very simple thing.

I know that one issue was that we asked folks to update PRs but it's been too long and they'd moved on. Therefore I will consolidate the PRs and cite the TSC meeting notes and push this through to one resolution or another.

But we definitely decided to do this. I recall it very distinctly.