Difficult to Use Markdown on Hazmapper Page

[wesleyboar]

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 use cases: broke down into separate files and fixed some headers that… #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.