Clarify link, table syntax guidelines

src/content/docs/style-guide/formatting/buttons.mdx → src/content/docs/style-guide/structure/buttons.mdx

@@ -5,6 +5,7 @@ tags:
   - Style guide quick reference
 redirects:
   - /docs/style-guide/quick-reference/buttons/
+  - /docs/style-guide/formatting/buttons/
 ---
 
 When you want to draw someone's attention to a link without putting it in a callout, buttons are an elegant way to do that.

src/content/docs/style-guide/formatting/callouts.mdx → src/content/docs/style-guide/structure/callouts.mdx

@@ -6,6 +6,7 @@ tags:
 redirects:
   - /docs/new-relic-only/basic-style-guide/writing-guidelines/callouts
   - /docs/style-guide/quick-reference/callouts/
+  - /docs/style-guide/formatting/callouts/
 ---
 
 Callouts direct your attention to information of special importance or to information that doesn't fit smoothly into the main text. Consider your reader. If your doc has too many callouts, it might confuse your reader about what matters the most and distract them from what does.

src/content/docs/style-guide/formatting/code-examples.mdx → src/content/docs/style-guide/structure/code-examples.mdx

@@ -12,6 +12,7 @@ redirects:
   - /docs/new-relic-only/basic-style-guide/writing-guidelines/code-formatting-guidelines
   - /docs/style-guide/writing-guidelines/code-formatting-guidelines-var-mark
   - /docs/style-guide/formatting/code-formatting-guidelines-var-mark
+  - /docs/style-guide/formatting/code-examples/
 ---
 
 import styleguideSyntaxHighlightingExampleCode from 'images/style-guide_screenshot-crop_syntax-highlighting-example-code.webp'

src/content/docs/style-guide/structure/collapsers.mdx

@@ -121,9 +121,8 @@ Here's an example of the collapser source:
 
 ## Collapsers triggers [#trigger-collapser]
 
-To open or close a collapser:
+The site automatically opens collapsers in a few scenarios:
 
