Markup AI for XMetaL Author — Integration Guide

Use Markup AI inside XMetaL Author to check, score, and rewrite content while you author. The integration runs as a sidebar hosted inside XMetaL — open a document, click Markup AI ▸ Show Sidebar, and review issues from the panel without leaving the editor.

The plugin analyzes the active document and applies suggestions in place, so you can triage issues and rewrite text right where you’re working.

What you need

• XMetaL Author on Windows — the plugin hosts the Markup AI sidebar and requires XMetaL to load it.
• The Microsoft Edge WebView2 runtime — the sidebar renders in WebView2. It’s preinstalled on Windows 11 and current Windows 10; if the sidebar opens blank, install it and restart XMetaL.
• The .NET Framework 4.7.2 runtime (or later), which ships with current Windows 10/11.
• A Markup AI account — create one at console.markup.ai.

Which agents are supported

• Style Agent

What Markup AI does for you in XMetaL Author

• Check & score: Analyze the active document and get a Content Risk level (High / Medium / Low Risk) plus a count of issues found.
• Grouped, filterable issues: Issues from the Style Agent are returned as a categorized list. Filter by severity (High, Medium, Low) or by category (Style, Brand, Consistency, Clarity, Tone).
• Jump to issue in the document: Click an issue card in the sidebar to select the matching text in the XMetaL editor — in both Normal and Tags On view.
• Apply a suggestion: When Markup AI returns a suggested replacement, click it in the issue card to rewrite the text directly in the document.
• Results for each document: The sidebar follows the active document and keeps separate results for every document you check, so switching between open documents doesn’t lose your place.
• Docked where you work: The sidebar opens as a Markup AI tab in XMetaL’s Resource Manager, alongside your other panes.

Installing the plugin

There are two ways to install Markup AI for XMetaL Author. Both install the same plugin — pick one:

• Install from the exe — a self‑extracting installer that sets everything up in one command.
• Install from the zip — a zip with a PowerShell install script, if you’d rather not run an exe.

Install from the exe

Use the self‑extracting installer, MarkupAI.XMetal.Plugin-Installer-<version>.exe. It copies the plugin into your XMetaL install and wires up the Markup AI menu in one command — nothing is written to the Windows registry. The exe is Authenticode‑signed, which keeps Windows SmartScreen prompts to a minimum.

MarkupAI.XMetal.Plugin-Installer-<version>.exe "C:\Program Files\XMetaL <version>\Author"

Install from the zip

The same plugin also ships as MarkupAI.XMetal.Plugin-<version>.zip, with an Install.ps1 script inside.

.\Install.ps1

.\Install.ps1 -XMetalAuthorDir "C:\Program Files\XMetaL <version>\Author"

Where the plugin is installed

Both methods place files in three folders inside your XMetaL install: the plugin itself in …\Author\DotNet\markupai, the startup macro in …\Author\Startup, and the sidebar loader script in …\Author\MarkupAiSidebar. The plugin is available to every user of that XMetaL install — there is no per‑user enable step.

Updating and uninstalling

• To update: close XMetaL and install the newer version the same way you installed the first one — it overwrites the previous install in place. The installer or script prints the version it’s installing, so you can confirm which build you’re on.
• To uninstall: close XMetaL, then run .\Install.ps1 -Uninstall from an extracted copy of the plugin zip. It deletes the installed files and nothing else — there is no registry state to clean up. Without the zip, delete the three folders listed under Where the plugin is installed by hand.

Launching Markup AI in a document

1. Open any document in XMetaL Author.
2. Show the sidebar in either of these ways:
   • Click Markup AI ▸ Show Sidebar on the menu bar (the Markup AI menu sits after Help).
   • Run the Markup AI - Open Sidebar macro from Tools ▸ Macros (or press Ctrl+Shift+P to Play Macro and pick it from the list).
3. The sidebar opens as a Markup AI tab in the Resource Manager. If the Resource Manager isn’t available in your XMetaL setup, the sidebar opens as a floating window instead.
4. Sign in to Markup AI if prompted. Sign‑in opens in your default browser (where you’re usually already signed in); complete it there and return to XMetaL, and the sidebar switches to the main view automatically. Your session is remembered across XMetaL restarts.

Configure your check

Before your first check, open the Settings panel (gear icon at the top of the sidebar) and pick the right configuration for your team:

• Style Guide: Select your team’s style guide from the dropdown. When you sign in (or switch organizations), the plugin selects your organization’s default target as the active style guide.
• Available agents: The Style agent checks for style‑guide compliance, passive voice, word choice, and consistency.

Settings persist across documents, so you only need to configure them once per session. If you change a setting after running a check, re‑run the check to apply the new configuration.

Running a check

1. Open the document you want to check. Checks run against the document’s current content in the editor, whether or not it’s saved.
2. In the Markup AI sidebar, click Check. The plugin extracts the active document’s XML, analyzes it, and posts the result back to the sidebar.
3. The header updates with:
   • A Content Risk banner — High Risk, Medium Risk, or Low Risk.
   • An issue count (for example, 48 issues found).
   • A severity breakdown — counts of High, Medium, and Low issues.
   • A Group / List view toggle.
4. Re‑run Check any time you want to refresh the score after editing.

