Anchors in markdown

[nl0]

To have working anchor links in markdown we have, basically, two options: manual anchor insertion and automatic generation (based on the heading text).

Manual

Insertion

Just insert the anchor: ## Section 1 <a name="section1"></a>, -- it's simple and explicit, we just need to enable html in remarkable options.

Usage

To use these anchors, we simply reference them by given names: [Section 1](#section1).

Pros

• Simplicity and explicitness
• Maintenance: anchors don't change implicitly

Cons

• Extra manual markup
• Possible security issue: need to enable html support in markdown renderer

Implementation

• Enable html in remarkable options

Automatic

Generation

We can generate the anchors with the help of something like markdown-toc (see example implementation).
This will require render customization to expose the generated names.

Usage

The usage is essentially the same as with the first option, but since the names are implicit, we should make the anchors accessible in some way, like anchor icons shown when hovering headings on github.

Pros

• Automatic
• Stylish and professional (especially with anchor icons shown on hover)
• No need to enable html parsing

Cons

• Added complexity: requires custom rendering for headings and extra styling for anchors
• Maintenance: when heading text changes, anchor changes, so one must adjust the links accordingly

Implementation

• Configure renderer to generate and insert anchors
• Style the anchors appropriately

Caveats

Hash routing works out-of-the-box if the contents are already rendered (so navigating using TOC is ok), but doesn't work on the cold start (navigating directly to /page#section is not ok), so we need some (probably hacky) workaround (our existing one won't work, because it's react-specific, and markdown rendering is happening outside of react context). Server-side rendering will fix this.

Site-local links

Also, it makes sense to intercept link clicks inside markdown and use react-router's push if the link is local (relative, absolute without schema or if origin matches the current one) to avoid page reload.

[nl0]

added note about local links

[ResidentMario]

I believe you meant to file this issue for the quiltdata/t4 repository, not the quiltdata/quilt repository.

As of PR #270, we support HTML rendering in Markdown content in t4. The manual approach already works, and would be a no-op; we'd just tell users "hey, add an anchor below the section heading."

The thing is though, it's probably even more important that we have a feature for linking directly to a preview card on a package or file landing page. For example, we will eventually want to be able to link people (via https://t4-stage.quiltdata.com/b/quilt-example/packages/robnewman/us_county_smoking_vs_poverty/tree/1549673112/#us-county-smoking-2015.json or a similar URL) to the us-county-smoking-2015.json preview on the robnewman/us_county_smoking_vs_poverty package (this one).

And if we have that feature then we have a problem: now anchors for section titles in a Markdown render can collide with the names of previewed files.

For this reason I believe that for now we should just have users populate anchors the manual way.

One thing in your statement that I didn't quite understand:

but doesn't work on the cold start (navigating directly to /page#section is not ok)

[sir-sigurd]

@nl0
is this still relevant?

[nl0]

probably no, at least in its current form