Clarify link, table syntax guidelines

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

@@ -13,6 +13,23 @@ 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:
+
+```[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):
+
+```[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:

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,23 @@ 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>
+```<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]