The content is captured at the moment you click Check, so you can keep editing while the check runs without affecting the result. Checks work the same way in Normal and Tags On view.

Reviewing and resolving issues

Once the check completes, Markup AI lists every issue under the Suggestions section. Use the controls at the top of the list to triage:

• Severity pills — Click High, Medium, or Low to scope the list to one severity level. Counts update as you work through issues.
• Group / List — Toggle between Group view (issues grouped by category with counts, like Brand 62, Style 85) and List view (a flat, ordered list).

Working through an issue card

1. Click anywhere on an issue card to expand it. The card reveals:
   • The category label (Consistency, Clarity, Spelling and grammar, Tone, etc.) and the severity tag (HIGH / MEDIUM / LOW).
   • The issue text — the exact phrase Markup AI flagged.
   • The suggested replacement (when Markup AI has one) shown under a SUGGESTION label.
   • A Why this matters explanation of the rule.
2. Click the issue text at the top of the card to select the matching content in the XMetaL editor — this jumps you to the exact range in the document.
3. Decide what to do for each card:
   • Apply the fix — click the suggested replacement (under SUGGESTION) to rewrite the text directly in the document.
   • Edit manually — fix the text in the editor, then click Check again to re‑score.
   • Dismiss — remove an issue that doesn’t apply.

The plugin keeps positions accurate even if you’ve edited the document since the check ran — insertions or deletions elsewhere in the document don’t throw suggestions off. If you’ve changed the flagged text itself, the plugin refuses to guess: selecting or applying that suggestion fails with a message instead of landing on the wrong text. Run Check again to refresh.

Working with multiple documents

The sidebar stays open for your whole XMetaL session and keeps separate results for each document you check.

• Switching documents: The sidebar updates as soon as you switch. If you’ve already checked that document, its results come back right away. If you haven’t, the sidebar shows a “not analyzed yet” message.
• Opening a new document: The sidebar makes it the active document automatically — no extra click needed.
• Closing the sidebar: If the sidebar is floating, closing its window only hides it. Click Markup AI ▸ Show Sidebar again and it comes back with your previous results intact.
• Applying a suggestion: A suggestion only ever edits the document it came from.

Troubleshooting

• The Markup AI menu doesn’t appear after installing — first make sure you restarted XMetaL after the install finished. If it’s still missing, the plugin files are almost certainly blocked by the Mark of the Web. Unblock the installer exe (right‑click → Properties → Unblock) and run it again.

  To unblock the already‑installed files in place instead, run this once in an Administrator PowerShell, then fully restart XMetaL:

  Get-ChildItem "C:\Program Files\XMetaL <version>\Author\DotNet\markupai" -Recurse | Unblock-File

• The installer stops with “XMetaL appears to be running” — close every XMetaL window (check the system tray and Task Manager for a lingering xmetal process) and run the installer again.

• The sidebar opens blank — your machine is probably missing the Microsoft Edge WebView2 runtime. Install it from developer.microsoft.com/microsoft-edge/webview2 and restart XMetaL. The bundle already contains everything else the plugin needs.

• A suggestion says “This suggestion’s span overlaps markup and can’t be selected or replaced” — the flagged text runs across an inline element boundary (for example, part of a <term>, <ph>, or <xref>). Apply that fix by hand in the editor, then re‑run Check.

• Sign‑in doesn’t stick, or you want a clean session — close XMetaL and delete the WebView2 profile folder at %LocalAppData%\MarkupAI\Sidebar\XMetal\WebView2. It’s recreated on the next launch.

• Something else went wrong — the plugin writes a diagnostics log you can send to Markup AI support. Paste this into the Windows Explorer address bar and attach diagnostics.log:

  %LocalAppData%\MarkupAI\Sidebar\XMetal

FAQ

• Which versions of XMetaL are supported? Markup AI supports the latest version of XMetaL Author.
• Can I check just a selection? No — checks run against the full active document.
• Does it work with DITA maps? You can open a map and run a check, but map documents are read‑only to the plugin: suggestions can’t be applied into a map. Open the referenced topics to check and fix them.
• Which XMetaL views are supported? Selecting and applying suggestions works in both Normal and Tags On view.
• Why did my results disappear after I renamed or moved a document? Markup AI tracks each document by its file path, so a renamed document looks unchecked. Run Check again under the new name.
• Can I move or resize the sidebar? Yes — it’s a standard Resource Manager tab, so it follows however you’ve arranged the Resource Manager. If it opened as a floating window, drag and resize it like any other window.
• Does installing need administrator rights? Only if XMetaL’s own folder isn’t writable by you — true for the default C:\Program Files install, not for one on another drive. Nothing is written to the registry, and uninstalling is a file delete.

Known limitations

• One document at a time. Checks run against the single active document — there’s no map‑ or project‑level check.
• No selection‑based check. Checks always cover the whole document, not a highlighted range.
• DITA maps are read‑only. Suggestions can’t be applied into map documents.
• Suggestions that cross inline markup can’t be applied. A flagged span that overlaps an inline element boundary (<term>, <ph>, <xref>, and similar) is rejected with a message in the sidebar. Fix those by hand.
• No inline squiggles. Issues appear as cards in the sidebar. Click a card to select the matching text in the editor — Markup AI doesn’t underline issues in the document.