Undermark documentation

Get started

Install Undermark from the Atlassian Marketplace (Confluence admin). Every site gets a 30-day free trial. After that it is $8 a month for up to 10 users, then billed per user.
Open any published page or blog post, click ••• (More actions) and choose Edit source. The editor opens full size on that page.
Or click Source in the page byline. The popup shows the current version and the size of the storage format. Click Edit source to open the same editor.
Space admins: open Space settings and choose Source editor for the Templates and Find and replace tabs.
Confluence admins: open Confluence administration and choose Source editor for the Access, Global templates and Activity tabs.

Nothing is saved until you click Review and save and confirm. Every save is a new page version, so the previous version is always in the page history.

The source editor

The top bar shows the page title, the version you opened and its size.

Storage (XHTML) and ADF (JSON): switch between the two formats. Undermark remembers the format you used last. Switching with unsaved changes asks you first (Discard and switch).
Source: the editor, with syntax highlighting, line numbers, code folding and search (Ctrl/Cmd+F).
Changes: your edits compared with the version you opened, line by line. A dot after Changes means you have unsaved edits.
History: page versions (see below).
Format: puts each block on its own line so the source is easier to read. Formatting alone never creates a new version: if the only difference is layout whitespace, there is nothing to save.
Review and save (or Ctrl/Cmd+S): compares your source with the current version and opens the save dialog.
Close: asks before discarding unsaved changes (Close without saving).

The status bar at the bottom shows ✓ Valid storage format (or ✓ Valid ADF), or the number of errors and the first one, plus any warnings.

Storage format or ADF?

Storage (XHTML) is the XHTML Confluence stores for a page, with ac: and ri: tags for macros, links and attachments. It is the format to use for macro parameters, Jira queries, layouts and tables.
ADF (JSON) is the format pages made in the current Confluence editor are stored in. Editing ADF directly means Confluence does not have to convert your edit, so nothing is reformatted on the way in.

When you save storage format on a page made in the current editor, Confluence converts it and may drop anything it can't represent. If a page looks different after a storage save, edit it as ADF instead, or restore the previous version from History.

Validation

Undermark checks the source as you type. Problems are underlined in the editor and marked in the gutter; hover for the message.

Storage format errors include tags that are never closed, mismatched or stray closing tags (with the name of the open tag), a bare & in text or attributes, attribute values without quotes or without a closing quote, attributes with no value, unterminated comments or CDATA sections, and macros without a name.

ADF errors include JSON syntax mistakes (such as a missing or trailing comma or single quotes) with the exact line, a root that is not {"type": "doc", "version": 1, "content": [...]}, and broken text, heading, link and mark nodes, with the path to the node.

Warnings never block a save. They tell you about things Confluence will remove or may drop, such as <script> tags, event attributes like onclick, unknown namespaces, and unknown ADF node or mark types.

Source with errors is never saved. Review and save shows the first error and the save button stays disabled until you fix it.

Review and save

The Review and save dialog shows a line-by-line diff of what saving would change compared with the current version of the page, which may be newer than the one you opened.

Note for the page history: optional (up to 200 characters), or required if your admin asks for one. Your note appears in the page history followed by "(Undermark)". Without a note, the version says "Edited in source with Undermark".
Save as version N: saves your source as one new version, as you.
Back to editing: closes the dialog without saving.

After a save you see "Saved as version N" with the number of lines added and removed, and a Reload the page link to see the result.

If someone else saved while you were editing

If a colleague saved a newer version after you opened the page, the dialog says so and the diff is against their version: lines marked - would be lost. Copy what you need from the diff, or click Save on top of version N if replacing their version is what you want. Undermark never overwrites a newer version without this step.

If Confluence refuses the save

Confluence runs its own checks when a page is saved, for example on unknown macro names or link targets. If it rejects the source you see "Confluence refused the save:" followed by Confluence's message, and nothing is saved.

Version history and restore

Open the History tab to see the page's most recent versions with Version, When, By and Note. The version you have open is marked current.

Click a version to see its source compared with the current version. Then:

