---
title: Outbound cross-links
description: Outbound cross-links are links from your documentation set to other documentation sets in different repositories. Outbound cross-links allow you to: Link...
url: https://www.elastic.co/elastic/docs-builder/docs/3066/reference/docs-builder/building-blocks/outbound-cross-links
---

# Outbound cross-links
**Outbound cross-links** are links from your documentation set to other documentation sets in different repositories.

## Purpose

Outbound cross-links allow you to:
- Link to documentation in other repositories.
- Maintain those links even as the target repository evolves.
- Validate links during local builds.
- Get warnings if target content is moved or deleted.


## Syntax

If both repositories publish to the same [Link Service](https://www.elastic.co/elastic/docs-builder/docs/3066/reference/docs-builder/building-blocks/link-service), they can link to each other using the cross-link syntax:
```markdown
[Link text](repository-name://path/to/file.md)
```

For example:
```markdown
See the [Search API documentation](elasticsearch://reference/api/search.md)
```


## How it works

You have to explicitly opt in to another repository's `Link Index` by adding it to your `docset.yml` file:
```yaml
cross_links:
  - docs-content
```

When `docs-builder` encounters a cross-link:
1. **Parse**: Extracts the repository name and path from the link
2. **Resolve**: Looks up the path in the locally cached [Link Index](https://www.elastic.co/elastic/docs-builder/docs/3066/reference/docs-builder/building-blocks/link-index) to get the actual URL
3. **Validate**: Verifies the link exists and generates an error if not
4. **Transform**: Replaces the cross-link with the fully resolved URL in the output

If the link scheme is not declared in `cross_links`, `{{dbuild}}` does not treat it as a valid cross-link target.
The only supported undeclared passthrough protocol schemes are:
- `cursor://...`.
- `vscode:...`.

Any other undeclared scheme still produces a cross-link validation error.

## Validation

During a build, `docs-builder`:
- **Validates immediately**: Checks all outbound cross-links against locally fetched [Link Index](https://www.elastic.co/elastic/docs-builder/docs/3066/reference/docs-builder/building-blocks/link-index) files.
- **Reports errors**: Reports errors about broken links before you publish.


## Configuration

To enable cross-links to a repository, add it to your `docset.yml`:
```yaml
cross_links:
  - elasticsearch
  - kibana
  - fleet
```

This instructs `docs-builder` to fetch the `Link Index` from the [Link Service](https://www.elastic.co/elastic/docs-builder/docs/3066/reference/docs-builder/building-blocks/link-service) during the build process which are then cached locally.
`docs-builder` will validate locally cached `Link Index` files against the remote `Link Index` files on each build fetching updates as needed.
Now you can create cross-links e.g `elasticsearch://path/to/file.md`
The explicit opt-in prevents each repository build having the fetch all the links for all the repositories in the [`Link Catalog`](https://www.elastic.co/elastic/docs-builder/docs/3066/reference/docs-builder/building-blocks/link-catalog) of which there may be many.

## Best practices


### Link to files, not URLs

**Good:**
```markdown
[Search API](elasticsearch://reference/api/search.md)
```

**Bad:**
```markdown
[Search API](https://www.elastic.co/guide/en/elasticsearch/reference/current/search.html)
```

The cross-link syntax is resilient to:
- URL structure changes.
- File moves (if redirects are configured).
- Version differences.


### Link to headings

You can link to specific headings within a page:
```markdown
[Query DSL](elasticsearch://reference/query-dsl.md#match-query)
```


## Related concepts

- [Inbound Cross-links](https://www.elastic.co/elastic/docs-builder/docs/3066/reference/docs-builder/building-blocks/inbound-cross-links) - Links from other repositories to yours.
- [Link Index](https://www.elastic.co/elastic/docs-builder/docs/3066/reference/docs-builder/building-blocks/link-index) - How cross-links are resolved.
- [Links syntax](https://www.elastic.co/elastic/docs-builder/docs/3066/reference/docs-builder/syntax/links) - Complete link syntax documentation.