Move Managing Links subsection into style guide

1 files changed, 27 insertions, 0 deletions

diff --git a/spec/STYLE.md b/spec/STYLE.md
index d14f7f1..ffc806d 100644
--- a/spec/STYLE.md
+++ b/spec/STYLE.md
@@ -92,3 +92,30 @@ Neither of these is really great.  We should find something better.
 > normative text, it is a good idea to put it in quoted text, like
 > this.
 
+
+## 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>`.
+