Umbraco 13 to 17 Migration – Rich Text Editor (TinyMCE to Tiptap) HTML Validation Issue

[Nishant.Vaghasiya]

Hi Team,

I recently migrated a website from Umbraco v13 to v17, and I am currently facing an issue related to the Rich Text Editor datatype.

As we know:

• Umbraco v13 uses TinyMCE as the Rich Text Editor.

• Umbraco v17 uses the new Tiptap-based Rich Text Editor.

The main issue I’m facing is related to HTML validation and structure enforcement.

In v13 (TinyMCE):

• There were no strict HTML validation rules.

• It allowed flexible/nested HTML structures.

• Custom markup worked without modification.

In v17 (Tiptap):

• HTML validation rules are enforced.

• The editor automatically restructures the markup.

• It follows proper HTML document structure.

• Some nested structures are modified or split automatically.

Because of this, my existing markup structure is being changed after saving content in v17.

Example:

v13 Rich Text Editor Output:

<h1 class="hero">
  ....
  <span class="d-flex">
    Thinks 
    <a href="#contact-us" class="talk-animation">
      <img src="https://chat-icon_webp.webp" alt="chat-icon">
      <span class="animation-link">
        Connect Now 
        <img src="https://link-arrow.svg" alt="Arrow icon">
      </span>
      <span class="typing-container">
        <span class="typing-dots">
          <span class="dot"></span>
          <span class="dot"></span>
          <span class="dot"></span>
        </span>
      </span>
    </a>
    Ahead
  </span>
</h1>

v17 Rich Text Editor Output (After Save):

<h1 class="hero">
  ....
  <span class="d-flex">Thinks</span>
  <a target=""
     data-router-slot="disabled"
     class="talk-animation"
     href="#contact-us"
     type="external">
     <span class="d-flex">
        <img src="https://chat-icon_webp.webp" alt="chat-icon">
     </span>
     <span class="animation-link">
        Connect Now 
        <img src="https://link-arrow.svg" alt="Arrow icon">
     </span>
  </a>
  <span class="d-flex">Ahead</span>
</h1>
<p></p>

Problem Summary:

• The anchor tag <a> is being moved outside of the wrapping <span>.

• The structure is being split into multiple <span> elements.

• An extra <p></p> is added.

• The custom animation markup structure breaks because of this restructuring.

• This affects frontend layout and styling.

My Questions:

1. Is there a way to relax or customize HTML validation rules in Umbraco 17 Tiptap editor?

2. Can we configure allowed tags / nesting rules?

3. Is there any recommended approach for handling complex custom markup in v17?

4. Should we avoid using RTE for this type of structured markup and instead use a Block/Grid editor?

Environment:

• Migrated from Umbraco 13 → Umbraco 17

• Issue specifically with Rich Text Editor datatype

• Frontend depends on custom nested HTML structure

[huwred]

You could stick with TinyMCE if you wish.

TinyMCE for Umbraco CMS | Umbraco Marketplace

[Nishant.Vaghasiya]

Thank you for your response.

As per my client’s requirement, we need to use the latest Tiptap-based Rich Text Editor in Umbraco 17, so switching back to TinyMCE is unfortunately not an option for us.

I have now resolved the issue locally by creating a custom Tiptap extension to support our required HTML structure. It is working as expected.

I’ve also created a GitHub repository for this solution:

GitHub - NishantArroact/umbraco-custom-rte: A custom Rich Text Editor (RTE) extension for...

Could you please review it and let me know if:

• The approach aligns with best practices for Umbraco 17 / Tiptap
• Any improvements or optimizations are recommended
• There is a better way to handle custom HTML validation in the new RTE

I would really appreciate any feedback or suggestions from the community.

Thank you