Heading Anchor Links Fail

[wesleyboar]

Overview

Heading permalinks are broken.

Only happens on transcluded page content, but that is the content of pages when navigated how users should navigate them. See "Workaround".

[^1]: The heading link

[!WARNING] There are 381 instances of this across 30 files.

Steps

1. Open a page whose content comes from include-markdown. ^{(e.g. curating/policies.md via curating.md)}
2. Click on a heading that has an anchor link to itself (a manual permalink). ^{(e.g. curating/policies.md "Mission")}

Expected

3. The page scrolls to the heading and the URL is appended with its hash. ^{(e.g. page scrolls to "Mission", #mission is appended to URL)}

Actual

3. The page is "Not Found".

Workaround

Visit the page directly e.g. https://www.designsafe-ci.org/user-guide/curating/policies/#mission.

[wesleyboar]

Proposal

A. Remove All Manual Permalinks

[!NOTE] This can be done fast via regex.

Find: \[(.+?)\]\(#(.+?)\) \{ #(.+?) \} Replace: $1 { #$3 }

B. Replace Manual Permalinks with Automatic Permalinks

Enable automatic permalinks via toc extension.

For example, to enable permalinks in the (included) toc extension, use:

markdown_extensions:
  - toc:
      permalink: true

[!WARNING] Requires both —

• either release of TACC/TACC-Docs with permalink config
• or cloning its markdown_ext…s and adding permalink config

— and "A. Remove All Manual Permalinks"

[wesleyboar]

Proposal

B. Replace Manual Permalinks with Automatic Permalinks

To add this to TACC, see https://github.com/TACC/TACC-Docs/issues/36.

[wesleyboar]

Fixed by #60.