Skip to content

Keep step text formatting in Word and PowerPoint exports - #324

Merged
Twest2 merged 2 commits into
mainfrom
fix/rich-text-word-pptx
Nov 17, 2026
Merged

Twest2 merged 2 commits into
mainfrom
fix/rich-text-word-pptx

Conversation

@Twest2

@Twest2 Twest2 commented Nov 17, 2026 •

Copy link
Copy Markdown
Owner

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:

  • Bold, italics, strikethrough and inline code came out as plain text.
  • Links (to web pages and to other steps) became plain words.
  • A numbered list came out as bullets.
  • A quote ran straight into the next sentence ("…stops working at once.Go back to…").

PDF, HTML, Markdown, Confluence and Wiki.js already kept all of this.

Now Word and PowerPoint keep it too, in descriptions and in callouts:

  • Word: bold, italic, strikethrough, inline code, web links and links to another step's heading, real numbered and bulleted lists, quotes, headings and tables. Inside a callout, a list is written as "•" and "1." lines, because an indented list would push the callout's colored border inward.
  • PowerPoint: the same formatting, with real slide bullets and numbering. A web link opens its page, and a link to another step jumps to that step's slide. Text split onto a "(continued)" slide keeps its formatting on both halves.

Changes

  • exporters/word-rich.js (new): the Confluence exporter's rich-text renderer, moved out so Word can share it.
    • In "styled" mode (Confluence) it refers to the List Paragraph, Quote, Heading 4 and Hyperlink styles, exactly as before. Confluence's output is byte-for-byte unchanged: I compared every part of an export with rich text before and after.
    • Word doesn't define those styles, so in its mode formatting is written on each run and paragraph. Bullets use a plain "•" that every font has; Word's usual Symbol-font bullet shows as a stray glyph wherever Symbol is missing.
  • exporters/confluence-word.js: uses the shared module.
  • exporters/docx.js:
    • Descriptions, the guide description on the cover, and callout text go through the shared renderer, with hyperlink relationships and a numbering part added when needed.
    • A callout is its label paragraph plus its text paragraphs, all sharing one border and shading, so Word draws a single box. The box has space after it, not between its paragraphs.
    • The keep-together logic now covers every paragraph of a multi-paragraph block that fits on a page. A block too tall to keep together can still break between its paragraphs, as before.
  • 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.js and exporters/pptx-xml.js:
    • Formatted runs, list bullets and numbering, quotes, and tables inside descriptions.
    • Links collected per slide. Step links are resolved to slide numbers when the deck is assembled.
    • List indents and mostly-bold text are allowed for when measuring the layout.
  • Tests:
    • tests/unit/rich-text-exports.test.js (new) covers:
      • Word: each kind of formatting, both kinds of link with their targets, real numbered and bulleted lists with the numbering part, the callout box, and the cover description.
      • PowerPoint: formatting, bullets and numbering, the web link, and the step link jumping to the right slide.
      • Formatting kept across a "(continued)" split.
      • The text helpers, and the Confluence (styled) form.
    • 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 (pBdr before shd). The old order was the other way round.
    • exporters-binary, branding and pptx-layout tests:
      • Relationship checks skip web links, which point outside the package.
      • The PowerPoint text helper joins a paragraph's runs without spaces.
  • 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

  • Exports
  • Documentation
  • Tests

Testing

  • bash tests/run_test.sh passes
  • Tested manually (described below)

bash tests/run_test.sh was not run. npm test passes: 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:

  • LibreOffice 26.2 opens both files, and they render as shown below.
  • In the PowerPoint file, python-pptx 1.0 reports the web link's address and a slide jump for the step link, which points at step 1's slide.
  • Confluence: the export with rich text is byte-identical to main in every part.

The files have not been opened in Microsoft Word or PowerPoint yet.

Screenshots or recordings

The same step exported from main and 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:

Before After
before after

PowerPoint:

Before After
before after

Rollout notes

None.

Checklist

  • Linked to an issue above
  • Scope is limited to that issue
  • New behavior has tests that check real output
  • Docs updated for anything users will notice
  • New interface text is in t(), and npm run translations lists nothing missing
  • Anything that still needs manual verification is listed above
  • No new network calls, dependencies, or third-party branding
  • Follow-up work is tracked in an issue

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.
@Twest2

Twest2 commented Nov 17, 2026

Copy link
Copy Markdown
Owner Author

@codex review

@chatgpt-codex-connector

chatgpt-codex-connector Bot commented Nov 17, 2026 •

Copy link
Copy Markdown
Codex Review Summary: ✅ Completed

This comment shows the latest Codex review activity on this pull request.

Review Status Commit Review trigger
📝 Code Review ✅ Completed 2026-11-17T19:13:42.816910Z 3d9311e Manual request
ℹ️ 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" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 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".

Comment thread exporters/pptx.js Outdated
Comment on lines +273 to +274
const head = sliceRuns(item.runs, 0, parts[0].length);
const tail = sliceRuns(item.runs, item.text.length - parts[1].length);

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge 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 👍 / 👎.

Copy link
Copy Markdown
Owner Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Comment thread exporters/pptx.js
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 });

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge 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 👍 / 👎.

Copy link
Copy Markdown
Owner Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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 &.

Comment thread exporters/pptx-text.js Outdated
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,

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge 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 👍 / 👎.

Copy link
Copy Markdown
Owner Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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&amp;b=2" links to "?a=1&b=2"
  instead of "?a=1&amp;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.
@Twest2
Twest2 merged commit 4a32d4b into main Nov 17, 2026
9 of 10 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant