STYLE: Recommend span over a id=...

And discuss some of the rather bizarre mdbook behaviours which lead to
this recommendation.

I already used <span> this way extensively in ssh-protocols.md.

1 files changed, 35 insertions, 0 deletions

diff --git a/spec/STYLE.md b/spec/STYLE.md
index 74388c3..b5efa61 100644
--- a/spec/STYLE.md
+++ b/spec/STYLE.md
@@ -146,3 +146,38 @@ anchors that our conversion process added.  For example,
 if you want to find `dir-spec.txt` section 2.1.3, look for
 the anchor that says `<a id="dir-spec.txt-2.1.3"></a>`.
 
+## Specific Markdown syntax
+
+### Define link fragment targets with `<span id="...">` (usually)
+
+To manually make an target for a `#` link fragment,
+prefer `<span id="fragment">Text</span>`,
+to `<a id=...>`.
+This works around mdbook mistakenly styling
+`<a>` without `href`
+as if it were a clickable link.
+
+You may need to make sure you have some other text
+on the same line as the `<span>`
+to avoid mdbook thinking you were writing
+a whole paragraph of raw HTML.
+
+Sometimes you may wish to use `<div id="...">`.
+Or, even, `<h6 id="fragment">Some heading</h6>`
+(which won't appear in the table of contents,
+but will generate the reference arrow mark when
+the user clicks on a link with that target).
+
+Example:
+```
+<span id="lemons-lemonade">LEMONS
+are a sour fruit, sometimes used for making
+lemonade</span>
+
+(later)
+
+Various fruit may be found, including [lemons](#lemons-lemonade).
+```
+
+It is OK to use an *empty* `a` element: `<a id=....></a>`.
+Many existing section anchors are done this way.