Load into editor: puts that version's source in the editor without saving, so you can copy from it or edit it before saving.
Restore this version: after you confirm, saves that version's content as a new version with the note "Restored version N with Undermark". Nothing in the page history is deleted.

Restore uses the format you have selected (storage format or ADF).

Page templates

Templates have no version history in Confluence, so Undermark keeps backups for you.

Space templates: Space settings > Source editor > Templates lists the page templates of that space. Space admins can open and edit them. Other people see the list only, without View source or Edit source buttons.
Global templates: Confluence administration > Source editor > Global templates lists site-wide page templates. Confluence admins can edit them. Space templates are edited from each space's settings.

Click Edit source next to a template to open it in storage format. The editor validates as you type, and Format works the same as for pages. Click Review and save to see the diff, then Save template. Back to templates returns to the list.

Every template save keeps the previous text under Backups (the last 10). For each backup:

Compare: shows the backup against the current template.
Restore: after you confirm, puts the backup back. The current text is backed up first.

If someone changed the template after you opened it, the save dialog tells you to copy your edits and reopen the template. A template save never overwrites someone else's change.

Find and replace across a space

Space settings > Source editor > Find and replace searches every published page and blog post in the space. It is for space admins.

Fill in Find and Replace with.
Choose a scope:
- Page text only (safe: tags, links and macro settings are never touched): the default. Only the text people read changes, plus the content of code blocks. Link targets, macro parameters and task ids are left alone.
- Whole source (macro parameters, link targets, attributes): matches anywhere in the storage format, for example a Jira query in every Jira macro. Pages whose result would not be valid storage format are skipped.
Options: Match case, Whole words, and Regular expression ($1 in the replacement inserts a group).
Click Dry run. Undermark scans the space and shows "Scanned N pages" as it goes; click Stop to end the scan early. Nothing is changed by a dry run.

The results list each matching page with the number of matches and an example of the change. Click Preview to see the full diff for one page. Untick any page you want to leave out (or use Select all). Pages that can't be changed safely show the reason and can't be ticked.

Click Replace N in N pages and confirm. Each page gets one new version with the note "Find and replace with Undermark" followed by the search and replacement. Results shows how many pages were saved, skipped or failed, with the reason for each. A page edited since the dry run is skipped ("Edited since the dry run"); run the dry run again to include it.

Undo a replace

Recent replace jobs lists the last replace jobs in the space with the search, the replacement, the scope and how many changes and pages it touched. Click Undo and confirm to put every page back as it was before the replace, as a new version ("Undid find and replace with Undermark"). Pages someone edited after the replace are left alone and reported; use those pages' version history instead.

Admin settings

Confluence admins open Confluence administration > Source editor.

Access

Under Who can use the source editor:

Everyone who can edit the page: the default.
Only members of these groups (Confluence admins always can): search for a group and click Add followed by its name. Repeat for each group. You need at least one group.

Under Features:

Allow editing ADF (JSON) as well as storage format
Allow editing page templates (space admins for space templates, Confluence admins for global ones)
Allow space admins to run find and replace across their space
Require a note for the page history on every save

All four feature switches start on, except the required note. Click Save. Changes apply the next time someone opens the source editor.

These settings can only narrow access. Confluence permissions always apply on top: people can only change pages and templates they can already edit in Confluence. Group limits and feature switches are enforced on the server for every save, not only hidden in the interface. Confluence admins are never locked out.

People outside the allowed groups can still open the editor and read the source. The editor tells them their admin has limited it and names the groups, so they know whom to ask.

Activity

The Activity tab lists the last 300 changes made with Undermark on your site: When, Who, What (edited source, restored a version, edited template, restored template backup, find and replace, undid find and replace), Where and Change (version numbers, lines added and removed, and the note). Each page change is also a normal version in that page's history.

Licensing and trials

Undermark is paid through Atlassian, from the first user, with a 30-day free trial. Up to 10 users it is $8 a month. Above 10 users it is billed per user, graduated, starting at $1.15 per user per month for users 11 to 100. Annual billing is 10 times the monthly price. Atlassian handles billing, invoices and refunds.

