Repository navigation
Adopt the Word-authored Hyperlink, CommentText and CommentReference style definitions #117
Description
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
- Lift the three
w:styledefinitions verbatim out ofcomments-rich-para.docxintosrc/docx/templates/default.docxand the unpackeddefault-docx-template/word/styles.xml. - Delete
_add_default_hyperlink_style()and the branch that calls it (text/paragraph.py:166), and haveadd_hyperlink()resolve the style throughstyleslike everything else. - 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:basedOnon each lifted definition —CommentTextis typically based onNormalandCommentReferenceonDefault 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.pyand the template part-size assertions move.
Split out of #23 so the unblocked part can ship without waiting for a Word session.
Activity
toxicphreAK commentedon Aug 5, 2026
Landed in #139. The three definitions plus
CommentTextChar(thew:linkofCommentText, which would otherwise dangle) lifted verbatim fromcomments-rich-para.docxinto both the bundled template anddefault-styles.xml, withw:rsidstripped — 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:basedOnandw:linkresolves in the template (a test asserts it), and the visible change — links are theme-coloured rather than hardcoded blue — is in HISTORY.rst.FootnoteText,FootnoteReferenceand the endnote pair are still missing and stay on #23.