Single source publishing is one of those phrases that everyone in documentation tooling claims to support. The pitch is clean. Write a topic once and click publish. The same content appears as a web page, a PDF, an in-app tooltip, and a Markdown file in your repo. Most tools quietly compromise. The PDF looks nothing like the web output. Tables overflow the page. Code blocks lose their syntax highlighting. The Markdown export turns your callouts into plain quoted paragraphs. By the time you finish manually fixing each channel, you do not have single source publishing. You have one source plus three manual cleanup workflows.
This article explains what single source publishing requires under the hood. It maps where common tools fall short. Then it gives you a way to tell a real implementation from a marketing claim. The useful part is the failure modes. Those are the specific places where "write once, publish everywhere" stops working under real content.
What single source publishing actually means
Single source publishing is the practice of writing content once in a format-neutral source, then rendering it to multiple output formats without manual intervention between channels. The source describes content semantically: this is a procedure, this is a code sample, this is a warning, this is a cross-reference. The pipeline then knows how to express each of those semantics in HTML, in PDF, in Markdown, or in any other supported channel.
The distinction that matters is between formatting and meaning. A heading in a Word document is bold and larger than the surrounding text. A heading in a single source system is marked as a heading. The bold and the size happen at publish time. They also happen differently per channel. PDF may want a serif font and a chapter rule. The web output may want a sticky anchor and a copy-link button. Markdown just gets ## Heading. The same source, three correct outputs, zero manual reformatting.
Sarah O'Keefe at Scriptorium has written about this for two decades under the broader label of structured content. The principle is older than the web. Separate content from presentation. Store the semantics. Render the appearance. What changed in the last 10 years is the entry cost. The model no longer requires writing DITA XML by hand. Modern CCMS tools, including Topicary, keep the semantic model under the hood and give writers a normal editor on top.
Single source vs multi-source publishing
| Dimension | Single source | Multi-source |
|---|---|---|
| Source of truth | One canonical source per topic | Separate files per output channel |
| Update cost | Edit once, republish all channels | Edit each copy independently — drift is inevitable |
| Consistency | Guaranteed by the pipeline — outputs match by construction | Depends on manual discipline across writers and channels |
| Setup cost | Higher — requires semantic markup and format-aware renderers | Lower initially — copy and paste is fast until it is not |
The four technical requirements
Real single source publishing requires four things, and a tool that skips any of them forces manual work somewhere in the pipeline. The four are semantic structure, format-aware renderers, conditional logic, and variable substitution. Structure separates content from presentation, and renderers handle each output's quirks. Conditions cover variant content. Variables cover context-specific values. Each one addresses a failure mode that shows up when you ship the same content across channels.
Semantic structure. The source must mark content by what it means, not how it looks. A note is a <note> or a Callout component, not a paragraph in a colored box. A code sample is a code block with a language attribute, not a monospaced paragraph. A cross-reference is a typed link to a topic, not an HTML anchor with a hardcoded URL. This is the foundation. Without it, nothing else works. The renderer has no semantics to reason about.
Format-aware rendering. Each output channel has its own constraints. PDF has fixed page widths, page breaks, headers and footers, and a typesetting model that descends from print. Web has reflowable text, interactive elements, and JavaScript. Markdown has a smaller vocabulary than either, with no callouts, no tabs, and no rich tables in CommonMark. A single source publishing pipeline needs format-specific renderers. Each renderer translates the semantic source into the idiom of its channel. It also degrades gracefully when the target format cannot represent something natively.
Conditional content. The same source routinely needs to appear differently for different audiences or platforms. A setup guide for Linux, macOS, and Windows shares 80 percent of its content. The rest has to vary. A user manual ships to free-tier and enterprise customers, and enterprise features must appear for one group only. Conditional content tags blocks with metadata (os="linux", plan="enterprise"). The publishing pipeline filters at output time. Without conditions, audience-specific variation forces you back into multiple maintained copies.
Variables. Product names change. Version numbers change. Support email addresses change. A variable lets the source say "the API supports requests per second". The tokens resolve at publish time. The same variable set can produce a free-tier output and an enterprise-tier output from one source. This is the layer below conditions. Conditions decide whether a block appears at all. Variables decide what appears inside the blocks that survived.
A tool that ships all four cleanly delivers what it advertises. A tool that ships three of the four pushes the missing piece onto the writer. That is how teams end up running parallel content workflows inside a "single source" tool.
Where most tools fall short
The most common failure modes show up not in the marketing pages but in real content with tables, code, conditions, and PDF output. Architecture predicts the failure mode. HTML-first tools tend to break on PDF, and Markdown-first tools tend to break on rich content. Wiki-first tools tend to break on conditions. Knowing the pattern tells you where a given tool will hurt before you commit to it.
PDF rendering breaks. Most web-first documentation tools generate PDF by printing HTML through a headless browser. That works for simple text. It falls apart on real content. Wide code blocks overflow the page or wrap awkwardly mid-token. Tables with more than four columns collapse or split across pages mid-row. Long ordered lists lose their numbering across page breaks. Syntax highlighting gets stripped, or rendered in web-only palettes that are illegible in print. The CSS Paged Media specification at W3C covers what should work in theory. Real PDF output needs a pipeline that was designed for print, not HTML reflowed onto pages.
Markdown export drops semantics. A tool supports custom callouts, tabbed code groups, conditional blocks, and cross-references in its editor. Then it exports Markdown missing all of them. Callouts become indented paragraphs. Tabs become a single concatenated code block. Conditions either disappear or get flattened to the default variant. Cross-references become bare anchor links that may or may not resolve in the consuming environment. The exported Markdown is technically valid but semantically lossy. Round-tripping it back into the source loses information.
Conditional content does not actually filter. A handful of tools accept condition tags in the editor. Then they apply them at the viewer layer only, never at publish. The resulting PDF contains every variant — enterprise content visible to free-tier readers, Linux content visible to Windows users. Others apply conditions only to one output and not the others. The test is simple. Export the same map twice with different condition profiles. Verify that the outputs differ in the right places. Tools that pass this test reliably are the minority.
Variable substitution is inconsistent. Variables work in the web output but appear as raw {{tokens}} in the PDF. Or they work in PDF but not in Markdown. Or they work everywhere but cannot be overridden per output target. That rules out one variable set for the free-tier docs and another for enterprise. Real single source publishing needs substitution that runs in every channel. Values must also scope to specific publication targets.
Cross-references break across formats. A link to another topic should resolve differently in each format. A URL in the web output, a page number in the PDF, and a relative path in the Markdown. Three out of four tools handle one of these and degrade the others. Most commonly the PDF loses its page numbers. The reader gets "see Configuring SSO" with no indication of where to look. Topic-to-topic linking in structured authoring without XML is supposed to abstract this. It only works if the publishing pipeline resolves the link per channel.
A practical evaluation checklist
To evaluate whether a tool delivers real single source publishing, run five tests against your own content. Skip vendor demos. Take a topic that exercises tables, code, conditions, variables, and cross-references. Publish it through every channel the tool supports. The failures will show up within an hour.
-
Render the same topic to web and PDF, side by side. Compare them at the level of tables, code blocks, lists, callouts, and headings. If the PDF has defects the web version does not, the pipeline was bolted on, not designed in.
-
Export to Markdown and re-import. A clean round trip is rare and is a strong signal. If the re-imported topic differs from the original — missing callouts, flattened tabs, lost conditions — the Markdown layer is lossy. That is acceptable if Markdown only feeds AI agents or static-site consumption. It is fatal if you intended Markdown as a peer output channel.
-
Apply conditional content and publish both variants. Tag a paragraph with a condition. Publish once with the condition active and once with it inactive. Verify both outputs differ in the right place and only in the right place. Then publish to every channel and verify the filtering applies in each.
-
Substitute variables across all formats. Define a variable and reference it in body text and in a heading. Publish to web, PDF, and Markdown. The variable should resolve in all three. If it resolves in the editor preview but not in the PDF, the rendering pipeline is not variable-aware.
-
Stress-test with hard content. Wide tables, long code blocks, deeply nested lists, mathematical expressions if you use them, images with captions, footnotes, sidebar callouts. Push the source to the edge of what a documentation team actually writes. The places that break are the places you will fight forever.
This checklist is also useful as a procurement filter. Tools that pass all five with your real content are candidates. Tools that pass on curated demo content but fail on yours are priced on marketing, not capability.
When single source publishing matters (and when it does not)
Single source publishing matters when you publish the same content across multiple channels with high consistency requirements — developer docs that ship as a help center, a downloadable PDF, and embedded in-app help; regulated documentation that needs audit trails across formats; multi-product docs with shared sections across product lines. The alternative is maintaining the same content in multiple places. That degrades quickly. Most teams discover this around 100 topics and 2 output formats.
It matters less when you publish to one channel only. A blog has one output. A SaaS app's internal wiki has one output. A README in a repo has one output. For these, a structured authoring tool is overhead. A Markdown file and a renderer are enough. The question is simple. Do you publish the same content in more than one place, or is each output a fundamentally different work product? If the latter, single source is the wrong frame.
It matters most when your team has more than 2 writers and more than 100 topics. Below that scale, manual coordination across channels is faster than learning a structured tool. Above it, the manual cost grows faster than linearly. Every new channel multiplies the maintenance burden. Every new topic adds N copies to the inventory if you support N channels. The break-even point is where the cost of drift exceeds the cost of the tool. For most documentation teams, that point sits between 100 and 300 topics. Content reuse at scale is the foundation that makes single source publishing pay off. The same components feed every channel. Reuse multiplies through publishing as well as within the source.
What Topicary does differently
Topicary is built around single source publishing as a primary use case. Maps compile to web, PDF, and Markdown from the same source. Components render the same way in every channel. The publishing pipeline applies the same semantic conversions before the format-specific renderers run. Conditions filter at publish time and apply to every output target. Variables resolve in every format, with per-target overrides for audience-specific values.
The PDF pipeline runs through a print-optimized template. A generic HTML-to-PDF dump is not the same thing. Tables paginate correctly, code blocks wrap inside their grid, and chapter numbering survives across page breaks. Markdown export preserves callouts, tabs, and cross-references through custom syntax. That syntax round-trips back into the source without information loss. The five tests above were used as the design criteria, not as marketing claims after the fact.
Suppose your documentation team has outgrown a wiki or a Markdown-only platform. The thing to test is whether single source publishing holds up under your real content, not the vendor's. Topicary's seven import formats exist to make that test cheap to run with your actual topics, not just a writing sample.
Frequently asked questions
What is single source publishing? Single source publishing is the practice of writing content once and rendering it to multiple output formats — typically web, PDF, and Markdown — without manual reformatting between channels.
What is the difference between single source publishing and single source authoring? Single source authoring is the discipline of maintaining one canonical version at write time. Single source publishing is the output-time mechanism that takes that one source and produces multiple correct outputs.
Do I need structured authoring to do single source publishing? In practice, yes. Plain Markdown is too narrow, and freeform documents like Word do not carry enough semantic information for a publishing pipeline to render them correctly across formats.
What are common single source publishing tools? CCMS platforms (Paligo, Heretto, MadCap Flare, Topicary), DITA toolchains, and structured static site generators with PDF pipelines (Sphinx, Antora) are the main categories.
When does single source publishing stop being worth the overhead? When you publish to one channel only, or when each output is a fundamentally different document rather than the same content in different formats. Below 100 topics or 2 channels, manual coordination is usually faster than tool adoption.