Skip to content

Adopt the Word-authored Hyperlink, CommentText and CommentReference style definitions #117

Closed

Description

@toxicphreAK

Five styles the library writes by name are not defined in the bundled template, so each site works around the gap:

style id written by workaround
Hyperlink Paragraph.add_hyperlink() _add_default_hyperlink_style() (src/docx/text/paragraph.py:168) synthesises a blue underlined character style on first use
CommentText, CommentReference Comment.add_paragraph(), Run.mark_comment_range() assigns the id straight to the element (comments.py:113, oxml/text/run.py:181), bypassing the styles lookup that would raise
FootnoteText, FootnoteReference Footnote.add_paragraph(), Run.add_footnote_reference() same, footnotes.py:110, text/run.py:311

Today:

>>> document.styles["Hyperlink"]
KeyError: "no style with name 'Hyperlink'"

— on a document where the library itself has just applied that style. The reference resolves to nothing, so Word falls back to default character formatting and the link renders as ordinary text.

#23 has this blocked on having Word available to author the definitions. Three of the five do not need Word. The repo already carries Word-authored definitions of Hyperlink, CommentText and CommentReference, in fixtures Word wrote:

Hyperlink          features/steps/test_files/comments-rich-para.docx
                   features/steps/test_files/par-hlink-frags.docx
                   features/steps/test_files/par-hyperlinks.docx
CommentReference   features/steps/test_files/comments-rich-para.docx
CommentText        features/steps/test_files/comments-rich-para.docx

Those are authentic Word output, not a guess at what Word would write — which is the exact objection that stalled #23.

What to do

  1. Lift the three w:style definitions verbatim out of comments-rich-para.docx into src/docx/templates/default.docx and the unpacked default-docx-template/word/styles.xml.
  2. Delete _add_default_hyperlink_style() and the branch that calls it (text/paragraph.py:166), and have add_hyperlink() resolve the style through styles like everything else.
  3. Leave the comment and footnote sites assigning ids directly for now — that is a separate simplification and the footnote styles are still missing.

FootnoteText, FootnoteReference and the endnote pair are not in the corpus and still need Word, or a Word-authored document from elsewhere. They stay on #23.

Watch out for

  • Check w:basedOn on each lifted definition — CommentText is typically based on Normal and CommentReference on Default Paragraph Font. Both exist in the template, but confirm rather than assume, or the imported styles inherit from nothing.
  • Hyperlink's definition uses a theme colour (w:color w:themeColor="hyperlink"). It will resolve against the template's own theme, which is the same Office theme the fixtures were written against, so it should look right — but that is worth eyeballing in Word before merging rather than trusting.
  • The synthesised style _add_default_hyperlink_style() produces today is hardcoded blue and underlined. The real definition is theme-linked and includes the visited-link behaviour, so links in documents created after this change will look slightly different. That is the point, but it is a visible change and belongs in HISTORY.rst.
  • tests/test_reproducible.py and the template part-size assertions move.

Split out of #23 so the unblocked part can ship without waiting for a Word session.

Activity

  1. toxicphreAK commented on Aug 5, 2026

    @toxicphreAK
    OwnerAuthor

    Landed in #139. The three definitions plus CommentTextChar (the w:link of CommentText, which would otherwise dangle) lifted verbatim from comments-rich-para.docx into both the bundled template and default-styles.xml, with w:rsid stripped — it records the editing session Word wrote them in and this library does not maintain rsids. _add_default_hyperlink_style() and its branch are gone.

    Both watch-outs check out: every w:basedOn and w:link resolves in the template (a test asserts it), and the visible change — links are theme-coloured rather than hardcoded blue — is in HISTORY.rst. FootnoteText, FootnoteReference and the endnote pair are still missing and stay on #23.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementNew feature or request

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions