Skip to content

links.md

Latest commit

 

History

History
249 lines (158 loc) · 6.56 KB

links.md

File metadata and controls

249 lines (158 loc) · 6.56 KB

Links

A Markdown link looks like this:

[Link text](destination.md)

It has two components:

  • Link text enclosed in square brackets [ ]
  • Link destination enclosed in parentheses ( )

Link types

Internal links

Link between documentation pages in the same repository using the file’s relative or absolute path. The path must include the .md file extension. Optionally append an anchor to send readers to a specific section on a page. Never use a full URL for links between documentation pages.

Relative paths

Use relative paths to link to other pages inside the same repository.

[Security docs](../security/index.md)

[Install](monitor/index.md#installation)

Absolute paths

Use absolute paths to link to other pages inside the same repository.

[API keys](/deploy-manage/api-keys.md)

[Authentication](/deploy-manage/api-keys.md#authentication)

Note the leading / before the path.

Same-page links (anchors)

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. They are automatically generated by:

  • Converting to lowercase
  • Replacing spaces with hyphens
  • Removing special characters

For example:

### Same-page links (anchors)
<!-- Creates anchor #same-page-links-anchors -->

Custom anchors

You can specify custom anchors for headings inline:

## License management [manage-license]
<!-- Creates anchor #manage-license instead of #license-management -->

Custom anchors are also cleaned up to remove special characters and spaces, and converted to lowercase:

## API Setup [First Time Setup!]
<!-- Creates anchor #first-time-setup -->

Cross-repository links

Link to documentation in different repositories using the scheme://path syntax:

[Kibana API documentation](kibana://api/index.md)
[Beats configuration](beats://configuration.md)

The syntax follows the format <scheme>://<path>, where:

  • scheme: The target repository name (e.g., kibana, beats)
  • path: The file path within that repository

:::{important}

  • The path in cross-repo links must be relative to the docset.yml file and not the full path within the repo.
  • The link text is mandatory; if you omit it, the link will fail to be displayed. :::

Never use a full URL for links across documentation repositories.

Cross-repository validation only applies to schemes declared in cross_links in your docset.yml. If a scheme is not declared:

  • cursor://... links pass through as custom protocol links.
  • vscode:... links pass through as custom protocol links.
  • Other undeclared schemes are treated as invalid cross-repository links and produce build errors.

External links

Link to websites and resources outside the Elastic docs:

[Elastic Cloud](https://cloud.elastic.co)
[Elastic Documentation](https://www.elastic.co/guide)

Autolinks

Bare https:// URLs in text are automatically converted to clickable links.

Autolinks:

  • Only work with https:// URLs (not http://).
  • Open in a new tab.
  • Display the external link indicator.
  • Are not rendered inside code blocks or inline code.

Excluded URLs

Certain URLs are intentionally excluded from autolinking:

Pattern Example Reason
URLs with explicit ports https://example.co:443/path Typically configuration examples.
Example and placeholder domains (localhost, 127.0.0.1, example.com, example.org, example.net, and subdomains) https://localhost/api Reserved for documentation examples.
URLs with template placeholders ({{ or }}) https://{{cluster_id}}.example.co Contain variables meant to be replaced.
Broken AsciiDoc-style links ([ or ] in URL) https://example.org/page[text Malformed links needing manual correction.

Examples

::::{tab-set}

:::{tab-item} Output

:::

:::{tab-item} Markdown

- Documentation: https://example.com/docs/guide
- Search: https://example.com/search?q=elasticsearch&page=1
- Section link: https://example.com/page#configuration

:::

::::

Hint for elastic.co/docs URLs

Autolinks pointing to elastic.co/docs trigger a hint during build, suggesting you replace them with a cross-repository link or relative link for better maintainability.

For example, this autolink triggers the hint: https://www.elastic.co/docs

Instead, use a cross-repository link or a relative link.

Link formatting

Style link text

You can include Markdown formatting within link text:

[**Distributed architecture**](distributed-architecture.md)

[*Production guidance* and best practices](production-guidance.md)

[`manage-connectors.md`](manage-connectors.md)

Auto-generated link text

When linking to local Markdown files, you can omit the link text to automatically use the target page's title:

[](maintenance.md)  
<!-- Uses the title from maintenance.md -->

[](monitoring.md#alerting)
<!-- Uses "Alerting" section title from monitoring.md -->

You can also auto-generate text for specific headings within files:

[](deploy.md#scaling)
<!-- Uses "Scaling" section title from deploy.md -->

[](#configuration)  
<!-- Uses the "Configuration" section title from current file -->

Reference-style links

docs-builder supports reference-style external links.

::::{tab-set}

:::{tab-item} Output

  • Link: This link uses the reference name as text.
  • Your own text: This link overrides the reference name.

% References are typically added at the bottom of the page

:::

:::{tab-item} Markdown

- [Link]: This link uses the reference name as text.
- [Your own text][Link]: This link overrides the reference name.

% References are typically added at the bottom of the page

[Link]: https://elastic.co/docs

:::

::::

Reference-style links are useful when adding links to tables, for example, or to update frequently used links more easily. Place them at the end of the document to simplify their management.

Legacy features

Inline anchors

::::{warning} This syntax exists to aid with migration. It is scheduled for removal and should not be used in new content. ::::

Some text $$$custom-anchor$$$ more text