sanctuary-js / sanctuary

:see_no_evil: Refuge from unsafe JavaScript
https://sanctuary.js.org
MIT License
3.03k stars 94 forks source link

documentation: prefix heading identifiers to avoid collisions #663

Closed davidchambers closed 4 years ago

davidchambers commented 4 years ago

Commit message:

Identifiers are automatically generated for both headings and functions. Currently these can collide. It is currently impossible to link directly to S.array because it has the same fragment identifier as the ‘Array’ section in which it resides.

This commit adds a script to be run during readme generation, which wraps the text of each heading in <span id="section:...">❑ ...</span>. GitHub's algorithm converts the LOWER RIGHT SHADOWED WHITE SQUARE to a hyphen, which prevents GitHub's heading identifiers from colliding with function identifiers (control characters are rendered as �, and GitHub's algorithm ignores space characters, so a visible character is required).

Before:

### Array

After:

### <span id="section:array">❑ Array</span>

The heading above will have two fragment identifiers, #section:array and #-array (assigned by GitHub), neither of which collides with #array, the fragment identifier for S.array.