Users need to understand what happens to their workflow mappings when the underlying document blueprint changes.
Blueprints sometimes need remaking — for example, certain block types (synchronised navigation blocks) can only be created on a published page, which means structural changes to the blueprint require rebuilding it from a template. When this happens, every block instance gets a new GUID.
The good news is that UpDoc matches blocks by contentTypeKey (the element type GUID, which is stable) rather than by instance GUID — so remaking a blueprint with the same block types preserves mappings after regenerate-destination. The one edge case is blueprints with duplicate block types, where reconciliation is ambiguous.
Scope:
- New docs page: "Updating Blueprints"
- Covers: how UpDoc identifies blocks, what's safe to change, what needs attention, the duplicate-block-types edge case, the recommended workflow after updating a blueprint
- Slotted into the sidebar after "Creating Documents from Source"
Also:
- Planning note (
planning/DOCS_SCREENSHOT_AUTOMATION.md) capturing a Playwright-driven screenshot automation idea for future work — docs are text-heavy and would benefit from automated screenshot regeneration
Users need to understand what happens to their workflow mappings when the underlying document blueprint changes.
Blueprints sometimes need remaking — for example, certain block types (synchronised navigation blocks) can only be created on a published page, which means structural changes to the blueprint require rebuilding it from a template. When this happens, every block instance gets a new GUID.
The good news is that UpDoc matches blocks by
contentTypeKey(the element type GUID, which is stable) rather than by instance GUID — so remaking a blueprint with the same block types preserves mappings after regenerate-destination. The one edge case is blueprints with duplicate block types, where reconciliation is ambiguous.Scope:
Also:
planning/DOCS_SCREENSHOT_AUTOMATION.md) capturing a Playwright-driven screenshot automation idea for future work — docs are text-heavy and would benefit from automated screenshot regeneration