-* Click the open buttons or **Show/Hide All**.
 * Arrive at an individual collapser via an anchor ID. For example, go directly to [Collapser 1 in the example above](/docs/style-guide/quick-reference/collapsers#collapser-1).
-* Type the shortcut key `s` to **s**how (open) all collapsers on the page.
 * Use **CMD+F** (or **CTRL+F**) to find in page and all the collapsers will open automatically.
+* Type the shortcut key `s` to **s**how (open) all collapsers on the page.

src/content/docs/style-guide/formatting/hyperlinks.mdx → src/content/docs/style-guide/structure/hyperlinks.mdx

@@ -5,6 +5,7 @@ redirects:
   - /docs/new-relic-only/style-guide/writing-guidelines/hyperlinks
   - /docs/new-relic-only/advanced-style-guide/writing-guidelines/hyperlinks
   - /docs/style-guide/writing-guidelines/hyperlinks
+  - /docs/style-guide/formatting/hyperlinks/
 ---
 
 Whenever possible, include hyperlinks where relevant within the text itself. Avoid creating lists of doc links in the **For more help** section, because it is harder for future writers to determine why they matter.
@@ -13,6 +14,27 @@ Whenever possible, include hyperlinks where relevant within the text itself. Avo
   If you're linking to the product, see our style guide page on [UI paths](/docs/style-guide/quick-reference/ui-paths).
 </Callout>
 
+## Link syntax [#link-syntax]
+
+The docs site uses Markdown inline link syntax:
+
+```markdown
+[link text](https://example.com)
+```
+
+If you're linking to another page on the docs site, you should use "relative" links (omitting the docs site's `https://docs.newrelic.com` root URL):
+
+```markdown
+[link text](/docs/category-path/doc-path/)
+```
+
+<Callout variant="tip">
+Markdown [also supports "reference"-style links](https://daringfireball.net/projects/markdown/syntax#link), where the destination URL is listed at the end of the doc. Although they'll work and render correctly, we avoid using this link style for a few reasons:
+
+* It's a less common style, and may be confusing for contributors.
+* Our docs are very long, which can make connecting a link to its destination unwieldly for contributors.
+</Callout>
+
 ## Link text [#hyperlinks-linktext]
 
 Follow these guidelines when writing text for hyperlinks:
@@ -79,16 +101,6 @@ Take the link test for these three examples. The last is the best for readers lo
 Get support at [support.newrelic.com](support.newrelic.com).
 ```
 
-## Docs site ("internal") links [#Hyperlinks-internal]
-
-When creating links to other documents on the docs site, include only the path from `/docs` forward. Do not include `https://docs.newrelic.com`, or the site will treat it as an external link.
-
-Here is an example:
-
-```
-[/docs/agents/php-agent/configuration/php-agent-newrelic-ini-settings](PHP agent (newrelic.ini) settings
-```
-
 ## Anchor links [#hyperlinks-anchor]
 
 If your link includes an anchor (for example, `#inivar-scope`), use the complete, **current** doc path it uses. Some browsers do not retain anchors with redirects.
@@ -140,16 +152,4 @@ In addition to the link text guidelines in this doc, here are some other things
 * Think about the best way to future-proof your links. If possible, point to a top-level domain, but not if it reduces the usefulness of the link. How stable is the content you're linking to? Is the URL likely to change?
 * Make sure your link is as useful as possible. What value are you trying to add to the document? Can that information be shared in another way?
 * Help the reader understand why you're linking to this external source. Is it a useful reference, such as a list of time zones? Is it a way to save someone time, such as linking directly to a hard-to-find file?
-* Make sure that your link is generally accessible. Are you linking to an external site that requires authentication, such as a private GitHub repo?
-
-## Linking to an arbitrary (non-heading, non-collapser-entry) section in a doc [#link-anywhere]
-
-H2 and H3 headings and collapsers have their own built-in IDs that you can link to. But sometimes you may want to link to a paragraph or to a table entry. In general, avoid this, and instead, link to headings and collapsers.
-
-Occasionally it's useful to link to a specific entry in a table, or a very important paragraph in a conceptual explanation. To do that, place a `<span>` tag around some text, using this format:
-
-```
-<span id="name">your text</span>
-```
-
-And then link to it using the standard anchor link format.
+* Make sure that your link is generally accessible. Are you linking to an external site that requires authentication, such as a private GitHub repo?

src/content/docs/style-guide/structure/side-by-side.mdx

@@ -7,11 +7,11 @@ tags:
 
 import exampleImg from 'images/network_screenshot-full_device-performance.webp'
 
-The `SideBySide` component lets you split the screen in half, or more sections. You can use it to display a screenshot on the left-hand side of a doc, and some text on the right. 
+The `SideBySide` component lets you split the screen in half, or more sections. A common use case is to show a screenshot in the right column, and accompanying text on the left.
 
 You need to wrap the content for each side inside a `Side` component, but you can add as much content as you need inside each `Side`.
 
-Ideally, there'll never be more than two columns of content in a doc.
+Technically the component supports more than two `Side` columns, but you should avoid using more than two.
 
 Here's an example of the component: 
 

src/content/docs/style-guide/structure/tables.mdx

@@ -16,22 +16,22 @@ Use sentence case for text in every table column unless it's a specific file nam
 
 <Callout variant="tip">
 The Keyboard Maestro macro for the Table component is `kktable`
-  </Callout>
+</Callout>
 
-## Table template
+## Table syntax
 
-This is a basic table template.
+Our tables are built as MDX React components. In practice, they're quite similar to HTML tables::
 
 ```html
 <table>
   <thead>
     <tr>
       <th style={{ width: "200px" }}>
-        Item
+        **Item**
       </th>
 
       <th>
-        **Requirements**
+        **Description**
       </th>
     </tr>
   </thead>
@@ -48,66 +48,25 @@ This is a basic table template.
 </table>
 ```
 
-Additional options:
-
-<table>
-  <thead>
-    <tr>
-      <th style={{ width: "200px" }}>
-        If you want to...
-      </th>
-
-      <th>
-        Do this
-      </th>
-    </tr>
-  </thead>
-
-  <tbody>
-    <tr>
-      <td>
-        Shade every other row
-      </td>
-
-      <td>
-        Use `<table class="alternate">`.
-      </td>
-    </tr>
-
-    <tr>
-      <td>
-        Create a table within a clamshell
-      </td>
+<Callout variant="tip">
+The docs site technically supports [Markdown tables](https://www.markdownguide.org/extended-syntax/#tables), but we avoid using them for a few reasons:
 
-      <td>
-        Use `<table class="spec">`.
-      </td>
-    </tr>
+* There are multiple flavors of Markdown, and different flavors use different table syntaxes. This is because John Gruber's original Markdown spec did not include tables.
+* Markdown tables don't support elements that span multiple lines, and most of our tables include code blocks, bulleted lists, or other elements that require multiple lines.
+</Callout>
 
-    <tr>
-      <td>
-        Highlight row in gray on hover
-      </td>
+## Setting column width [#column-width]
 
-      <td>
-        Add the class `table-hover` to the `<table>` element.
-      </td>
-    </tr>
+You can set column width with a style rule on the `<th>` element:
 
-    <tr>
-      <td>
-        Specify individual column widths
-      </td>
+```html
+<th style={{ width: "200px" }}>
+```
 
-      <td>
-        Set `style="width:###px;"` in the header row. In general, for two-column tables on the docs site:
+In general, for two-column tables on the docs site:
 
-        1. Set the first column as 200 pixels: `<th style="width:200px">`.
-        2. To allow the table to adjust automatically to the remaining page width, do not set a width for the second column.
-      </td>
-    </tr>
-  </tbody>
-</table>
+1. Set the first column as 200 pixels: `style={{ width: "200px" }}`.
+2. To allow the table to adjust automatically to the remaining page width, do not set a width for the second column.
 
 ## Tables to describe UI functions [#tables-ui]
 

src/content/docs/style-guide/structure/tiles.mdx

@@ -12,11 +12,11 @@ DocTiles, or just `tiles` for short, are a unique type of react component design
 
 Tiles are set up similarly to `tabs`, by placing the component using the following format where you want them to be in the doc. They are framed by `<DocTiles>` tabs, with each tile in the group being framed by `<DocTile>` tabs. The `DocTile path` section is where you place the hyperlink that you want the tile to lead to, and the `Text` section before the closing tag is where you put the text you want to display on the tile. You can add as many tiles as you want to a section, but try to limit them as best you can to avoid the component becoming overwhelming.
 
-```
+```html
 <DocTiles>
-<DocTile path="">Text</DocTile>
-<DocTile path="">Text</DocTile>
-<DocTile path="">Text</DocTile>
+    <DocTile path="/docs/path/to/a/doc">Text</DocTile>
+    <DocTile path="/docs/path/to/a/doc">Text</DocTile>
+    <DocTile path="/docs/path/to/a/doc">Text</DocTile>
 </DocTiles>
 ```
 
@@ -47,8 +47,6 @@ For quick reference, see the code example and screenshot below.
     src={styleTileTypes}
 />
 
-
-
 <Callout variant="tip">
 The Keyboard Maestro macro for tiles is `kktilegroup`.
 </Callout>

src/content/docs/style-guide/formatting/titles.mdx → src/content/docs/style-guide/structure/titles.mdx

@@ -1,38 +1,37 @@
 ---
-title: Titles vs Short titles vs Path vs Redirects
+title: Titles, short titles, and paths
 redirects: 
   - /docs/style-guide/quick-reference/titles/
+  - /docs/style-guide/formatting/titles/
 ---
 
 This doc explains the difference between Titles and Short titles. It also delves into how these are affected and affect Paths and Redirects.
 
 ## Titles
 
-Titles are the title rendered at the top of each doc. The title of this doc is **Titles vs Short Titles vs Path vs Redirects**.
+Titles are the title rendered at the top of each doc. The title of this doc is **Titles, short titles, and paths**.
 
-The title of a document is define in the front matter. This doc's title is defined below:
+The title of a document is defined in the front matter. This doc's title is defined below:
 
-```
----
-title: Titles vs Short Titles vs Path vs Redirects
----
+```yaml
+title: Titles, short titles, and paths
 ```
 
 ## Short titles
 
-Short titles are displayed in the left nav. These are used in cases where the title is a bit too long to be easily scanned. The Short title of this doc is **Titles vs Short titles**.
+Short titles are displayed in the left nav. These are used in cases where the title is a bit too long to be easily scanned. The short title of this doc is **Titles and short titles**.
 
-The Short title is defined in the corresponding navigation file. This doc's short title is define in `src/content/nav/style-guide.yml`:
+The short title is defined in the corresponding navigation file. This doc's short title is defined in `src/content/nav/style-guide.yml`:
 
-```
-- title: Tables
-  path: /docs/style-guide/quick-reference/tables
+```yaml
+- title: Titles and short titles
+  path: /docs/style-guide/structure/titles
 ```
 
 Read more about [editing the left nav](/docs/style-guide/processes-procedures/update-left-navigation-pane).
 
-## Paths and Redirects
+## Paths and redirects
 
-The path and file name of a specific doc has no bearing on the title of that doc. The path for this doc is `/docs/style-guide/quick-reference/tables`. Notice that although the file is named `tables`, neither the title or the short title is called `Titles`.
+The path and file name of a specific doc has no bearing on the title of that doc. The path for this doc is `/docs/style-guide/structure/titles`. Notice that although the file is named `titles`, neither the title or the short title is called `Titles`.
 
 Redirects fully ignore the title, short title, and path of a doc. It will redirect you to wherever the redirect points. [Read more about redirects](/docs/style-guide/processes-procedures/rename-or-redirect-document).

src/content/docs/style-guide/formatting/ui-paths.mdx → src/content/docs/style-guide/structure/ui-paths.mdx

@@ -5,6 +5,7 @@ tags:
   - Style guide quick reference
 redirects:
   - /docs/style-guide/quick-reference/ui-paths
+  - /docs/style-guide/formatting/ui-paths/
 ---
 
 Explaining where to find UI pages and elements can be tricky. When done well, path descriptions can make navigating our UI easier for readers. We have different options for handling smaller UI paths and longer UI paths.  

src/nav/style-guide.yml

@@ -19,24 +19,16 @@ pages:
             path: /docs/style-guide/capitalization/capitalization
           - title: 'Product and capabilities: capitalization, trademarks, and usage'
             path: /docs/style-guide/capitalization/product-capability-feature-usage
-      - title: Formatting
-        pages:
-          - title: Buttons
-            path: /docs/style-guide/formatting/buttons
-          - title: Callouts
-            path: /docs/style-guide/formatting/callouts
-          - title: Code references
-            path: /docs/style-guide/formatting/code-examples
-          - title: Hyperlinks
-            path: /docs/style-guide/formatting/hyperlinks
-          - title: 'Titles, short titles, and paths'
-            path: /docs/style-guide/formatting/titles
-          - title: UI paths
-            path: /docs/style-guide/formatting/ui-paths
       - title: Content structure and components
         pages:
           - title: Introduction to components
             path: /docs/style-guide/structure/intro-to-components
+          - title: Buttons
+            path: /docs/style-guide/structure/buttons
+          - title: Callouts
+            path: /docs/style-guide/structure/callouts
+          - title: Code references
+            path: /docs/style-guide/structure/code-examples
           - title: Collapsers
             path: /docs/style-guide/structure/collapsers
           - title: Comments
@@ -45,6 +37,8 @@ pages:
             path: /docs/style-guide/structure/levels-headings
           - title: Indentation
             path: /docs/style-guide/structure/styleguide-markup-indentation
+          - title: Links
+            path: /docs/style-guide/structure/hyperlinks
           - title: Lists
             path: /docs/style-guide/structure/lists
           - title: Pop-overs
@@ -59,6 +53,10 @@ pages:
             path: /docs/style-guide/structure/tabs
           - title: Tiles
             path: /docs/style-guide/structure/tiles
+          - title: 'Titles and short titles'
+            path: /docs/style-guide/structure/titles
+          - title: UI paths
+            path: /docs/style-guide/structure/ui-paths
       - title: 'Images, videos, and captions'
         pages:
           - title: Screenshots and images