Update linking syntax page (#415)

docs/syntax/links.md

@@ -1,105 +1,142 @@
 # Links
 
-A link contains link text (the visible text) and a link destination (the URI that is the link destination). The link text can include inline elements.
-
-## Inline link
+A markdown link looks like this:
 
 ```markdown
-[Link title](links.md)
+[Link text](destination.md)
 ```
+It has two components:
+- Link **text** enclosed in square brackets `[ ]`
+- Link **destination** enclosed in parentheses `( )`
 
-[Link title](links.md)
+## Link types
 
-```markdown
-[**Hi**, _I'm md_](links.md)
-```
+### Internal links
 
-[**Hi**, _I'm md_](links.md)
+Link between documentation files using either relative or absolute paths.
 
-## Anchor link
-
-You can link to a heading on a page with an anchor link. The link destination should be a `#` followed by the header text. Convert spaces to dashes (`-`).
+#### Relative paths
+Navigate relative to the current file's location:
 
 ```markdown
-I link to the [Inline link](#inline-link) heading above.
+[Security documentation](../security/index.md)
+
+[Monitoring guide](monitor/index.md)
 ```
 
-I link to the [Inline link](#inline-link) heading above.
+#### Absolute paths
+
+You can also use absolute paths to link to pages within the same repository.
+Say you're working on a random page somewhere in the `docs-content` repo. You can link to a page in the `deploy-manage` section like this:
 
 ```markdown
-I link to the [Notes](tables.md#notes) heading on the [Tables](tables.md) page.
+[API Keys](/deploy-manage/api-keys.md)
 ```
 
-## Cross Links
+Note the leading `/` before the path.
+
+### Same-page links (anchors)
 
-Cross links are links that point to a different docset.
+Link to sections within the same document using heading anchors prefixed with `#`:
 
 ```markdown
-[Cross link](kibana://cross-link.md)
+[Jump to the next section](#next-section-anchor)
 ```
 
-The syntax is `<scheme>://<path>`, where <scheme> is the repository name and <path> is the path to the file.
+Headings will automatically create anchor links in the resulting HTML. They are automatically generated by:
 
-## Auto Text Links
+- Converting to lowercase
+- Replacing spaces with hyphens
+- Removing special characters
 
-If you link to a local markdown file but omit any link text `docs-builder` will use the target's [title](titles.md).
+For example:
 
 ```markdown
-[](applies.md)
+### Same-page links (anchors)
+<!-- Creates anchor #same-page-links-anchors -->
 ```
-will output: [](applies.md)
 
-You can go one step further to auto generate link text for headings within files:
+#### Custom anchors
+You can specify custom anchors for headings inline:
 
 ```markdown
-[](applies.md#sections)
+## License management [manage-license]
+<!-- Creates anchor #manage-license instead of #license-management -->
 ```
 
-will output: [](applies.md#sections)
+Custom anchors are also cleaned up to remove special characters and spaces, and converted to lowercase:
+
+```markdown
+## API Setup [First Time Setup!]
+<!-- Creates anchor #first-time-setup -->
+```
 
-This also applies to local anchors
+### Cross-repository links
 
+Link to documentation in different repositories using the `scheme://path` syntax:
 
 ```markdown
-[](#anchor-link)
+[Kibana API documentation](kibana://api/index.md)
+[Beats configuration](beats://configuration.md)
 ```
 
-will output: [](#anchor-link)
+The syntax follows the format `<scheme>://<path>`, where:
+- `scheme`: The target repository name (e.g., kibana, beats)
+- `path`: The file path within that repository
 
-## Heading anchors
+### External links
 
-Headings will automatically create anchor links in the resulting html. 
+Link to websites and resources outside the Elastic docs:
 
 ```markdown
-## This Is A Header
+[Elastic Cloud](https://cloud.elastic.co)
+[Elastic Documentation](https://www.elastic.co/guide)
 ```
 
-Will have an anchor link injected with the name `this-is-an-header`.
+## Link formatting
 
+### Style link text
 
-If you need more control over the anchor name you may specify it inline
+You can include Markdown formatting within link text:
 
 ```markdown
-## This Is A Header [#but-this-is-my-anchor]
+[**Distributed architecture**](distributed-architecture.md)
+
+[*Production guidance* and best practices](production-guidance.md)
+
+[`manage-connectors.md`](manage-connectors.md)
 ```
 
-Will result in an anchor link named `but-this-my-anchor` to be injected instead. 
+### Auto-generated link text
 
-Do note that these inline anchors will be normalized. 
+When linking to local Markdown files, you can omit the link text to automatically use the target page's title:
 
 ```markdown
-## This Is A Header [What about this for an anchor!]
+[](maintenance.md)  
+<!-- Uses the title from maintenance.md -->
+
+[](monitoring.md#alerting)
+<!-- Uses "Alerting" section title from monitoring.md -->
 ```
 
-Will result in the anchor `what-about-this-for-an-anchor`.
+You can also auto-generate text for specific headings within files:
 
+```markdown
+[](deploy.md#scaling)
+<!-- Uses "Scaling" section title from deploy.md -->
 
-## Inline anchors
+[](#configuration)  
+<!-- Uses the "Configuration" section title from current file -->
+```
 
-Docsbuilder temporary supports the abbility to create a linkable anchor anywhere on any document. 
+## Legacy features
 
-```markdown
-This is text and $$$this-is-an-inline-anchor$$$
-```
+### Inline anchors
 
-This feature exists to aid with migration however is scheduled for removal and new content should **NOT** utilize this feature.
+::::{warning}
+This syntax exists to aid with migration. It is scheduled for removal and **should not be used** in new content.
+::::
+
+```markdown
+Some text $$$custom-anchor$$$ more text
+```

docs/syntax/titles.md

@@ -17,7 +17,7 @@ This title is used both by the documentation navigation
 * Left hand site
 * Navigational elements such as breadcrumbs and previous/next links.
 
-As well as when using the [auto text links](./links.md#auto-text-links), e.g:
+As well as when using the [auto text links](./links.md#same-page-links-anchors), e.g:
 
 ```markdown
 [](titles.md)