diff --git a/docs/syntax/links.md b/docs/syntax/links.md index 610654fd..7f11243b 100644 --- a/docs/syntax/links.md +++ b/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 `://`, where is the repository name and 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) + ``` -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] + ``` -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!] + +``` -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 `://`, 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) + + +[](monitoring.md#alerting) + ``` -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) + -## Inline anchors +[](#configuration) + +``` -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. \ No newline at end of file +::::{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 +``` \ No newline at end of file diff --git a/docs/syntax/titles.md b/docs/syntax/titles.md index af89fe57..ab8ffb0a 100644 --- a/docs/syntax/titles.md +++ b/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)