HTML to WordPress

What should you prepare before you convert HTML to WordPress?

A conversion goes faster when the agent can see the whole page at once and knows which parts matter. Collect the files first, decide what the WordPress version has to do, and set up a place where a mistake costs nothing.

Before you start

• A staging copy or a fresh WordPress install, never your live site
• The page's HTML file plus every CSS file it loads
• The images, logos and font files the page uses, gathered in one folder
• A note of every form, embed or script on the page
• A recent backup of the WordPress site you are building on

If the page came from a site builder export, open the HTML file in a browser and check that it still renders on your own machine. Broken relative paths are much easier to fix before the agent starts than halfway through the rebuild.

How does each part of an HTML page map to WordPress blocks?

Most static pages are assembled from a small set of patterns, and nearly every one of them has a native block that does the same job. Knowing the mapping helps you read the draft the agent produces and spot the places where it had to guess.

Sections that fit none of these rows, such as a pricing toggle or an image carousel, are the ones the agent should flag for you instead of faking with a pile of nested groups.

How do you keep your design when the CSS moves into WordPress?

The most common mistake in an HTML to WordPress conversion is pasting the old stylesheet into a custom CSS box and calling the job done. It looks right on day one, then breaks the first time someone adds a block that the old selectors never knew about.

The cleaner route is to move the design decisions instead of the selectors. Ask the agent to read your CSS and pull out the colors, font families, font sizes and spacing values, then save them as the site's global styles in the Site Editor. Blocks inherit those values automatically, so new content matches the old design without extra code.

What usually needs a manual touch

Custom breakpoints, complex hover effects and CSS animations rarely have a matching global style setting. Keep a short list as the agent finds them, and decide for each one whether it deserves a small block style or whether the page reads perfectly well without it.

How do you move images, fonts and other files?

An HTML page usually loads images from relative paths such as images/hero.jpg. WordPress cannot find those, so every image has to go into the Media Library and every block has to point at the new address. Ask the agent to upload each image, write alt text from the surrounding content, and swap the old paths while it builds.

Fonts need the same care. If your page loads a font from a hosted service, the WordPress Font Library can register the same family so the Site Editor offers it everywhere. If you were serving font files yourself, upload them through the Font Library instead of linking to the old folder.

Favicons, downloadable PDFs and video files are easy to forget. Add them to your file list, upload them to the Media Library, and check every link that pointed at them.

What should you paste into the chat?

Give the agent one page at a time. A focused request with the source attached produces a cleaner draft than an instruction to convert a whole folder in one go.

A first prompt that works

"Here is the HTML and CSS of our About page. Rebuild it on a new draft page called About using native blocks only, with no Custom HTML block. Move colors, fonts and spacing into global styles first. Upload the images from the attached folder to the Media Library. When you finish, list anything you could not convert."

Follow-up prompts for the second pass

"The three team cards stack in the wrong order on mobile. Put each photo above the name." Or: "The hero heading is hard to read over the photo. Add a dark overlay to the Cover block at about half opacity." Short, specific corrections like these land faster than asking for a full rebuild.

How do you convert a multi-page HTML site?

Start with the page that holds the most shared parts, usually the home page, and let the agent build the header, footer and global styles from it. Every page after that reuses those pieces, so the second and third conversions take far less effort than the first.

Once the shared parts exist, convert the remaining pages in order of traffic or importance. Ask the agent to keep a running list of the internal links it finds, so menu items and links inside the text can be pointed at the new WordPress addresses after every page exists.

If your source is a live website rather than a folder of files, the live URL to WordPress guide covers fetching the pages first. Designs that only exist in a design file are covered in Figma to WordPress, and sites leaving a hosted builder have their own route in Squarespace to WordPress.

How do you check the result before you publish?

Treat the draft as a first version, not a finished page. Open it in the editor and on the front end, then work through this order:

• Compare it side by side with the original at desktop width
• Resize to phone width and check that every section stacks sensibly
• Click every link and button, including the ones in the footer
• Confirm that each image has alt text and comes from the Media Library
• Run the page through a speed test and compare it with the old version

Anything that fails goes back to the agent as one short, specific request. Keep revisions switched on, so you can step back if a fix makes something else worse.

How do you replace an old static site without losing visitors?

If the HTML site is already live and indexed, its old addresses carry search traffic. Before you point the domain at WordPress, list every old URL, such as about.html, and set a 301 redirect to the matching WordPress page. A redirect plugin or your host's redirect rules both do the job.

Copy the old title tags and meta descriptions into your SEO plugin as a starting point, then improve them. After launch, watch for 404 errors for a few weeks and add redirects for anything you missed.

