Questionnaire
The topic is complex and there are a lot of options. I have tried to condense the principles behind them into a set of questions. This is not intended as a deciding vote but for finding out the collective opinion.
If existing Commonmark constructs are used to generate target anchors in the output format, these are known as automatic anchors or implicit anchors. A new construct or convention would be needed for manual anchors or explicit anchors.
Automatic anchors
- All headings should become anchors automatically (using their textual content)
- Implicit anchors (e.g.
## Heading
) should automatically be available as reference link definition labels for overrides (e.g. [Heading]: {#ID}
)
-
Unused reference link definitions (
[label]:
) should become anchors automatically
-
All links should become anchors automatically (using their textual content)
-
Specific inline links (e.g.
[text](@)
or [text]()
) should become anchors automatically
-
All reference links (
[text][label]
) should become anchors automatically (using their label)
-
Specific reference links (e.g.
[text][#label]
or [][label]
) should become anchors automatically
- Other links should not become anchors automatically
Manual anchor restrictions
Manual anchors …
- may be restricted to headings
- may be restricted to defining terms (e.g.
<dfn>
in HTML output)
- may be restricted to blocks (i.e. headings, code blocks, quotations, …)
- may be restricted to headings and defining terms
- may be restricted to blocks and defining terms
- should be available in arbitrary locations
Manual anchor positions
Manual anchors …
- should always come before/above text (e.g.
## Heading {#ID} ##
)
- should always come after/below text (e.g.
## {#ID} Heading ##
)
- may come either before/above or after/below text
Manual anchors in headings …
- should come between text and affix
##
or underline ===
(e.g. ## Heading {#ID} ##
)
- should stay outside text and affix
##
or underline ===
(e.g. ## Heading ## {#ID}
)
Manual anchors in links …
- should be inside the text part (e.g.
[text {#ID}](target)
)
- should be inside the target or label part (e.g.
[text](target {#ID})
)
- should be outside current text and target or label parts (e.g.
[text](target){#ID}
)
Stylistic preferences
- Anchor ID should always be inside curly braces
{}
- Anchor ID should always be prefixed by a hash sign
#
- Manual anchors should always be on a separate line