Skip to content

Update links.md to add reference-style links #1326

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 10 commits into from
Jun 12, 2025
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
39 changes: 38 additions & 1 deletion docs/syntax/links.md
Original file line number Diff line number Diff line change
@@ -1,11 +1,13 @@
# Links

A markdown link looks like this:
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 `( )`

Expand Down Expand Up @@ -133,6 +135,41 @@ You can also auto-generate text for specific headings within files:
<!-- 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][Link]: This link overrides the reference name.

% References are typically added at the bottom of the page

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

:::

:::{tab-item} 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
```

:::


::::

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
Expand Down
Loading