Knowledge Article Staging Tool
Approved Word drafts needed manual HTML cleanup before staging in Salesforce Knowledge, a content system edited through raw source code, not a WYSIWYG editor.
This single-file browser tool converts approved Word content into Salesforce-ready HTML with a live preview and validation panel. A typical article’s staging pass dropped from 30–60 minutes to about 15, and what remains is verification, not formatting.
Last updated: 2026-08-04. What changed: Name updated; baseline restated; agent-failure specifics, known limitations, and maintenance added.
| Role | Sole builder and maintainer, within the knowledge team |
|---|---|
| Internal name | KM HTML Converter (the GitHub repo name) |
| Scope | SME-approved Word document → Salesforce Knowledge-ready HTML |
| Adoption | All 9 team members use it; a 5-person testing group supplies the reported numbers (4 pilot-era writers + one mid-July 2026 hire) |
| Timeline | Built as a one-day pilot, June 5, 2026; refined through ongoing use |
| Tools | Single-file, dependency-free browser tool (no framework, no libraries, no install) |
| Deliverables | HTML converter with live preview + pre-publication validation panel |
| Status | In active use, documented step in the staging workflow |
Where it sits in the flow
Originally built for the Copilot workflow; architecturally compatible with either pipeline’s approved output, though team use to date has been through Copilot.
The tool only ever intakes content that’s already SME-approved. The team owns staging (preparing articles for publication), not publishing itself.
Drafting and formatting are one lifecycle stage, split across two agents only because one agent couldn’t do both roles.
The problem
What writers did by hand
Pasting Word content directly into the CCMS carries its formatting with it, and none of it matches the destination.
- Stripped Word markup.
- Rebuilt lists and tables.
- Reapplied styles.
- Redid the horizontal dividers between sections.
- Cross-checked editor, source, and preview views by hand.
Each fix is minuscule alone; together they consumed the time meant for quality.
The team had already tried the obvious alternative, the generic Word2HTML web converter. It still required hand-editing the output to reach the team’s CCMS conventions.
What the manual pass cost
- Time per article. The manual pass typically took 30–60 minutes per article, and up to 3 hours on complex documents with nested lists, tables, code snippets, and callouts (team-reported; no time logs).
- Uneven burden. The burden fell hardest on teammates without HTML fluency.
The layout itself was never negotiable. How a guide looks is part of the reader’s experience, and it determines whether a user spots a warning before acting.
Business impact and value delivered
The tool's value is time returned on every article the team stages, and publication defects caught before they ship instead of after.
- Time returned per article. A typical article's staging pass dropped from 30 to 60 minutes to about 15, and complex multi-section documents that previously took up to 3 hours follow the same pattern. The formatting portion collapses to minutes; what remains is verification, not formatting. Team-reported, with no time logs, which is why both times are stated rather than a ratio.
- Full adoption. All 9 members of the knowledge team use it, and it is a documented step in the staging workflow. Adoption is the strongest evidence the tool clears a real cost.
- Defects stopped before publication. The validation panel and live preview surface problems while the writer can still fix them. One documented save: A repeating table header and a stray horizontal rule caught pre-publish. Verification by preview replaces trust in a converter.
- The skill barrier removed. Writers with no HTML background stage articles in a CCMS that is edited through raw source code, without hand-editing markup. Staging capacity is no longer limited to whoever is comfortable in HTML.
- Near-zero operating cost. A single dependency-free file that runs in the browser: Nothing to install, license, or host, and the source is shared with the team.
Claim limit: The times are team-reported estimates for typical articles. No ratio is claimed, and the remaining verification pass stays with the writer by design.
Constraints
- Approved input only. Input is always an SME-approved Word document, never raw or unreviewed source.
- Exact conventions. Output must match exact CCMS conventions (heading levels, table styles, list markers) that generic cleaners can’t produce.
- Invisible defects. Markup defects are invisible in a way prose defects aren’t. A dropped list level renders as subtly wrong, not obviously broken.
- Raw-source editing. The destination system is edited through raw HTML source, so verification means reading markup by eye unless a preview exists.
- Source variance is real. Content copied from web Word behaves differently from desktop Word, and the tool has to handle both.
- No dependencies. No framework, install, license, or token dependency (every article passes through this stage, so it has to be durable).
The approach
Three-step guided workflow: Paste the Word draft, review the cleaned HTML against a rendered preview side by side, copy the final HTML into Salesforce.
What it standardizes deterministically
- Section headings to
<h2>. - Nested lists rebuilt from Word’s
mso-listmetadata rather than read as flat paragraphs. - Fixed marker hierarchies to seven levels (disc/circle/square; 1./a./i.).
- Table styling (
#E8F9FFheader background,0.5pxborders) applied the same way regardless of what Word sends in. - Horizontal dividers before section headings.
- Callout keywords (Note, Important, Warning) formatted to convention.
- Code-shaped content rendered in monospace.
What still needs a human
- Wrong heading levels.
- Restarted list numbering.
- Table cells miscast as headings.
- Hyperlinks altered by the link toggle.
The validation panel and preview surface these known risk points as checkpoints, not defects the tool claims to prevent blindly.
System in action: Why conversion couldn’t be an agent
Word doesn’t paste lists as lists. It emits flat paragraphs with the nesting encoded only as metadata (mso-list:l0 level1 vs. level2).
What Word actually pastes for a two-level list (representative sample, not a live capture)
<p class=MsoListParagraphCxSpFirst style='mso-list:l0 level1 lfo1'>Open the settings panel</p>
<p class=MsoListParagraphCxSpMiddle style='mso-list:l0 level2 lfo1'>Select the account tab</p>
<p class=MsoListParagraphCxSpLast style='mso-list:l0 level1 lfo1'>Save and close</p>No <ul>, no <li> anywhere. Word encodes the hierarchy as a number buried in a style attribute, and the bullet characters are literal text.
A real before/after capture from a production document will be added as it becomes available.
What an agent produced: Plausible, and wrong
<ul>
<li>Open the settings panel</li>
<li>Select the account tab</li>
<li>Save and close</li>
</ul>Clean, valid, and it silently flattens a two-level list into one. The level2 item becomes a sibling instead of a child.
In a procedure, that turns a sub-step into a separate step: A meaning change, not a formatting one. It looks correct until rendered.
What the tool produces: Reconstructed from the level metadata
<ul>
<li>Open the settings panel
<ul><li>Select the account tab</li></ul>
</li>
<li>Save and close</li>
</ul>Same result every time, because it follows a rule instead of an impression. Nested lists build inside the parent li, up to seven levels (though deep nesting is discouraged by convention as harder to read and likelier to convert incorrectly).
What the conversion agent actually got wrong in testing
- Missed required formatting (warning text that renders in red, section dividers).
- Got heading hierarchy wrong.
- Bolded and italicized the wrong spans.
- Dropped hyperlinks.
- Failed to recognize code snippets.
- Missed block quotes.
The decisive defect was non-determinism. Each run produced a different set of errors from the same class of input, so every output required a full audit, and no prior run told you what to check.
Correcting the agent cost about as much as converting by hand.
The realization: This is a logic problem, not an intelligence problem
- Map the source heading and font size to a heading level.
- Preserve existing emphasis.
- Preserve nested-list order.
- Monospace the code-shaped blocks.
- Insert a divider before each section.
It doesn’t need elaborate intelligence to execute that.
Why the preview makes it safe
The rendered preview is what makes the tool safe in practice. A writer doesn’t have to notice a missing nesting level in markup, because the preview shows an indented sub-step or it doesn’t.
Key decisions
Killed the third agent, built a tool instead
Two reasons.
- First. The conversion agent hallucinated in a way that relocated work rather than removing it. Correcting its output took nearly as long as converting by hand, and that burden fell on the writers least equipped to catch it.
- Second, and more decisive. The pipeline was never continuous at this stage. Author review and SME validation are human gates before conversion, so every invocation is a cold start on an already-approved document, and there’s no ambiguity left for an agent’s judgment to resolve.
Consequence Conversion became a deterministic browser tool; the agent idea’s most valuable piece, a strict input contract, survived in the tool’s expectations.
Verification by preview, not by trust
A rendered preview beside the cleaned HTML means a writer confirms output instead of believing it.
Consequence The audit burden an unreliable agent would have pushed downstream disappears instead of relocating.
How the pivot was communicated
We tested the agent idea and mapped the failure points:
- Too many edge cases.
- Too much variance.
- Low trust.
So I pivoted to a deterministic converter: It kept the value and removed the risk. Framed that way, no one pushed back.
The argument was made from mapped failure points, not preference.
Results
A typical article’s staging pass dropped from 30–60 minutes to about 15.
- The mechanical part. The formatting portion, the strip-rebuild-restyle work, collapses to minutes.
- Judgment stays human. What remains is verification against the source, which is judgment the tool deliberately leaves with the writer.
- The worst case before. Complex multi-section documents previously ran up to 3 hours.
- Full team adoption. All 9 team members use the tool.
- Team-reported. The 5-person testing group is the source of the reported numbers.
Figures are team-reported and typical/median, since a few complex documents would otherwise skew the average upward; no ratio is claimed.
During staging, the preview surfaced a repeating table header and a stray horizontal rule before the first heading. Both would have broken formatting in Salesforce.
Fixed pre-publish; a messy post-publication rollback avoided.
Paraphrase, not a captured quote. The final stretch before publishing was the tedious part (not the research, the staging), and it scaled sharply with article type and length.
The tool took that off their plates, freeing time already stretched across SME follow-up, drafting, and screenshots.
Known limitations
Known limitations: Consistent, not infallible
The tool is consistent, not infallible, and the preview is what surfaces the edge cases. Named plainly:
- Mixed nested lists. Complex mixed nested lists (numbered and bulleted markers interleaved at depth) don’t always reconstruct correctly.
- Merged table cells. Tables with merged cells break the uniform rows-and-columns assumption.
- Intake field loss. Some pasted content doesn’t survive the intake field intact.
- Rich-text intake gaps. Rich-text intake doesn’t always carry every piece of source formatting.
Maintenance
How the tool is shipped and shared
- It ships with a built-in usage guide.
- The source is shared with the team.
- The build is deliberately a single file, so anyone can copy, run, or fork it without dependencies.
No one else has yet modified or extended it. Maintenance is currently one person.
What changed after testing
- Abandoned the three-agent plan. The conversion agent’s non-deterministic errors proved too costly to verify.
- Replaced “an agent that’s usually right.” A rendered preview and validation panel a writer can trust without auditing line by line took its place.
- Kept the tool dependency-free. No framework, install, or license, so it survives platform and license changes that affected the agent-based stages.
- Hardened against source variance. The gap was between web Word and desktop Word paste behavior.
- Added format detection. Code snippets, block quotes, and callout keywords now get detected, since drafts did not always format them as expected.
Reflection
If I built this again, two things would change:
- Instrument the staging workflow from day one. The technical outcome was measured, but baseline timings and before/after examples weren’t captured during active use, which forced reconstructing estimates later.
- Validate the simplest solution earlier. The AI agent was explored first because it seemed more capable, but testing showed the bottleneck was deterministic conversion.
The lesson this project cemented, carried into the governance work that followed: Prove where intelligence is actually needed before introducing AI.
Limitations and next step
What isn’t documented yet
- A real captured before/after, rather than the representative sample above.
- The validation panel’s exact severity rules (error vs. warning vs. info).
Next: Capture real examples and confirm the rules
- Capture a real conversion example from production.
- Confirm the panel’s severity logic against actual use.
- Add a table-based before/after (tables are the other high-risk conversion case).
- Get 2–3 written teammate confirmations of the baseline.
Supporting artifacts
Sanitized before/after samples and the usage guide will be added as they become available. The converter demo and its source are linked above.