The Merge Marker That Didn't Survive the Account Manager's Edit

The master service agreement template looked complete when the account manager opened it: a renewal clause, a liability section, the usual boilerplate framing both. She changed one sentence in the term length, saved the file, and reopened it to check her edit. The comment that told the contract generator where to drop in the renewal clause was gone, and the hidden liability paragraph had vanished with it.

The Clause That Vanished After Save

A solutions engineer built the master service agreement template once, for a contract-generation pipeline. Account managers use that pipeline every time a deal closes. Two things in that template do real work behind the scenes. An HTML comment reading CLAUSE:auto-renewal:v3 marks the exact spot where the generator inserts the auto-renewal clause. A hidden block tagged data-tier="enterprise" holds a liability-cap paragraph, styled with display:none so it never shows on screen. That paragraph only prints when the deal is tagged enterprise. Nothing in the visible editor marks either piece as special. The renewal-clause spot looks like ordinary paragraph text, and the liability section simply isn't there unless the deal happens to be enterprise-tagged.

An account manager opens the template in Synap Editor. She adjusts one sentence of deal-specific wording before it goes to legal. She retypes the sentence, saves, and moves on to the next deal. When she, or anyone else, reopens that file later, the comment is gone. So is the hidden liability block. The template still looks identical on screen, because neither piece was ever visible to begin with.

The cost lands downstream, not in the editor. The generator runs its next pass looking for CLAUSE:auto-renewal:v3 and finds nothing to anchor the renewal clause to. An enterprise deal goes out without its liability cap. Nobody notices until legal asks where the clause went. That's usually after the contract has already gone to the client for signature. By then, the account manager who made the edit has moved on to other deals and has no memory of touching this file at all. Tracing the gap means pulling the save history and checking a field nobody thought to look at before.

Why the Editor Strips What It Doesn't Show

Synap Editor doesn't simply keep whatever HTML was in the file untouched. It rebuilds the document each time it loads content and each time it saves. That rebuild parses the markup into its own internal structure and writes it back out. That rebuild has to decide what each piece of markup is. Either it counts as content, or it is clutter left behind by an earlier export.

An HTML comment carries no visible content. A block set to display:none renders nothing on screen. By the rebuild's default rules, both look like leftovers, markup that isn't part of what a reader actually sees. So neither one is part of what gets written back out. The editor drops them the same way it would drop stray whitespace.

This happens on every load and every save, not once at the start. A template can sit untouched for months without losing anything, because nothing has forced a rebuild yet. The moment someone opens it in the editor, edits a sentence, and saves, the rebuild runs. Anything in it that qualifies as invisible clutter by default disappears from that point on. That holds no matter how many edits it had already survived before. A template built from scratch rarely has either piece to begin with; the risk shows up only on templates that get reused and resaved many times over, like this one.

Telling Synap Editor What Counts as Content

What a fix needs to do is narrow. It has to tell the editor that these particular invisible pieces are not clutter. They are content the pipeline depends on. They should survive the same rebuild that would otherwise drop them.

Synap Editor splits that decision into two independent controls. One tells the rebuild to keep HTML comments exactly as they are. That's the same CLAUSE:auto-renewal:v3 marker that was getting dropped. The other tells it to keep display:none blocks in place, the same hidden liability section tagged data-tier="enterprise".

Because the two are independent, a solutions engineer can turn on only what a given template actually needs. A template built only with hidden conditional blocks, with no comment markers at all, needs just the one. The master service agreement template uses both a merge marker and a hidden clause, so both get turned on. Neither depends on the other being set. Turning one on changes nothing about what happens to the other kind of markup.

Measured against working around the problem by hand, that is what the reader gains. Nobody has to re-insert the marker and the hidden clause into the file after every account manager edit. Nobody has to keep a separate master copy outside the editor to paste the missing pieces back in from either.

The Template That Keeps Its Hidden Instructions

The account manager opens the same master service agreement template, changes the same kind of sentence, and saves. This time, reopening the file shows the comment sitting exactly where it was. CLAUSE:auto-renewal:v3 sits right before the renewal clause paragraph, exactly as before. Below it, the hidden block tagged data-tier="enterprise" is still there too, display:none intact. It's invisible on screen the way it always was.

Nothing about the editing experience changed for her. She never saw the comment or the hidden block before, and she still doesn't see them now. What changed is what happens after she hits save.

The contract-generation pipeline runs its next pass over the file. It finds CLAUSE:auto-renewal:v3 where it expects it and inserts the renewal clause correctly. Because the deal is tagged enterprise, the pipeline also finds the hidden liability-cap paragraph still in place. It prints that paragraph into the final contract, exactly as it would have before anyone touched the file. Legal never sends the follow-up question asking where the renewal clause went, because there is no gap left to explain. The account manager never even learns that a comment and a hidden block exist in the file she edited. The fix works entirely out of her sight, and that is exactly the point.

[[shot: the saved contract template reopened in Synap Editor's source view, showing the CLAUSE:auto-renewal:v3 comment marker and the hidden enterprise liability block both intact after save]].

How to Preserve Comments and Hidden Sections

Both controls live under editor.buildOption.html, set together as one settings object:

// synapeditor.config.js
{
    'editor.buildOption.html': {
        'remainComment': true,
        'remainNoneNode': true
    }
}

remainComment keeps HTML comments through load and save. remainNoneNode keeps display:none blocks in place instead of stripping them. Both default to false on their own, so turning on one does not turn on the other.

See the manual pages for Preserve HTML Comments and Preserve HTML display:none Nodes for version requirements and related settings.

Common questions

If I only turn on remainNoneNode, do my HTML comments still get stripped on save? Yes. remainComment and remainNoneNode are separate settings under editor.buildOption.html, and each defaults to false independently. Turning on remainNoneNode alone preserves display:none blocks only; comments are still stripped unless remainComment is also set to true.

Do these settings preserve comments pasted in from another page, or only ones already in the loaded HTML? The material doesn't cover general copy-paste comment preservation beyond one specific case. What it confirms is narrower: the comment markers that copy/paste itself inserts, StartFragment and EndFragment, are stripped either way, regardless of these settings.

What editor version do I need for each setting? remainComment is available from release 2.13.0 onward. remainNoneNode needs a later release, 2.15.2211 onward.

What happens to a display:none block if I leave remainNoneNode at its default? At its default of false, remainNoneNode removes display:none blocks when the editor loads or saves HTML.