Migrate a static HTML view to Pug without carrying over unsafe behavior

Problem

A legacy HTML page often relies on global scripts, inline onclick strings, document IDs, relative assets, server-injected values, form endpoints, and CSS loaded by a parent layout. Mechanical conversion can preserve the visible tree while carrying unsafe URLs and obsolete behavior into valid Pug. It can also hide changes made by the HTML parser or encourage developers to invent template logic before defining its data source. A safe migration separates syntax conversion from behavior redesign and proves the final render inside the real application.

When to use this

• A reviewed static or server-rendered HTML view must move into an Express application that uses Pug.
• One card, form, table, navigation section, email preview, or SVG fragment needs a Pug draft before application data is connected.
• A legacy template audit needs to expose inline events, active URLs, scripts, malformed nesting, and page-level dependencies.
• A team wants a repeatable checklist for migrating several HTML views without treating generated templates as sanitized or finished code.

Steps

1. Step 1

   Choose one view and inventory everything it depends on

   Select the smallest coherent view or fragment that completes one user task. Record parent layouts, stylesheets, scripts, fonts, images, relative links, form actions, IDs queried by code, browser storage, global variables, server values, authentication assumptions, and error states. Remove secrets, customer data, private hosts, and production tokens from the conversion fixture. Decide whether the destination owns a complete document or an included fragment before retaining doctype, html, head, and body.

2. Step 2

   Capture the current render and behavior as a baseline

   Render the source in its working environment and note heading order, labels, alt text, tab order, keyboard activation, form validation, loading and failure states, narrow-screen layout, and network requests. Save representative assertions or screenshots. Inspect the browser-parsed DOM as well as the original file because malformed HTML may already be normalized. This baseline defines what must remain and what legacy behavior should be intentionally removed.

3. Step 3

   Convert the source and investigate every warning

   Open HTML to Pug in Markup Conversion Workbench and convert the reviewed source. Compare tags, nesting, text spaces, comments, attributes, SVG, template content, and document wrappers. Investigate parser-normalization notices, removed formatting whitespace, legacy doctypes, script or style elements, noscript blocks, inline on-event attributes, javascript or active data URLs, and template-looking markers. Syntax-validated output is only a migration draft; do not suppress a warning because the first render looks similar.

4. Step 4

   Replace preserved active behavior with an application design

   Remove inline event strings and global DOM calls. Move behavior into named client modules or framework components with explicit inputs, error handling, and tests. Replace javascript URLs with approved navigation, validate form destinations, and decide whether scripts belong in the layout, a bundled client entry, or nowhere. Apply a defined URL and content trust policy. If source content is not fully trusted, sanitize it at the ingestion boundary rather than relying on conversion.

5. Step 5

   Define Pug locals and introduce dynamic syntax deliberately

   List every value the route supplies and define its type, required status, default, escaping rule, and empty or error state. Add variables, conditions, loops, includes, mixins, and inheritance only where this contract requires them. Keep user-controlled values escaped, avoid unescaped interpolation without a documented sanitizer, and test missing or adversarial values. Move stable layout into shared templates only after the standalone render matches the baseline.

6. Step 6

   Compile, render, and verify the destination view

   Run the project's Pug compile, formatter, linter, tests, and production build. Parse or snapshot the rendered HTML rather than snapshotting only Pug source. Exercise normal, empty, long, Unicode, invalid, loading, and failure data; test routes, assets, forms, keyboard use, accessible names, focus, 390px mobile layout, Content Security Policy, and expected network requests. Review the source-to-render diff and active-code resolutions before merging or publishing.

Example

<form class="profile" action="/profiles" method="post"><label for="name">Name</label><input id="name" name="name" value="Ada" required><button onclick="trackSave()" type="submit">Save</button></form>

Convert the structure, remove the preserved onclick attribute, supply the current name through an escaped Pug local, keep a real label and POST action, and attach approved analytics from the application layer. Test missing and long names, validation failure, keyboard submission, CSRF handling, server errors, and the rendered form under the production CSP.

Common mistakes

FAQ