> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.markup.ai/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.markup.ai/_mcp/server. # Markup AI for XMetaL Author — Integration Guide > Install, configure, and use the Markup AI plugin inside XMetaL Author to check, score, and rewrite your XML documents without leaving the editor. 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](https://developer.microsoft.com/microsoft-edge/webview2/) 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](https://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** > **Warning** > > **Unblock the download first (Mark of the Web).** Windows tags anything downloaded from the internet as "came from another computer," and XMetaL silently refuses to load a still‑blocked plugin — the **Markup AI** menu never appears, with no error message. Right‑click the downloaded installer → **Properties** → tick **Unblock** → **OK** *before* you install. Use the **self‑extracting installer**, **`MarkupAI.XMetal.Plugin-Installer-.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. #### Unblock and close XMetaL Right‑click **`MarkupAI.XMetal.Plugin-Installer-.exe`** → **Properties** → tick **Unblock** → **OK**. Then **close XMetaL Author** — a running XMetaL locks the plugin files, and the installer stops with *"XMetaL appears to be running"* until you close it. #### Run the installer with your Author folder path From a command prompt, run the installer, passing the path to your XMetaL **`Author`** folder (the version part of the path depends on your XMetaL version): ``` MarkupAI.XMetal.Plugin-Installer-.exe "C:\Program Files\XMetaL \Author" ``` It verifies the folder is a real XMetaL install and copies the plugin files into place. Run it with **no arguments** to be prompted for the path, or `--help` for options. **Administrator rights** are needed only if you can't write to XMetaL's own folder — the case for the default install under `C:\Program Files`, but not for one on another drive. The installer checks and tells you if it needs an elevated prompt. #### Start XMetaL Open a document — a new **Markup AI** menu appears after **Help**. Click **Markup AI ▸ Show Sidebar**. ![PowerShell console output from the Markup AI for XMetaL installer, showing the plugin version, the verified XMetaL Author folder, and the installed confirmation.](/_fern-img/8186f12a751ae4981daba45d59c0b3a5c1a236616e98088b1d74af2bb15b99f0.webp) ### **Where the plugin is installed** The installer places 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 run the newer installer the same way — it overwrites the previous install in place. The installer prints the version it's installing, so you can confirm which build you're on. * **To uninstall**: close XMetaL, then delete the `…\Author\DotNet\markupai` and `…\Author\MarkupAiSidebar` folders and the `MarkupAiSidebar.mcr` file in `…\Author\Startup`. Leave the rest of the `Startup` folder alone — it belongs to XMetaL. There is no registry state to clean up. --- ## **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. ![XMetaL Author menu bar with the Markup AI menu open, showing the Show Sidebar item.](/_fern-img/e1ac1507a2481986153cad9222bfd2d5aca837e61af71cf3cd1ce5148add15c0.webp)![XMetaL Author with the Markup AI sidebar docked in the Resource Manager, showing the Sign in to Markup AI view with Sign In and Sign Up buttons.](/_fern-img/4e3dc9c8408c756b155dec79d82c3f161734cee7173c13f914359c5b95cea61e.webp) > **Note** > > Login opens in your default browser rather than a popup inside the plugin, so you don't have to sign in from scratch every time. To force a fresh sign‑in, close XMetaL and delete the WebView2 profile folder at `%LocalAppData%\MarkupAI\Sidebar\XMetal\WebView2` (it's recreated on next launch). --- ## **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. ![Markup AI sidebar docked beside a document after a check, showing a High Risk banner, 45 issues found, a severity breakdown, and issues grouped under Brand and Style.](/_fern-img/8cf24f7d36f26cebe629e0707628695720d03e31518f2cd02159dd27e054f5ed.webp) --- ## **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. ![Expanded Markup AI issue card showing a suggested replacement, a Why this matters explanation, and Mark as Resolved and Dismiss actions, with the flagged word highlighted in the document editor behind it.](/_fern-img/8cf24f7d36f26cebe629e0707628695720d03e31518f2cd02159dd27e054f5ed.webp) 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: ```powershell Get-ChildItem "C:\Program Files\XMetaL \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](https://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 ``, ``, or ``). 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. --- ## **Under consideration** We're exploring the following enhancements, though we can't commit to specific timelines yet. * Checking a whole DITA map. ## **Known limitations** * **No selection‑based check.** Checks always cover the whole document, not a highlighted range. * **Suggestions that cross inline tags can't be applied.** A flagged span that overlaps an inline element boundary (``, ``, ``, and similar) is rejected with a message in the sidebar. Fix those by hand.