STYLE: Recommend # {#anchor} over <... id="...">

1 files changed, 9 insertions, 4 deletions

diff --git a/spec/STYLE.md b/spec/STYLE.md
index 0596e3d..cd0786e 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.
 
@@ -157,16 +161,17 @@ 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="...">`.
-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:
 ```