Conversion defines the stored meaning
The conversion workflow takes HTML, Markdown or another source and constructs Portable Text blocks. Its concerns include unique keys, annotation references, list structure and mappings for custom content. This is the right starting point for an importer or migration. Keeping raw HTML in a string field may appear simpler, but it bypasses the structured representation the target editor expects.
Serialization defines the delivered experience
The rendering workflow maps stored blocks and marks to frontend components or output formats. A missing custom renderer cannot usually be fixed by changing unrelated source conversion. Conversely, a visually pleasing renderer can hide a broken annotation reference in stored content. Diagnose which side of the boundary is responsible before replacing libraries or rewriting the pipeline.
Share fixtures across the boundary
Keep examples with headings, nested lists, internal and external links, images, inline objects and unsupported blocks. Convert them into stored data, validate the structure and then render the exact result. Include long content, absent fields and unusual characters so that the happy-path example does not become the only acceptance test.
Verify structure and visible behavior
Compare semantic meaning as well as appearance. Check escaping and link schemes, accessible HTML and keyboard behavior. For migrations, confirm repeatability and reference integrity before cutover. These are source-based workflow comparisons; the catalog did not install the libraries, execute a migration or certify interoperability for every listed framework. Use the current framework-specific references when implementing the final renderer.
| Task | Starting point | Check before choosing |
|---|---|---|
| HTML or Markdown import | Portable Text conversion | Validate keys and annotation references |
| React, Vue or other frontend output | Portable Text serialization | Use the matching framework reference |
| Missing custom block | Trace storage and renderer separately | Do not silently drop content |
| Migration acceptance | Both workflows with shared fixtures | Check semantic and visual fidelity |