DOC-8540: Update Style Guide to reflect new linking strategies (#17643)

StyleGuide.md

@@ -64,6 +64,11 @@ Included in this guide:
     - [Italics](#italics)
     - [Underline](#underline)
   - [Links](#links)
+    - [Link capitalization](#link-capitalization)
+    - [Links to CockroachDB docs pages in the same folder](#links-to-cockroachdb-docs-pages-in-the-same-folder)
+    - [Links to CockroachDB docs pages outside of the current folder](#links-to-cockroachdb-docs-pages-outside-of-the-current-folder)
+    - [Links to a specific location on a page that is not a heading](#links-to-a-specific-location-on-a-page-that-is-not-a-heading)
+    - [Localized external links](#localized-external-links)
     - [GitHub issues and pull requests](#github-issues-and-pull-requests)
   - [Tips, notes, and warnings](#tips-notes-and-warnings)
     - [Tips](#tips)
@@ -535,52 +540,76 @@ Do not use underlined text in CockroachDB docs. If it seems beneficial to emphas
 
 Whenever a CockroachDB feature is referenced, provide a link to the relevant documentation. You can also provide links to external resources, but only if the resource is confirmed to be accurate by a technical reviewer or the author is a Cockroach Labs SME and no CockroachDB documentation covers the topic.
 
+Links are marked with inline text surrounded by square brackets followed by the link address in parentheses.
+
 Avoid using non-descriptive link names such as `here`, `this page`, or `go`.
 
-Use Markdown reference-style links when several parts of the same page refer to the same target URL (e.g., [Release Notes](releases/v22.1.html)).
+Use Markdown reference-style links when several parts of the same page refer to the same target URL. Reference-style links contain two sets of square brackets. The first set of brackets contains the link text that will appear on the final rendered page. The second set of brackets contains the reference name.
 
-For websites that automatically localize pages, avoid using localization elements directly within the URL. For example:
+**Example:**
 
-- GitHub
-  - Instead of `https://docs.github.com/**en/**graphql/overview/explorer`
-  - Use `https://docs.github.com/graphql/overview/explorer`
-- Wikipedia
-  - Instead of `https://en.wikipedia.org/wiki/SQL:2011`
-  - Use `https://www.wikipedia.org/wiki/SQL:2011` or `https://wikipedia.org/wiki/SQL:2011`
+```
+This text has a [link to a page][docs].
+...
+This text has a [link as well][docs].
+...
+[docs]: https://www.cockroachlabs.com/docs
+```
+
+#### Link capitalization
 
 Link capitalization should match our [capitalization rules](#capitalization-rules) for page titles and headers:
 
 - **Use title case** when referring to the linked doc by its page title (e.g., "See __Best Practices__ for more information").
 - **Use sentence case** when referring to the linked doc by one of its headers (e.g., "See __Clock synchronization__ for further guidance").
 - **Use sentence case** - when referring to a linked doc without explicitly citing a page title or header (e.g., "[…] follow the __identifier rules__ when creating […]").
 
-Links are marked with inline text surrounded by square brackets followed by the link address in parentheses. If you are including a relative (i.e., internal) link:
+#### Links to CockroachDB docs pages in the same folder
 
-- To link to another page in the docs, use just the name of the file.
+To link to a page within the same folder (e.g., a page in `v23.1` to another page in `v23.1`), use the [Jekyll link syntax](https://jekyllrb.com/docs/liquid/tags/#links).
 
-    **Example:** `[here](name-of-article.html)`
+**Example:** `[Foreign Key Constraint]({% link v23.1/foreign-key.md %})`
 
-- To link to a specific heading on another page, use the name of the file plus the heading.
+To include a subsection, place it outside of the Liquid tag.
 
-    **Example:** `[xyz](name-of-article.html#heading-on-page)`
+**Example:** `[Rules for creating foreign keys]({% link v23.1/foreign-key.md %}#rules-for-creating-foreign-keys)`
 
-- To link to a specific heading on the current page, use just the heading.
+This also applies to files within a subfolder of the same folder (e.g., a link from `v23.1/abc.md` to `v23.1/architecture/xyz.md` or from `v23.1/architecture/xyz.md` to `v23.1/abc.md`).
 
-    **Example:** `[xyz](#heading-on-page)`
+**Example:** `[Multi-active availability]({% link v23.1/architecture/glossary.md %}#multi-active-availability)`
 
-- To link to a specific location on a page that is not a heading (e.g., a specific command-line flag in a table), add a manual anchor and use the `name` parameter:
+#### Links to CockroachDB docs pages outside of the current folder
 
-    **Example:**
+To link to a page outside of the current folder (e.g., a link from `v23.1` to `cockroachcloud`), use the fully qualified production URL:
 
-    ```
-    # Anchor:
-    <a name="flags-max-offset"></a>`--max-offset`
-    ```
+**Example:** `[Quickstart with CockroachDB](https://www.cockroachlabs.com/docs/cockroachcloud/quickstart)`
 
-    ```
-    # Link:
-    [--max-offset](#flags-max-offset)
-    ```
+#### Links to a specific location on a page that is not a heading
+
+To link to a specific location on a page that is not a heading (e.g., a specific command-line flag in a table), add a manual anchor and use the `name` parameter:
+
+**Example:**
+
+```
+# Anchor:
+<a id="flags-max-offset"></a>`--max-offset`
+```
+
+```
+# Link:
+[--max-offset](#flags-max-offset)
+```
+
+#### Localized external links
+
+For websites that automatically localize pages, avoid using localization elements directly within the URL. For example:
+
+- GitHub
+  - Instead of `https://docs.github.com/**en/**graphql/overview/explorer`
+  - Use `https://docs.github.com/graphql/overview/explorer`
+- Wikipedia
+  - Instead of `https://en.wikipedia.org/wiki/SQL:2011`
+  - Use `https://www.wikipedia.org/wiki/SQL:2011` or `https://wikipedia.org/wiki/SQL:2011`
 
 #### GitHub issues and pull requests