Experiment: Add Gutenberg-compatible custom field placeholders for post content.

[cbravobernal]

Summary

As a user, I want to reference custom field values directly
inside Gutenberg content using a token syntax like
[[my_custom_key]], so the field value is rendered inline in
paragraphs or other supported blocks.

User story

As a user, I want to be able to create custom fields on a post
and reference them in post content by writing [[my_custom_key]],
so I can reuse custom field values dynamically inside the editor
and on the frontend.

Problem

Users can create custom fields for posts, but they cannot easily
insert those values into Gutenberg content without manually
duplicating content or building custom blocks/templates.

A token-based approach would let users reference field values
inline while keeping the source of truth in the custom field
itself.

Proposed behavior

Support placeholder tokens in post content using this format:

  [[my_custom_key]]

When content is rendered, the token should be replaced with the
corresponding custom field value for the current post.

This should work in Gutenberg content, including inline usage
inside paragraph blocks and other compatible content areas.

Functional requirements

• Allow users to reference any post-level custom field using
  [[field_key]] syntax.
• Support usage inside Gutenberg-authored content.
• Render the referenced field value inline within supported
  blocks, including paragraph content.
• If a referenced field has no value:
  • do not display anything by default, or
  • provide a setting/option that lets the user choose whether
    to show or hide empty output.
• The feature must degrade safely if:
  • the field does not exist
  • the field value is empty
  • the placeholder is malformed

Content and formatting requirements

• Allow safe inline HTML from the field value so formatting such
  as:
  • bold
  • italic
  • other permitted inline markup
    can be rendered.
• Invalid or malformed HTML in field values must not crash
  rendering or break the editor/frontend.
• Output must be sanitized according to WordPress core standards.

Compatibility requirements

• Must be Gutenberg compatible.
• Must follow WordPress core development standards and plugin
  best practices.
• Content must remain persisted in post content if the plugin is
  deactivated.
• Plugin deactivation must not corrupt or remove saved post
  content.
• If the plugin is deactivated, the raw placeholder text should
  remain in content unless an alternative fallback behavior is
  intentionally designed.

Acceptance criteria

• Users can type [[my_custom_key]] into Gutenberg content.
• On render, the placeholder is replaced with the matching custom
  field value for the current post.
• Placeholder replacement works inside paragraph blocks.
• Placeholder replacement works in other supported text-based
  content blocks.
• Empty or missing field values do not produce PHP errors, JS
  errors, or broken markup.
• Empty output is hidden by default, or a user-facing option
  exists to control whether empty output is shown/hidden.
• Safe formatting HTML in field values is preserved where
  allowed.
• Unsafe or malformed HTML is sanitized and does not crash
  rendering.
• Deactivating the plugin does not remove or corrupt saved post
  content.
• Implementation follows WordPress core coding, sanitization,
  escaping, and Gutenberg compatibility standards.

Out of scope

• A templating language beyond simple [[field_key]] replacement
• Cross-post or cross-object field references
• Advanced conditional logic beyond empty-value handling
• Full arbitrary HTML support without sanitization

Open questions

• Should placeholder replacement happen:
  • only on frontend render,
  • in the editor preview as well,
  • or both?
• Should users be able to insert placeholders through a UI
  picker, or only manually by typing?
• Should empty-value behavior be:
  • global,
  • per placeholder,
  • or per block?
• Which HTML tags should be allowed in rendered field output?
• Should this support only text-like field values initially, or
  also formatted/WYSIWYG fields?