/html-to-page

name: html-to-page
description: "Use when the user hands over a finished HTML page (a file, a paste, a designer or AI export) to recreate in WordPress, in any builder: Elementor, Divi, Bricks, Gutenberg, Breakdance, Oxygen, Beaver Builder or WPBakery. One Respira Exhale call writes it as native, editable builder elements that look like the file; this skill covers the input, the call, the choices and the check."
license: MIT
metadata:
  author: Respira for WordPress
  author_url: https://respira.press
  version: 1.0.0
  mcp-server: respira-wordpress
  category: migration

HTML to a builder page

**Version:** 1.0.0 **Updated:** 2026-10-04 **Category:** migration **Status:** stable **Requires:** Respira for WordPress plugin (9.1+) and an MCP connection, on a site running a supported builder

---

Description

A finished HTML page becomes a new WordPress page in the site's own builder, in one call to `respira_convert_html_to_builder` (Respira Exhale). The conversion is deterministic code on the site, so no tokens are spent writing builder structure.

On Elementor, Divi, Bricks, Gutenberg (and block plugins such as Kadence, Spectra, GreenShift), Breakdance, Oxygen Classic, Beaver Builder and WPBakery it runs in **fidelity mode** whenever the document has a stylesheet:

• the file's structure is written one to one as the builder's own elements: sections, containers or rows, headings, text, buttons and images, each editable in the builder
• every class and id stays on its element
• the stylesheet travels verbatim, scoped to the page, so the page looks like the file on desktop and phone, hover states, transitions and keyframe animations included
• the page goes on the builder's blank template, so no theme header, page title or footer sits on top of a page that draws its own

Prefer this to writing the page by hand with `respira_build_page` whenever the file exists. A hand-built page has to restate every inherited style (font, weight, line height, colour) on every widget, and any style it misses falls back to the theme or the builder kit, so it drifts from the file. The converter carries the stylesheet itself.

---

When to use

• The user pastes or attaches an HTML file and asks for it as a WordPress page.
• A designer, a site generator or another AI produced a landing page as HTML.
• A static page from an old site has to move into the builder.

Do not use it to build a page from a description or a brief (use `respira_build_page`, or the build skill for the builder), or to change an existing page (use the find and update tools on a draft duplicate).

Trigger phrases

• "convert this html to elementor" (or divi, bricks, gutenberg, breakdance, beaver, wpbakery, oxygen)
• "recreate this html page in wordpress"
• "turn this file into a page"
• "import this landing page"

---

Workflow

1. Read the site

Call `respira_get_site_context` and `respira_get_builder_info`. Note the active builder and its version. When the user named a builder, pass that one; otherwise the converter uses the active builder.

2. Prepare the input

Send the whole document: `<head>` with its `<style>` blocks and font links, and the `<body>`. Do not strip the head.

• **Linked stylesheets** over https (Bootstrap, a design system) are fetched and carried with the page. Google Fonts links are kept as font links.
• **Images** need absolute URLs the site can reach. A relative path (`images/hero.jpg`) or a local file renders broken: upload it first with `respira_upload_media` or `respira_sideload_image` and put the media URL in the file.
• **Tailwind through the CDN script** (`cdn.tailwindcss.com`) does not convert: the script never runs on the site, so the classes carry no design. Compile the CSS (Tailwind CLI or the Play CDN export) into a `<style>` block first. The converter warns when it sees the script.
• **Scripts** are not carried. Anything the page does only in JavaScript (a slider, a counter, a menu toggle) is lost; CSS animations, transitions and hover states are kept. Tell the user which behaviours were script-driven.
• **Forms** keep their markup but post nowhere on WordPress. Say so, and offer to rebuild them with the site's form plugin.
• The scoped stylesheet can carry about 150 KB on fidelity builders (100 KB on others). Over that the call refuses with `respira_css_too_large` and creates nothing: trim unused rules and extra font weights, then convert again.

3. Convert

respira_convert_html_to_builder {
  html: "<!doctype html>...the whole file...",
  builder: "elementor",
  options: { title: "Spring landing page", status: "draft" }
}

• `status` defaults to `draft`. Keep it a draft; publishing is the user's call.
• `blank_template` defaults to true. Pass `false` when the file is content only and the site's own header and footer should stay around it (on Divi with Theme Builder headers this matters most).
• Leave `mode` unset. `"restyle"` re-types the design into builder settings and site tokens instead of carrying the stylesheet; use it only when the user explicitly wants every style in the builder's own controls, and tell them it will not match the file as closely.
• Every call creates a new page. After an error or a timeout, check `respira_list_pages` for a page that already landed before you call again.

4. Read the report

The result is the evidence. Check, and pass on to the user what matters:

• `mode`: `fidelity` on the builders listed above.
• `fidelity.structure`: sections, containers, headings, images, buttons, texts, and `raw` (leaves kept as markup). A page whose content is mostly in `raw` deserves a look.
• `fidelity.css_carried`: bytes against the cap.
• `fidelity.images`: `unresolved` must be 0.
• `fidelity.attributes_dropped`: attributes the builder cannot carry on that element (an `aria-*` on a wrapper, say).
• `fidelity.template`: what was requested and what was stored.
• `warnings`: read every one.

5. Check the render

The report counts structure;