docx/hyperlink

Metadata

XPath assertions

Render assertions

Generator source

scripts/gen_hyperlink.py

#!/usr/bin/env python3
"""Generate ``fixtures/docx/hyperlink.docx``.

A minimal document exercising the ``w:hyperlink`` element with an
external URL target. One paragraph containing one hyperlink whose
visible text is ``Click here for example`` and whose relationship
resolves to ``https://example.com/``.

Uses the fork's ``Paragraph.add_hyperlink()`` high-level API
(python-docx >= 2026.05.0). The default ``style="Hyperlink"`` is
disabled here because a fresh ``Document()`` does not include that
character style; the spec cares about the presence of
``<w:hyperlink r:id="…">`` and the external relationship target, not
the character style.
"""

from __future__ import annotations

from pathlib import Path

from docx import Document

_REPO_ROOT = Path(__file__).resolve().parent.parent
_OUT = _REPO_ROOT / "fixtures" / "docx" / "hyperlink.docx"


def main() -> int:
    doc = Document()
    paragraph = doc.add_paragraph()
    paragraph.add_hyperlink(
        url="https://example.com/",
        text="Click here for example",
        style=None,
    )
    _OUT.parent.mkdir(parents=True, exist_ok=True)
    doc.save(_OUT, reproducible=True)
    print(_OUT)
    return 0


if __name__ == "__main__":
    raise SystemExit(main())

Manifest (expanded)

{
  "$schema": "../manifest.schema.json",
  "id": "docx/hyperlink",
  "title": "External hyperlink",
  "format": "docx",
  "category": "references",
  "summary": "A run wrapped in a <w:hyperlink> whose r:id resolves to an external URL relationship.",
  "spec": {
    "source": "ecma-376-5-part-1",
    "clause": "17.16.22",
    "element": "w:hyperlink",
    "rnc_reference": "spec/ecma-376-5/part-1/rnc/WordprocessingML.rnc",
    "xsd_reference": "spec/ecma-376-5/part-1/xsd/wml.xsd",
    "notes": "External hyperlinks are expressed as a <w:hyperlink r:id='rIdN'> whose rId points at a <Relationship Type='.../hyperlink' Target='<url>' TargetMode='External'/> entry in word/_rels/document.xml.rels. Anchor-only links (to a bookmark inside the document) use @w:anchor instead. This fixture exercises the external variant."
  },
  "fixtures": {
    "machine": "docx/hyperlink",
    "office": "docx/hyperlink"
  },
  "generator": {
    "python": "scripts/gen_hyperlink.py"
  },
  "assertions": [
    {
      "id": "hyperlink-element-present",
      "part": "word/document.xml",
      "namespaces": {
        "w": "http://schemas.openxmlformats.org/wordprocessingml/2006/main",
        "r": "http://schemas.openxmlformats.org/officeDocument/2006/relationships"
      },
      "xpath": "//w:hyperlink[w:r/w:t[normalize-space()='Click here for example']]/@r:id",
      "must": "exist",
      "description": "The hyperlink wrapping the visible text must carry an r:id attribute pointing at the external relationship."
    },
    {
      "id": "hyperlink-relationship-external",
      "part": "word/_rels/document.xml.rels",
      "namespaces": {
        "pr": "http://schemas.openxmlformats.org/package/2006/relationships"
      },
      "xpath": "//pr:Relationship[@Type='http://schemas.openxmlformats.org/officeDocument/2006/relationships/hyperlink' and @TargetMode='External']/@Target",
      "must": "equal",
      "value": "https://example.com/",
      "description": "The hyperlink relationship must be external and point at the expected target URL."
    }
  ],
  "render_assertions": [
    {
      "id": "hyperlink-anchor-present",
      "kind": "css_selector",
      "selector": ".docx-wrapper a[href]",
      "must": "match-text",
      "value": "Click here for example",
      "description": "At least one rendered <a href=...> under .docx-wrapper must contain the hyperlink display text."
    }
  ]
}