Prepare static HTML for theme conversion by defining page roles, reusable partials, repeating content, dynamic fields, links, and content slots.
A website can look finished in a browser and still be difficult to convert into a theme. Theme conversion needs more than clean styling. It needs an explicit answer to which parts are shared, which content repeats, which values change, and where a CMS or static-site generator should insert page content.
The practical way to structure HTML for theme conversion is to define representative page roles, keep shared regions consistent, identify loops and dynamic fields, provide a clear content slot for single pages, and normalize links and asset paths before conversion begins.
Start With Page Roles
Do not start by annotating every HTML file in the project. First, identify the smallest set of layouts that represents the site.
A typical content site needs:
- A home page
- A default page layout
- A list page for posts or another collection
- A single-item layout for one post or collection entry
- Named page designs when About, Contact, or another landing page genuinely needs a different layout
Forge's recommended source structure expresses those roles like this:
src/
assets/
blog/
list/
index.html
single/
index.html
pages/
about.html
contact.html
index.html
page.html
The folder names are not a universal web standard. They are a useful contract between the source design and Forge. A project can use another collection name, such as products or episodes, as long as its role remains clear.
This step also exposes missing designs. If a static export contains a home page and three polished landing pages but no representative post list or single post, a converter has no reliable example for those templates.
Make Shared Regions Consistent
Headers, navigation, footers, and script groups usually become partials or template parts. Before marking them, compare them across the representative pages.
The markup does not need to be identical in every detail, but it should not contain accidental differences. A navigation list with different classes on each page forces you to decide whether those are meaningful states or design drift.
Forge uses data-forge-partial to identify these regions. Place the marker on the semantic element that owns the complete region:
<head data-forge-partial="head">
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1" />
<link href="assets/css/site.css" rel="stylesheet" />
</head>
<nav data-forge-partial="nav" aria-label="Primary navigation">
<!-- navigation markup -->
</nav>
<footer data-forge-partial="footer">
<!-- footer markup -->
</footer>
Define the shared partials on index.html first. That gives the converter a stable reference for regions that appear throughout the theme.
Do not mark every reusable CSS class as a partial. A partial is a reusable template region, not merely an element that shares visual styling.
Separate List Structure From Sample Content
A static list page might contain copied cards, product entries, or simple rows of article titles and links. The target platform needs one complete item template and a loop that repeats it for real content.
Mark the collection region with data-forge-loop and one representative item with data-forge-item:
<main data-forge-block="main">
<section data-forge-loop="blog">
<article data-forge-item="post">
<img
data-forge-bind="featured_image"
src="assets/images/sample.jpg"
alt=""
/>
<h2 data-forge-bind="title">Sample article title</h2>
<p data-forge-bind="summary">A short sample summary.</p>
<a data-forge-bind="url" href="post.html">Read the article</a>
</article>
</section>
</main>
The static values remain useful because the source page can still be previewed in a browser. The markers state which values the target generator should replace.
Keep the repeated item complete. If an image, title, or link sits outside the marked item only to make the sample layout look right, it may not repeat with the rest of the item after conversion.
Bind only values that are actually dynamic. Common Forge bindings include title, summary, author, date, featured_image, url, and category. A decorative label that never changes can remain ordinary HTML.
Give Single Pages a Clear Content Slot
List pages and single pages solve different problems. A list page repeats summaries. A single post or basic page needs a stable shell around a body supplied by the platform.
Forge documents data-forge-block="content" for the content region and data-forge-block="content-slot" for the point where the post or page body belongs:
<main data-forge-block="content">
<article>
<header>
<h1 data-forge-bind="title">Sample page title</h1>
</header>
<div data-forge-block="content-slot">
<p>This sample body will be replaced by platform content.</p>
</div>
</article>
</main>
That content slot is important. Without it, a converter may know which title to replace but not where WordPress post content or a generator's rendered Markdown should appear.
Forge also documents content-body, protected, and preserve blocks for more advanced collapsing behavior. Start with the basic content and content-slot relationship. Add advanced markers only when the page structure requires them.
Normalize Links and Asset Paths
Theme output rarely lives at the same path as the static prototype. A relative link that works from pages/about.html may break when the target engine moves that content into another route.
Before conversion:
- Use one predictable asset directory
- Remove file paths that point outside the project
- Check nested pages for fragile
../chains - Decide which links are internal routes and which are external URLs
- Keep capitalization consistent because deployment filesystems may be case-sensitive
Forge provides data-forge-link for internal routes that should be rewritten using the selected engine's conventions:
<a href="about.html" data-forge-link="/about/">About</a>
This marker describes intent. The browser-preview link can remain in href, while Forge receives the production route separately.
Assets need the same attention. A converter can organize and rewrite documented asset references, but it cannot determine whether two similarly named files are accidental duplicates or which unused images should be removed.
Validate the Source Before You Convert It
A short source review catches problems more cheaply than debugging several generated templates.
Use this checklist:
- Open every representative source page directly in a browser.
- Confirm that each page has one clear role.
- Compare shared regions and resolve accidental markup differences.
- Check that a list has one complete marked item inside its loop.
- Check that every dynamic binding sits on the element that should receive the value.
- Confirm that single and basic page layouts contain a content slot.
- Follow internal links from nested pages.
- Verify that styles, scripts, fonts, and images load without relying on files outside the source folder.
- Validate the HTML and fix malformed nesting.
- Keep an untouched copy or Git commit so you can review exactly what conversion changes.
The goal is not to decorate the source with every available marker. The Forge Data Markers reference notes that most sites need partials, a few blocks, and optional loops and bindings.
Where Forge Fits
Forge uses the structural hints in ordinary HTML to create editable files for a selected supported target. The generated syntax and file organization depend on that target.
Forge does not repair an incomplete content model, migrate existing content, or remove the need to understand the target platform. A missing content slot or inconsistent page role can still produce incomplete output. Inspect the generated files and run the target platform's own preview or build process.
That narrower role is useful. Your static source remains understandable in a browser, while the markers describe enough intent to turn repeated manual template work into a reviewable conversion step. The Forge overview explains that place in the wider workflow.
Frequently Asked Questions
Does every HTML page need Forge markers?
No. Start with representative layouts and mark only the regions that have structural meaning during conversion. Repeating the same marker plan across equivalent pages usually creates maintenance work without adding information.
Should I split partials into separate HTML files first?
Not necessarily. Forge can recognize marked partial regions in your source HTML. Separate source partial files may still make sense when your existing toolchain already supports them, but they are not required merely to describe the regions.
Can a converter infer loops from repeated items?
Repeated markup suggests a pattern to a person, but it does not fully describe the collection, the repeating item, or the dynamic fields. Explicit loop, item, and binding markers remove that ambiguity.
Is clean HTML enough for theme conversion?
Clean, valid HTML is the foundation. Conversion also needs page roles and dynamic intent. A perfectly valid row, card, or other item does not say whether it repeats, which field supplies its title, or how its link should be generated.
What to Do Next
Prepare one home page, one list page, one single page, and one basic page before working through an entire site. Then download an established sample from Forge Getting Started and compare its markers and generated files with your own plan.
If those four page roles convert cleanly, the rest of the site becomes a controlled extension of a known structure instead of a collection of exceptions.