HTX Guide · 1.5.0-alpha.2

Semantic references

Cross-reference blocks with (@id) — symbol table and trust rules.

HTX 1.5.0-alpha.2 (reference implementation 0.3.0-alpha.3) — Features below are available in the htx CLI unless noted as browser-only.

Status: Shipped in reference implementation 0.3.0-alpha.3 (HTX 1.5.0-alpha.1)

Motivation

Documents often need to point at a named block elsewhere in the same file — a data vault, a figure, or a reusable section — without duplicating content or relying on fragile line numbers.

Syntax

Register a symbol with #id on a block directive, then reference it with (@id) in prose:

::vault { #financial-table source="q2.csv" }
  Quarterly data
::

See (@financial-table) for details.

Rules

  1. #id in an attribute block registers the block in the document symbol table.
  2. (@id) in inline text resolves to the registered node at compile/transform time.
  3. References resolve only to nodes with trust: "trusted". Symbols inside ::data quarantine scopes are not referenceable.
  4. Duplicate #id values in one attribute block emit HTX005.
  5. Unresolved references emit HTX010; references to untrusted symbols emit HTX011; cycles emit HTX012.

LSP integration

htx-lsp provides go-to-definition from (@id) to the #id registration site. AST loc fields use UTF-8 byte offsets; the LSP boundary converts to UTF-16 code units (ADR-010).

Example

Live fixture: semantic-references example.

Prior art

  • Markdoc {% link %} and tag cross-references
  • Djot reference syntax (different model)
  • HTML id + fragment links (HTX keeps references semantic in the AST)