Merge branch 'style' into 'main'

STYLE: Recommend span over a id=...

See merge request tpo/core/torspec!233

2 files changed, 42 insertions, 1 deletions

diff --git a/spec/STYLE.md b/spec/STYLE.md
index 74388c3..8111084 100644
--- a/spec/STYLE.md
+++ b/spec/STYLE.md
@@ -131,12 +131,16 @@ name is reasonable.  Before you rename a file, consider adding
 a redirect from the file's old name.  (See the mdbook documentation
 for more information about how.)
 
+<div id="mdbook-heading-anchors">
+
 If you want to link to a specific section within a file,
 make sure that the section has a defined anchor that makes sense.
 The syntax to define heading ids in mdbook looks like this:
 
 `## Heading with a long title that you want shorter name for { #shortname }`
 
+</div>
+
 If you need to change a heading, make sure that you keep its
 `id` the same as it was before, so that links will still work.
 
@@ -146,3 +150,40 @@ 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 `#`-prefixed link fragment,
+prefer `<span id="fragment">Text</span>`,
+to `<a id=...>Text</a>`.
+This works around mdbook mistakenly styling
+`<a>` without `href`
+as if it were a clickable link.
+
+(Of course it is often better to
+make the referenced text a section
+and
+[use the mdbook explicit anchor syntax](#mdbook-heading-anchors).)
+
+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="...">` and `</div>`
+(which must usually be placed as paragraphs of their own).
+
+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.
diff --git a/spec/rend-spec/revision-counter-mgt.md b/spec/rend-spec/revision-counter-mgt.md
index bc94416..a59c606 100644
--- a/spec/rend-spec/revision-counter-mgt.md
+++ b/spec/rend-spec/revision-counter-mgt.md
@@ -71,7 +71,7 @@ that can generate test vectors,
 see `src/test/ope_ref.py` in the
 Tor source repository.
 
-> <a id="use-case"></a>Note:
+> <h6 id="use-case">Note:</h6>
 >
 > Some onion service operators have historically relied upon
 > the behavior of this OPE scheme to provide