Skip to main content
Unlisted page
This page is unlisted. Search engines will not index it, and only users having a direct link can access it.
Last updated on

Links

↑ Docs content model

Links are inline references to other pages or external URLs, including cross-references between docs pages.

When to use​

Link whenever you name a concept, task, or reference that lives on another page, and whenever you point a reader to an external resource. Cross-linking is how the docs form a navigable web instead of isolated pages — a Next steps or Additional resources section is built almost entirely from links.

Technical details​

Links use standard Markdown syntax, [link text](destination). Destinations take three forms:

  • Internal cross-reference — a root-absolute path rooted at docs/web/docs, including the .md extension. [Change data capture](/ldp/cdc.md) links to the generated output of docs/web/docs/ldp/cdc.md. Don't use relative paths.
  • Anchor within a page — append # and the heading's slug: [Limitations](/ldp/cdc.md#limitations). Omit the path to link within the current page: [see below](#limitations).
  • External URL — the full https:// URL.

The project also supports an auto-text link, [\_](/path/to/file.md). The \_ placeholder is replaced at build time with the target's H1 (or, for an anchored link, the linked heading's text), so the link text stays in sync when the target's title changes. \_ is real syntax — never rewrite it to literal text. The same applies to :re[...] tokens that appear in link text: they're replaced during the build, so leave them as written.

Rules​

  • Internal links are root-absolute (/ldp/cdc.md) and include the .md extension. Never relative.
  • Never reverse the [\_] placeholder or a :re[...] token to literal text.
  • When you move or rename a target file, add a redirect so existing inbound links don't break.

Style​

  • Prefer [\_](/path.md) for cross-references so the link text always matches the target's current title.
  • When you write link text by hand, make it describe the destination. Don't use "click here" or a bare URL as the text.
  • Link a term on its first, most relevant mention rather than on every occurrence.

Template​

Markdown
[Link text](/path/to/file.md)

[\_](/path/to/file.md)

Examples​

Example:

Markdown
See [Change data capture](/ldp/cdc.md) for the full pattern.

The [\_](/ldp/cdc.md) page covers advanced options.

Jump straight to the [limitations](/ldp/cdc.md#limitations).

Read the [Apache Spark documentation](https://spark.apache.org/docs/latest/).

Used in​

Content atoms appear in any page section. Links appear in nearly every section; they make up the bulk of Next steps and Additional resources.

On this page