Convert a static HTML design into a classic WordPress theme, then inspect, install, configure, and test the generated template files.
Converting HTML to a WordPress theme means more than changing file extensions from .html to .php. WordPress has to select the right template for each request, load shared template parts, retrieve content, repeat posts, and generate links from site data.
With Forge, the process is to prepare representative static pages, add data-forge-* markers that describe their structure, choose the WordPress target, inspect the generated classic theme, install it, configure WordPress, and test each important page type.
Know Which Kind of WordPress Theme You Are Building
WordPress supports classic themes and block themes. The distinction matters before you convert anything.
A classic theme uses PHP template files such as index.php, single.php, page.php, header.php, and footer.php. A block theme uses HTML templates made from block markup.
Forge's documented WordPress output is a classic PHP theme. This tutorial does not convert a static design into a block theme or Full Site Editing templates.
WordPress chooses a template through its template hierarchy. A request for a single post, a page, the posts index, a category archive, or search results can each resolve to a different template. If a more specific file is missing, WordPress falls back through the hierarchy and ultimately reaches index.php in a classic theme.
That is why the conversion starts with page roles, not one giant HTML file.
Prepare the Static Source
Your design should work as ordinary HTML before Forge touches it. Navigation, responsive behavior, scripts, styles, and images should load from within the source folder.
Forge recommends a structure with these representative inputs:
src/
assets/
blog/
list/
index.html
single/
index.html
pages/
about.html
contact.html
index.html
page.html
screenshot.png
The home page, posts list, single post, and default page each give Forge a different template role. Files under pages/ can become named templates for designs that need their own layouts.
The Forge WordPress guide also calls for a 1200 by 900 pixel screenshot.png in the theme root. WordPress displays that image when someone reviews themes in the administration interface.
If the source pages do not yet have consistent partials, loops, and content regions, start with the separate guide to structuring HTML for theme conversion.
Mark the Reusable Regions
Forge uses data-forge-partial to recognize shared regions. Common WordPress source markers include:
<head data-forge-partial="head">
...
</head>
<nav data-forge-partial="nav">...</nav>
<footer data-forge-partial="footer">...</footer>
<div data-forge-partial="scripts">...</div>
The typical generated theme contains header.php, footer.php, and files under template-parts/ for the marked regions. Keep each marker on the element that owns the complete region so opening and closing markup does not become separated accidentally.
For navigation that WordPress should manage, place data-forge-menu="primary" on the menu list:
<ul class="navbar-nav" data-forge-menu="primary">
<!-- static preview items -->
</ul>
Forge also documents an optional footer menu location and a data-forge-cta marker for a navigation call to action.
Map Posts and Page Content
The list page needs a collection loop, a repeating item, and bindings for values WordPress supplies:
<main data-forge-block="main">
<section data-forge-loop="blog">
<article data-forge-item="post">
<h2 data-forge-bind="title">Sample post</h2>
<p data-forge-bind="summary">Sample excerpt.</p>
<time data-forge-bind="date">August 5, 2026</time>
<a data-forge-bind="url" href="single.html">Read more</a>
</article>
</section>
</main>
Forge maps those hints to WordPress fields and The Loop in the generated output.
A single post or page needs a content shell and a place for the body:
<main data-forge-block="content">
<article>
<h1 data-forge-bind="title">Sample title</h1>
<div data-forge-block="content-slot">
<p>Sample body content.</p>
</div>
</article>
</main>
Use data-forge-link for internal links that should become WordPress-aware routes. Keep ordinary external links as normal URLs.
Not every page needs every marker. The Data Markers reference is the canonical list and explains advanced content blocks, protected regions, pagination helpers, menus, and bindings.
Convert the Site in Forge
Before using your own design, download the WordPress sample linked from the Forge guide and convert it without changes. That gives you a known input and a reference output.
For a custom project:
- Open Forge and map the source folder and representative files.
- Select WordPress as the target.
- Review page roles and conversion options.
- Enable navigation exposure on
index.htmlif WordPress should control the marked primary menu. - Choose a separate output folder.
- Run the conversion.
Do not generate directly over the source project. Keeping input and output separate makes the conversion reviewable and prevents generated PHP from being confused with the static design files.
Inspect the Generated Theme Before Installing It
Forge documents a typical WordPress output containing:
wordpress-theme/
style.css
functions.php
index.php
header.php
footer.php
front-page.php
home.php
single.php
page.php
search.php
archive.php
category.php
tag.php
template-about.php
template-contact.php
template-parts/
assets/
Your exact output depends on the mapped inputs and options. Review it rather than assuming every possible template will be present.
Check these areas first:
style.csscontains valid theme metadata and the expected styles are reachable.functions.phploads assets and registers the expected menu locations.front-page.php,home.php,single.php, andpage.phppreserve the correct layout roles.- Template parts contain complete shared regions.
- The posts loop uses dynamic WordPress values rather than sample text.
- Internal URLs and asset paths no longer depend on the original folder depth.
- Output files contain no unwanted sample copy or external development paths.
This review is where an HTML to WordPress template conversion becomes a maintainable theme rather than an opaque export.
Install and Configure the Theme
Copy the generated theme folder into:
wp-content/themes/
Then open WordPress administration and activate it under Appearance and Themes.
For a site with a designed home page and a separate posts index, open Settings and Reading. Select a static homepage and a posts page. WordPress will use front-page.php for the front page and home.php for the posts index when those files and settings are present.
If you exposed the marked navigation, create or select the WordPress menu and assign it to the generated location under the menu management interface. Administration screens can vary with the WordPress installation and active plugins, so verify the location rather than relying only on its visual position.
If the design has search, Forge documents a search loop plus a GET form with role="search", action="/", and an input named s. Confirm that a query reaches the generated search.php and that both results and no-results states remain usable.
Test the Theme as WordPress Uses It
Opening front-page.php directly is not a valid theme test. Run WordPress and visit the request types that exercise the hierarchy.
At minimum, test:
- The front page
- The posts page
- A single post with short and long content
- A normal page using
page.php - Each named page template you intend to keep
- A category, tag, or date archive that the site exposes
- Search results and no results
- Primary and footer menus at desktop and mobile widths
- Posts with and without featured images, excerpts, and categories
- Pagination when the site has enough content to trigger it
Also inspect the browser console and network requests for missing assets. Test from a WordPress installation whose URL differs from the static preview path, because hard-coded development URLs often hide until that point.
What Forge Does Not Convert
Forge converts marked source HTML into editable classic-theme files. It does not migrate an existing WordPress database, posts, pages, users, plugins, settings, or media library.
It also does not remove the need for WordPress development knowledge. Custom fields, plugin integrations, complex queries, block-editor styling, accessibility review, security review, and deployment remain separate work when the project requires them.
The practical benefit is narrower: Forge can handle the repeatable translation from explicit HTML regions to the documented WordPress theme structure, leaving you with PHP files you can inspect and maintain.
Frequently Asked Questions
Can I convert any HTML page into a WordPress theme automatically?
Not reliably without preparation. A static page does not state which content repeats, where WordPress should insert a post body, or which navigation WordPress should manage. Forge relies on documented markers and mapped page roles to make those decisions explicit.
Does Forge create a block theme?
No. Its documented WordPress workflow creates a classic PHP theme. Use WordPress's block-theme documentation and tooling when Full Site Editing is a project requirement.
Do I need index.php and style.css?
Yes for a classic theme. WordPress documents those as the required classic-theme files. More specific templates allow the theme to handle different request types without putting every case into index.php.
Will the conversion import my existing content?
No. Theme conversion and content migration are different jobs. Plan imports, media handling, redirects, and data cleanup separately.
What to Do Next
Start with the documented sample, not your largest production design. Convert it, compare the output with the Forge on-disk reference, install it in a test WordPress environment, and walk through the validation list above.
When that path is clear, review the Forge WordPress conversion page and WordPress Getting Started guide before mapping your own design. The Aeriform Forge overview provides the broader context for deciding where conversion belongs in your workflow.