Difficult to Use Markdown on Hazmapper Page

Overview

Using Markdown on the Hazmapper doc (code, page) reveals obstacles.

Details

Obstacles

1. Internal anchor links should go to id-tagged elements.

   Not blank anchors like <a id="whatever"></a>, but instead use:

   • images: ![...](...){\#whatever ... }
   • headings: #### Whatever { #whatever }
     • problem: Some anchors are for text that should be a heading but can not be (e.g. "Non-linked mapillary assets", "Linked mapillary assets"). reason: The heading depth limit is reached (i.e. no ####### / <h7>). solution: Raise all the files heading levels up one. problem: Headings are at the correct level for being included onto /…/tools/visualization/ page. reason: The /…/tools/visualization/ page heading starts at #, so child pages start at ##. solutions: Proposal 1 or Proposal 2.
   • new links within text: [whatever](#whatever){ #whatever }
2. HTML should be markdown.

   • problem: Anchor links via markdown fail on /…/tools/visualization/ (but succeed on /…/tools/visualization/hazmapper/). reason: The include-markdown plugin outputs visualization#whatever instead of #whatever. solution: Do not use include-markdown. problem: The include plugin would cause other issues. reason: All MkDocs includes solutions have some drawback. solutions: Proposal 2 or Proposal 3.

Proposals

1. Allow Would-Be Headings to be Headings

   (e.g. "Non-linked mapillary assets", "Linked mapillary assets")

   1. Remove a # on each heading to reduce heading depth of Hazmapper doc.
   2. Only on Visualization doc, increase heading depth of Hazmapper content.
      • Use the heading-offest option when including Hazmapper doc.
2. Link to Hazmapper Doc, Not "include" Them

   1. Change the include-markdown syntax in visualization.md to be (Markdown) links.
      • Link to Hazmapper sibling docs too (for consistent UX).
   2. Restore sidebar navigation for Visualization docs (that will be lost by step 1):
      • Update MkDocs to explicitly list all docs to show under Visualization (as was done for Use Cases in PR #63).
3. Use Plugin Option to Fix Anchors That Break on Include

   Use the rewrite-relative-urls option when including Hazmapper doc.

Background

Noticed during WG-397.

Start with user-guide/docs/tools/visualization/hazmapper.md and user-guide/docs/tools/visualization.md, then inspect the MkDocs configuration and the include-markdown plugin options referenced in the issue. Build the documentation and check the Visualization page, heading structure, internal anchors, links, and sidebar navigation. Done means the selected proposal works without broken links or unintended navigation changes.