From a331e9f48790ad4beaba1ee443c5ad8b13d3afb4 Mon Sep 17 00:00:00 2001 From: Nick Mathewson Date: Sat, 14 Oct 2023 18:52:10 -0400 Subject: Describe our link strategy a bit. --- spec/README.md | 33 +++++++++++++++++++++++++++++---- 1 file 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 ``. ______________________________________________________________________ @@ -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 -- cgit v1.2.3-54-g00ecf