When the site is stable, the converters directory lists the other sources you can bring into WordPress, and the guide on letting an AI agent work on WordPress safely is worth reading before you hand the agent more of the site. The connection used in every step above comes from NibWP, the plugin that lets your AI client work directly on your WordPress install.

Troubleshooting

Most problems in this setup come from a handful of causes. Work through the matching fix below before you change anything else, and note what you tried.

The page looks right in the preview but breaks on the live site

This usually means the stylesheet loads on the preview page only. Check that the converted CSS was saved as global styles or enqueued site-wide, then clear any page cache and reload. If a font is missing, confirm the font files were uploaded to your own Media Library and not left pointing at the old host.

Headings come out in the wrong order

Static HTML often skips from an h1 straight to an h4 for visual reasons. Ask the agent to list the heading levels it found, then fix the structure first and handle the size with CSS. A clean outline helps screen readers and search engines alike.

Buttons turned into plain links

A styled anchor with no button class has nothing for a block to map to. Tell the agent which links are buttons, or paste the button CSS together with the markup. It can then use the button block and attach your colors.

The slider or animation did not come across

Scripts do not travel with markup, and they should not. Decide whether you still need the effect. If you do, choose a block or plugin that provides it and let the agent place the content inside, rather than pasting the old script.

Forms are empty or send nowhere

A static form posts to a service that only the old site knew about. Rebuild it with the form plugin on your site, then ask the agent to put the shortcode or block where the old form sat and test one real submission.

Links still point to the old file names

Internal links such as about.html need to become your new permalinks. Give the agent a list of old and new addresses and ask it to rewrite links in one pass. After that, see how a design-first rebuild handles links for a comparable checklist.

If none of these match, work from the outside in. First confirm the page loads at all, then check that the styles load, then check the blocks themselves. Most conversion problems turn out to be a loading problem, not a content problem, so the cheapest checks come first. Keep a short log of what you changed so you can undo it.

A useful habit is to keep the original HTML file open beside the new page while you check. Compare headings, links and images one by one, and write down each difference you find. Fixing the same kind of problem across every page at once is quicker than treating each page as a new puzzle.

Doing it by hand vs with an AI agent

Both routes end with editable pages. They differ in effort, control and the kind of site they suit.

Read the table as a guide, not a verdict. A tidy five-page brochure site is often finished faster by hand than it is explained to an agent. A large archive with repeated templates is where the agent route starts to pay off, because the same mapping applies again and again.

Checklist before you publish

Run through this list on every page or batch. It takes a few minutes and catches the problems that are slow to fix later.

• Every page has exactly one h1 and a sensible heading order
• Images come from your Media Library and carry useful alt text
• Internal links use the new permalinks, not old file names
• Forms were rebuilt and one test submission arrived
• The page works at phone width without sideways scrolling
• Fonts load from your own site or a source you chose on purpose
• Old addresses redirect to the new pages
• A backup exists from before the first change
• You previewed every page as a logged-out visitor
• The title and description of each page are set and unique

Do the checklist on a staging copy first, then repeat the quick items on the live site after publishing. A page that passes on staging can still fail live because of caching, a different server setting or a missing redirect. The second pass is short and worth doing every time.

Glossary

Native block. A piece of content, such as a heading or list, that the WordPress editor understands and lets you change without touching code.

Custom HTML block. A block that stores raw markup. It displays correctly but is hard for others to edit later.

Global styles. Site-wide color, font and spacing settings that every block can reuse.

Permalink. The permanent web address of a page on your WordPress site.

301 redirect. A signal that a page moved for good, so visitors and search engines follow the new address.

Media Library. The place WordPress keeps your uploaded images and files.

Enqueue. The WordPress way of loading a stylesheet or script on the pages that need it.

Staging. A private copy of your site where you test before anything goes public.

None of these terms need deep technical knowledge. If a word in a reply from your AI client is unfamiliar, ask it to explain in one sentence and show where the setting lives in WordPress. Learning the vocabulary makes your reviews faster and your instructions clearer.

Common mistakes

• Converting everything at once. Start with one page, review it, and only then repeat the process. Problems found early cost little.
• Pasting the whole file as one block. That brings back the editing problem you wanted to leave behind. Ask for separate blocks per section.
• Forgetting the old addresses. Visitors and search engines still use them. Plan redirects before you switch the domain.
• Skipping the mobile check. Desktop previews hide narrow-screen problems. Test on a real phone.
• Working on the live site first. Build on a staging copy as described in the safe AI workflow checklist, then publish.

If your source is a live site rather than a file, the live URL guide covers that starting point. Whichever source you use, the finish is the same: native blocks, global styles, clean links and a short final review from the point of view of a first-time visitor.