Update linking syntax page

Author: leemthompo

docs/syntax/links.md

@@ -1,105 +1,140 @@
-# Links
+# Markdown links guide
 
-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)
 ```
+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:
 
 ```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
+### 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.
+
+Heading anchors are automatically generated by:
+
+- Converting to lowercase
+- Replacing spaces with hyphens
+- Removing special characters
 
-## Auto Text Links
+For example:
 
-If you link to a local markdown file but omit any link text `docs-builder` will use the target's [title](titles.md).
+`## Remote clusters: Cross-cluster setup!` 
+<br>becomes<br>
+`#remote-clusters-cross-cluster-setup` 
+
+#### Custom anchors
+You can specify custom anchors for headings inline:
 
 ```markdown
-[](applies.md)
+## License management [#manage-license]
+<!-- Creates anchor #manage-license instead of #license-management -->
 ```
-will output: [](applies.md)
 
-You can go one step further to auto generate link text for headings within files:
+Custom anchors are also cleaned up to remove special characters and spaces, and converted to lowercase:
 
 ```markdown
-[](applies.md#sections)
+## API Setup [#First Time Setup!]
+<!-- Creates anchor #first-time-setup -->
 ```
 
-will output: [](applies.md#sections)
-
-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
+```