﻿---
title: Links
description: A Markdown link looks like this: It has two components: Link text enclosed in square brackets [ ], Link destination enclosed in parentheses ( ). Link...
url: https://docs-v3-preview.elastic.dev/elastic/docs-builder/pull/2831/syntax/links
---

# Links
A Markdown link looks like this:
```markdown
[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.
```markdown
[Security docs](../security/index.md)

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


#### Absolute paths

Use absolute paths to link to other pages inside the same repository.
```markdown
[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 `#`:
```markdown
[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:
```markdown
### Same-page links (anchors)
<!-- Creates anchor #same-page-links-anchors -->
```


#### Custom anchors

You can specify custom anchors for headings inline:
```markdown
## 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:
```markdown
## API Setup [First Time Setup!]
<!-- Creates anchor #first-time-setup -->
```


### Cross-repository links

Link to documentation in different repositories using the `scheme://path` syntax:
```markdown
[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.
</important>

Never use a full URL for links across documentation repositories.

### External links

Link to websites and resources outside the Elastic docs:
```markdown
[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 title="Output">
    - Documentation: https://example.com/docs/guide
    - Search: https://example.com/search?q=elasticsearch&page=1
    - Section link: https://example.com/page#configuration
  </tab-item>

  <tab-item title="Markdown">
    ```markdown
    - Documentation: https://example.com/docs/guide
    - Search: https://example.com/search?q=elasticsearch&page=1
    - Section link: https://example.com/page#configuration
    ```
  </tab-item>
</tab-set>


#### 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](#cross-repository-links) or relative link for better maintainability.
For example, this autolink triggers the hint: [https://www.elastic.co/docs](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:
```markdown
[**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:
```markdown
[](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:
```markdown
[](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 title="Output">
    - [Link](https://elastic.co/docs): This link uses the reference name as text.
    - [Your own text](https://elastic.co/docs): This link overrides the reference name.
  </tab-item>

  <tab-item title="Markdown">
    ```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
    ```
  </tab-item>
</tab-set>

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.
</warning>

```markdown
Some text $$$custom-anchor$$$ more text
```