If the license is not active, a banner says "Your Undermark license is not active." You can still open the editor, read and format the source, see your changes, browse history, view templates (space admins and Confluence admins) and run a find and replace dry run. Saving is off: Review and save, Restore this version, template saves and restores, Replace and Undo are disabled, and the server refuses them with a message to start a trial or renew in Apps > Manage apps.

Confluence admins can still save access settings that narrow access while the license is inactive: limit the editor to groups, remove groups, turn features off or require a note. That way you can always lock Undermark down. Changes that widen access (allow everyone again, add a group, turn a feature back on, stop requiring a note) need an active license, and the server refuses them with a message saying so.

Permissions and data

Undermark runs on Atlassian's Forge platform and sends nothing to any outside server. The app has no external network permissions and loads nothing from outside Atlassian.
Every read and save of a page, blog post or template runs as the signed-in person, so Undermark can only show and change what that person can already see and edit in Confluence. Versions you save show you as the author.
Undermark stores, in Forge storage for your site:
- admin settings (allowed groups and feature switches),
- template backups (the last 10 per template),
- find and replace job records (page ids, titles, version numbers, and the search and replacement text) for the last 20 jobs per space, so jobs can be undone,
- the activity log (the last 300 entries: time, account id, action, page or template title, version numbers, line counts and the note),
- per-person preferences (the format you used last, and whether you dismissed the review prompt).
Page and blog post content is not stored by the app. It stays in Confluence.
The activity log and admin settings are visible only to Confluence admins. Find and replace is visible only to space admins.

Limits and known gaps

Pages and blog posts must be published. Drafts open with "Publish this page first."
The source of one page can be up to 4 MB.
History shows the most recent 50 versions.
Templates are edited as storage format only. The template list covers page templates.
A template backup is skipped if the template is larger than about 200 KB; the save message tells you when that happens. Older backups are dropped first when backups of a large template approach that size.
Find and replace works on the storage format of the pages and blog posts of one space at a time. A dry run stops after 5,000 pages; apply the matches and run it again for the rest. Find can be up to 500 characters and Replace with up to 5,000.
Page text only skips pages whose source is not well formed, because a text-only replace would not be safe there.
When you save storage format on a page made in the current editor, Confluence converts it and may drop elements it can't represent (see "Storage format or ADF?").
Confluence removes scripts and event attributes when it saves. Undermark warns you about them but can't keep them.

FAQ

Where is the button? In every page's and blog post's ••• (More actions) menu as Edit source, and as Source in the byline. If your admin limited the editor to groups, it still opens and tells you why you can't save, instead of disappearing.

Can I limit the editor to certain groups? Yes. Confluence administration > Source editor > Access limits it to groups, and the limit is checked on the server for every save.

Can I edit page templates? Yes. Space admins edit their space's templates and Confluence admins edit global templates, with a backup kept on every save.

Do I have to close the page editor first? No. Open Edit source from the page you are viewing, save once, and click Reload the page to see the result. One save is one version.

How do I stop people from breaking pages? Invalid source is never saved, every save shows a diff first, a newer version is never overwritten without an explicit step, and any version can be restored in one click. Admins can require a note on every save and see every change in Activity.

Will find and replace mess up my page formatting? Not in the default Page text only scope, which never touches tags, links or macro settings. In either scope you see a dry run with per-page diffs first, pages whose result would be invalid are skipped, and the whole job can be undone.

Can I see the source of an older version? Yes. History shows the source of any of the last 50 versions, compares it with the current one, and restores it as a new version.

Confluence adds extra paragraphs or changes my markup when I save. Why? Pages made in the current editor are stored as ADF, so storage format edits are converted on save. Switch to ADF (JSON) to edit the stored content directly.

Who can see what I change? Your saves are normal page versions with you as the author. Confluence admins also see them in Activity.

Uninstalling and your data

Everything you saved with Undermark is ordinary Confluence content: page and blog post versions and template text stay after you uninstall. When the app is uninstalled, Atlassian deletes Undermark's stored data for your site (settings, template backups, replace job records and the activity log) through Forge's data deletion process.

Support

Open a request in the Great Work support portal (linked from the Marketplace listing) or email hello@greatwork.company. First response within 1 business day.