Document xref and markdown quirks with new tools

[StackScribe]

Summary

The new tools have some "quirks" for xref links. These should be documented to help new users. These are listed in a comment to #2584 but can be handled in a separate PR.

DoD

• Create "Coding the docs" page in contribute/docs section
• Add that page to mkdocs.yml
• Provide links to the Markdown documentation
• Explain the comments: true block in the CRD ref pages
• Page title displayed in the main canvas is coded as an H1 (#) line. Note that the the title displayed in the left frame is determined by the appropriate line in the mkdocs.yml file. If you modify the page title, you must modify both locations.
  • The new title does not show in the left frame of your local build until you stop and restart the previewer.

Indentation for nested lists and code blocks

• Paragraphs and code blocks that are nested under a list item must be indented two spaces from the text of the list text. If they are not, the indented material is rendered as flush-left and ordered lists do not increment the list item number properly

External links and internal cross-references:

• Links to external pages use the target displayed URL as displayed, including the trailing /. This is required for:
  • Links to outside web pages
  • Links to files in the same repository that are outside the documentation NAV path
  • Links from files outside the documentation NAV path (such as README.md and CONTRIBUTING.md files) to files inside the documentation NAV path
    • Links using a relative path resolve correctly but the target documentation page does not include the contents in the left frame

Cross-references to "internal" pages (which is the documentation NAV path as defined in the mkdocs.yml file, which is also the path relative to the docs directory. displayed in the URL

• Use a relative path to link from a source file in the docs/docs directory (which is the documentation NAV path) to any other source file in that. source tree.
• URL formats for links do not match what is displayed in the browser
  • The path must include the full name of the targeted file, including the .md extension
  • If the target file is index.md or _index.md, you must specify that.
  • To cross-reference a subsection of a page, remove / from before the # that appears in the URL after the page tag

• Comments in the markdown source are delimited by the <!-- string at the beginning of the line

[mowies]

The team agreed to split this ticket into content for the contribution guide and rules for our linters (+ fixing the current docs accordingly)

[StackScribe]

Add the need to put <!-- markdownlint-disable MD007 --> at the top of the "Field" section for each CRD ref page so that markdownlint-fix doesn't screw up the indentation

Follow-up: This is no longer required since we fixed markdownlint