Repository navigation
Keep step text formatting in Word and PowerPoint exports - #324
Conversation
Word and PowerPoint built step descriptions and callouts from the plain-text version, so bold, italics, inline code, links and lists were lost: a numbered list came out as bullets, and a quote ran into the next sentence. - exporters/word-rich.js: the Confluence exporter's rich-text renderer, moved out so Word uses it too. Confluence's output is byte-for-byte unchanged. In Word (no list or link styles), formatting is written on each run: bold, italic, strikethrough, code, links to web pages and to other steps' headings, real numbered and bulleted lists (a plain "•" any font has), quotes, tables. - Word callouts: label and text are paragraphs sharing one border and shading; their lists are unindented "•" and "1." lines, since an indent moves a paragraph's border and would break the box. - Word pagination keeps a block's paragraphs together (each keeps with the next) when it fits a page; a block too tall to keep may break between them. - exporters/pptx-text.js: description HTML as paragraphs of formatted runs. Slides show bold, italic, strikethrough, inline code, real bullets and numbers, quotes and tables; web links open their page and links to another step jump to its slide. Text split onto a "(continued)" slide keeps its formatting on both sides.
|
@codex review |
Codex Review Summary: ✅ CompletedThis comment shows the latest Codex review activity on this pull request.
ℹ️ About Codex in GitHubYour team has set up Codex to review pull requests in this repo. Reviews are triggered when you
Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings. |
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 3d9311edf5
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| const head = sliceRuns(item.runs, 0, parts[0].length); | ||
| const tail = sliceRuns(item.runs, item.text.length - parts[1].length); |
There was a problem hiding this comment.
Split formatted runs using offsets in the original text
When a paragraph contains long unbroken text, such as Chinese prose or a long identifier, wrapText() breaks it between characters and splitText() rejoins those lines with inserted spaces. The resulting lengths are not offsets into item.runs, so these slices overlap or select the wrong characters. For example, splitting a 200-character unbroken paragraph into five measured lines produced 219 characters across the two run slices. Subsequent slides render the slices rather than item.text, duplicating content and separating formatting from the text being measured. Preserve the original character offset when splitting instead of deriving it from the reconstructed strings.
Useful? React with 👍 / 👎.
There was a problem hiding this comment.
Fixed in 6054bda: splitText now returns a character offset in the paragraph's own text, found by walking the wrapped lines against it, so both halves slice item.runs at the same point. Regression test: 1,500 bold + 1,500 plain unbroken CJK characters split across slides with no characters repeated or lost.
| function richRuns(ctx, runs, base) { | ||
| return runs.map((r) => { | ||
| let link = null; | ||
| if (r.href && /^(https?:|mailto:)/i.test(r.href)) link = ctx.addLink({ href: r.href }); |
There was a problem hiding this comment.
Decode HTML entities before registering hyperlink targets
For links with multiple query parameters, sanitized HTML contains an escaped URL such as https://example.com/?a=1&b=2. htmlToBlocks() leaves entities encoded in href, so registering that value here and later applying escapeXml() writes & into the relationship. PowerPoint consequently opens a URL containing the literal parameter name amp;b instead of b, breaking query-dependent destinations. Decode the HTML attribute value before creating the relationship; the newly enabled Word hyperlinks have the same issue through WordRichText.runs().
Useful? React with 👍 / 👎.
There was a problem hiding this comment.
Fixed in 6054bda: htmlToBlocks() now decodes entities in href the way it already decodes text, which covers both PowerPoint and Word. Regression test checks both relationship parts for ?a=1&b=2 and no &.
| out.push({ | ||
| runs, | ||
| text: joined(runs), | ||
| list: isList ? { ordered: block.type === 'oli', n: block.n || 1, level: Math.max(0, (block.indent || 1) - 1), continued } : null, |
There was a problem hiding this comment.
Preserve the parser's zero-based list nesting depth
For nested lists, htmlToBlocks() already returns zero-based list depths: a top-level item has indent: 0 and its child has indent: 1. Subtracting one again maps both to level: 0, so PowerPoint renders child instructions at the same indentation as their parents, losing the hierarchy. Use the parser's list depth directly; for example, <ol><li>Parent<ul><li>Child</li></ul></li><li>Next</li></ol> currently produces level zero for all three items.
Useful? React with 👍 / 👎.
There was a problem hiding this comment.
Fixed in 6054bda, in both PowerPoint and Word (word-rich.js had the same off-by-one). Word also now keeps one list per depth, so in your example "Next" continues as 2. rather than restarting at 1. after the nested bullet list.
…ord and PowerPoint - Lists: the parser's list depth is already zero-based, so a nested item was flattened to its parent's level. Word now also keeps one list per depth, so an outer numbered list keeps counting after a nested one. - Links: decode entities in href, so "?a=1&b=2" links to "?a=1&b=2" instead of "?a=1&amp;b=2". - Slides: split a long paragraph at an offset in its own text. Rejoining wrapped lines with spaces put the cut in the wrong place for long unbroken text, repeating characters across the two slides.
Issue
No issue filed; this PR describes the problem and the fix. It's the first of two from a review of every export format. #325 builds on it.
Summary
Word and PowerPoint exports lost the formatting of step text. Both built descriptions and callouts from the plain-text version:
PDF, HTML, Markdown, Confluence and Wiki.js already kept all of this.
Now Word and PowerPoint keep it too, in descriptions and in callouts:
Changes
exporters/word-rich.js(new): the Confluence exporter's rich-text renderer, moved out so Word can share it.exporters/confluence-word.js: uses the shared module.exporters/docx.js:exporters/pptx-text.js(new): description HTML turned into paragraphs of formatted runs (whitespace collapsed so they measure and split exactly), list markers, and splitting runs at a character offset.exporters/pptx.jsandexporters/pptx-xml.js:tests/unit/rich-text-exports.test.js(new) covers:tests/unit/docx-pagination.test.js: expected paragraph counts updated for two-paragraph callouts, and the callout's border and shading are now checked in schema order (pBdrbeforeshd). The old order was the other way round.exporters-binary,brandingandpptx-layouttests:docs/GETTING_STARTED.md: says which exports keep step-text formatting. It also corrects an old line that claimed Word, PowerPoint and GIF show the guide description as plain text: Word now keeps its formatting, and PowerPoint and the GIF never showed it.Area
Testing
bash tests/run_test.shpassesbash tests/run_test.shwas not run.npm testpasses: 1,658 tests, 1,632 passed, 0 failed, 26 skipped.tests/e2e/exports.test.js(export through the dialog, including Word) passes on a private Xvfb display; it was run on #325's branch, which contains this one.Checked on Ubuntu 26.04:
mainin every part.The files have not been opened in Microsoft Word or PowerPoint yet.
Screenshots or recordings
The same step exported from
mainand from this branch, rendered by LibreOffice. The step has a bold phrase, inline code, a numbered list, italics, a quote, a link to another step, and a callout with a bulleted list.Word:
PowerPoint:
Rollout notes
None.
Checklist
t(), andnpm run translationslists nothing missing