Describe our link strategy a bit.

1 files changed, 29 insertions, 4 deletions

diff --git a/spec/README.md b/spec/README.md
index 26c4bac..c248557 100644
--- a/spec/README.md
+++ b/spec/README.md
@@ -50,15 +50,38 @@ the URLs of their corresponding pages, so if you want to edit
 called [`spec/tor-spec-intro.md`].
 
 The chapter structure as a whole is defined in a special file called
-[`SUMMARY.md`].  Its format is pretty restrictive; see
-[the mdbook documentation](https://rust-lang.github.io/mdBook/format/summary.html)
-for more information.
+[`SUMMARY.md`].  Its format is pretty restrictive; see the [mdbook
+documentation] for more information.
 
 You can build the website locally to see how it renders.  To do this,
 just install mdbook and run the `./build_html.sh` script.  (You will
 need to have mdbook installed to do this.)
 
-> TODO: Add a note about trying not to break links.
+### Managing links
+
+We're in the early stages of this spec organization, but we should
+still be thinking about long term maintainability.
+
+Please think about how to keep links working in the long term.
+If you are going to add a link to a file, make sure that the file's
+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.)
+
+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 }`
+
+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.
+
+Finally, when you're looking for specific sections (e.g., to fix
+references that say "See section 5.2.3") you can look for the HTML
+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>`.
 
 ______________________________________________________________________
 
@@ -126,3 +149,5 @@ long-term permalinks.
 [`spec/tor-spec-intro.md`]: https://gitlab.torproject.org/tpo/core/torspec/-/blob/main/spec/tor-spec-intro.md?ref_type=heads
 [`spec` directory]: https://gitlab.torproject.org/tpo/core/torspec/-/tree/main/spec?ref_type=heads
 [`summary.md`]: https://gitlab.torproject.org/tpo/core/torspec/-/raw/main/spec/SUMMARY.md?ref_type=heads
+[heading ids]: https://github.com/raphlinus/pulldown-cmark/blob/master/specs/heading_attrs.txt
+[mdbook documentation]: https://rust-lang.github.io/mdBook/format/summary.html
\ No newline at end of file