From 23efc52214a59d7354f04a3b0a93700aa85d1dad Mon Sep 17 00:00:00 2001 From: Liam Thompson Date: Tue, 4 Feb 2025 18:47:37 +0100 Subject: [PATCH 01/10] Update linking syntax page --- docs/syntax/links.md | 129 +++++++++++++++++++++++++++---------------- 1 file changed, 82 insertions(+), 47 deletions(-) diff --git a/docs/syntax/links.md b/docs/syntax/links.md index 610654fde..633843253 100644 --- a/docs/syntax/links.md +++ b/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 `://`, where is the repository name and 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!` +
becomes
+`#remote-clusters-cross-cluster-setup` + +#### Custom anchors +You can specify custom anchors for headings inline: ```markdown -[](applies.md) +## License management [#manage-license] + ``` -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!] + ``` -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 `://`, 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 From 453ab0db05f6414539bc89b1c068f9d70e29ed82 Mon Sep 17 00:00:00 2001 From: Liam Thompson Date: Tue, 4 Feb 2025 18:48:47 +0100 Subject: [PATCH 02/10] Revert heading --- docs/syntax/links.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/syntax/links.md b/docs/syntax/links.md index 633843253..13c8583e0 100644 --- a/docs/syntax/links.md +++ b/docs/syntax/links.md @@ -1,4 +1,4 @@ -# Markdown links guide +# Links A markdown link looks like this: From 2bd4fecaa71a9a23275a8d3ca630d47503c335c2 Mon Sep 17 00:00:00 2001 From: Liam Thompson Date: Tue, 4 Feb 2025 18:50:42 +0100 Subject: [PATCH 03/10] expand --- docs/syntax/links.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/syntax/links.md b/docs/syntax/links.md index 13c8583e0..dfcf80142 100644 --- a/docs/syntax/links.md +++ b/docs/syntax/links.md @@ -26,7 +26,7 @@ Navigate relative to the current file's location: #### Absolute paths -You can also use absolute paths to link to pages: +You can also use absolute paths to link to pages within the same repository: ```markdown [API Keys](/deploy-manage/api-keys.md) From dd61948a54074e3d642605ab99b55e3e8355bc66 Mon Sep 17 00:00:00 2001 From: Liam Thompson Date: Tue, 4 Feb 2025 18:52:07 +0100 Subject: [PATCH 04/10] clean --- docs/syntax/links.md | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/docs/syntax/links.md b/docs/syntax/links.md index dfcf80142..d6005047b 100644 --- a/docs/syntax/links.md +++ b/docs/syntax/links.md @@ -40,9 +40,7 @@ Link to sections within the same document using heading anchors prefixed with `# [Jump to the next section](#next-section-anchor) ``` -Headings will automatically create anchor links in the resulting html. - -Heading anchors are automatically generated by: +Headings will automatically create anchor links in the resulting HTML. The are automatically generated by: - Converting to lowercase - Replacing spaces with hyphens From 104f844064a8f2b525d45dd0c10f2a05eb5bf03a Mon Sep 17 00:00:00 2001 From: Liam Thompson Date: Tue, 4 Feb 2025 18:54:10 +0100 Subject: [PATCH 05/10] avoid anchor in schematic example --- docs/syntax/links.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/syntax/links.md b/docs/syntax/links.md index d6005047b..3d5589bca 100644 --- a/docs/syntax/links.md +++ b/docs/syntax/links.md @@ -3,7 +3,7 @@ A markdown link looks like this: ```markdown -[Link text](#destination) +[Link text](destination.md) ``` It has two components: - Link **text** enclosed in square brackets `[ ]` From acb885e1e19124f501cacba4fd5736f088ce60ad Mon Sep 17 00:00:00 2001 From: Liam Thompson Date: Tue, 4 Feb 2025 18:59:39 +0100 Subject: [PATCH 06/10] good intentions --- docs/syntax/titles.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/syntax/titles.md b/docs/syntax/titles.md index af89fe577..ab8ffb0a0 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) From a786d34d47e5cf5af5d9825dc8de12390b55ddfb Mon Sep 17 00:00:00 2001 From: Liam Thompson Date: Tue, 4 Feb 2025 19:01:20 +0100 Subject: [PATCH 07/10] got to admit its getting meta --- docs/syntax/links.md | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/docs/syntax/links.md b/docs/syntax/links.md index 3d5589bca..13d6a3090 100644 --- a/docs/syntax/links.md +++ b/docs/syntax/links.md @@ -48,9 +48,10 @@ Headings will automatically create anchor links in the resulting HTML. The are a For example: -`## Remote clusters: Cross-cluster setup!` -
becomes
-`#remote-clusters-cross-cluster-setup` +```markdown +### Same-page links (anchors) + +``` #### Custom anchors You can specify custom anchors for headings inline: From 5401a08ef4f17223733a9e68ef9e028411d3c504 Mon Sep 17 00:00:00 2001 From: Liam Thompson Date: Wed, 5 Feb 2025 12:53:39 +0100 Subject: [PATCH 08/10] Clarify anchor creation syntax --- docs/syntax/links.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/syntax/links.md b/docs/syntax/links.md index 13d6a3090..2eace6300 100644 --- a/docs/syntax/links.md +++ b/docs/syntax/links.md @@ -57,14 +57,14 @@ For example: You can specify custom anchors for headings inline: ```markdown -## License management [#manage-license] +## License management [manage-license] ``` Custom anchors are also cleaned up to remove special characters and spaces, and converted to lowercase: ```markdown -## API Setup [#First Time Setup!] +## API Setup [First Time Setup!] ``` From 3f02e0c6500324454c89fff0a19f7e89f4639e05 Mon Sep 17 00:00:00 2001 From: Liam Thompson Date: Wed, 5 Feb 2025 13:01:23 +0100 Subject: [PATCH 09/10] Clarify absolute links further --- docs/syntax/links.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/docs/syntax/links.md b/docs/syntax/links.md index 2eace6300..961765088 100644 --- a/docs/syntax/links.md +++ b/docs/syntax/links.md @@ -26,12 +26,15 @@ Navigate relative to the current file's location: #### Absolute paths -You can also use absolute paths to link to pages within the same repository: +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 [API Keys](/deploy-manage/api-keys.md) ``` +Note the leading `/` before the path. + ### Same-page links (anchors) Link to sections within the same document using heading anchors prefixed with `#`: From b5cd235f8a7fa3150d2ea3cb750b7a0864753f3e Mon Sep 17 00:00:00 2001 From: Liam Thompson <32779855+leemthompo@users.noreply.github.com> Date: Wed, 5 Feb 2025 15:13:35 +0100 Subject: [PATCH 10/10] Fix typo Co-authored-by: Marci W <333176+marciw@users.noreply.github.com> --- docs/syntax/links.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/syntax/links.md b/docs/syntax/links.md index 961765088..7f11243be 100644 --- a/docs/syntax/links.md +++ b/docs/syntax/links.md @@ -43,7 +43,7 @@ Link to sections within the same document using heading anchors prefixed with `# [Jump to the next section](#next-section-anchor) ``` -Headings will automatically create anchor links in the resulting HTML. The are automatically generated by: +Headings will automatically create anchor links in the resulting HTML. They are automatically generated by: - Converting to lowercase - Replacing spaces with hyphens