Quick Answer
A WordPress Custom HTML block checklist should confirm why raw markup is needed, who owns it, whether it contains scripts, iframes, forms, hidden text, non-crawlable links, broken attributes, unsupported embeds, or missing source notes, and whether the previewed output still matches the reader-facing article. For a small publisher, the best fit is a conservative register: block location, code purpose, provider or owner, visible reader value, link behavior, script or embed dependency, fallback plan, and next review trigger.
Custom HTML Decision Table
| Situation | Better operator choice | Evidence to keep |
|---|---|---|
| Standard block can do the job | Replace raw HTML with a normal WordPress block | Block name and reason |
| Raw HTML is needed for a provider snippet | Keep only if owner, source URL, and fallback are documented | Provider doc, page slug, and owner |
| Code is only meant to be displayed as text | Use a Code block, not executable HTML | Example purpose and reviewer note |
| Shortcode controls the output | Audit the shortcode owner before editing HTML around it | Shortcode, plugin, and dependency |
| Link markup is custom | Confirm crawlable a elements and descriptive anchor text | Destination, anchor, and rel decision |
| Script, iframe, or form is present | Check provider trust, privacy, layout, and failure behavior | Provider, loaded surface, and fallback |
| Hidden or keyword-heavy markup appears | Remove, rewrite, or make it visibly useful | Cleanup reason and source note |
Who Should Use This Checklist?
Use this checklist when a WordPress publisher, editor-operator, theme reviewer, content operations owner, or small AdSense-oriented site is reviewing posts, pages, template parts, widgets, reusable patterns, or imported content that contains Custom HTML blocks, Code blocks, Shortcode blocks, raw embed snippets, hand-written links, forms, iframes, badges, tables, or provider widgets.
This is WordPress site-operations guidance, not a security audit, privacy certification, accessibility certification, professional SEO consulting, legal advice, AdSense account advice, Search Console account advice, Bing Webmaster Tools account advice, or plugin development guidance. It does not change WordPress settings, theme files, plugins, custom code, Search Console, Bing Webmaster Tools, AdSense, payment settings, tax settings, DNS, hosting, or production content. The article is source-derived operator analysis from public WordPress and Google documentation. No private WordPress dashboard, editor session, theme file, plugin setting, page source, browser screenshot, Search Console property, AdSense account, analytics property, server log, or production URL was inspected for this article.
The operating problem is simple: Custom HTML is useful because it gives an editor a direct escape hatch. That escape hatch is also why it deserves a review. A single block can contain a provider widget, an old table, a hand-coded link, a tracking script, a hidden fragment, or markup that looked fine in the editor but fails on the public page. The goal is not to ban custom code. The goal is to make every raw-code block explainable, visible, and maintainable.
Step 1: Confirm Why Custom HTML Is Needed
WordPress Custom HTML documentation describes adding HTML directly through the block editor. That is different from choosing a standard Paragraph, Button, Table, Image, Embed, Code, or Shortcode block. Before editing the markup, the operator should ask whether raw HTML is still the smallest useful tool.
Use this first-pass review:
- [ ] Record the post, page, template, widget area, or pattern that contains the block.
- [ ] Name the visible purpose: table, widget, badge, form, embed, link group, callout, or layout helper.
- [ ] Check whether a standard WordPress block now covers the same need.
- [ ] Identify whether the HTML came from a provider, theme, plugin, older import, or editor.
- [ ] Confirm who owns updates when the snippet breaks.
- [ ] Leave the block unchanged until the owner and purpose are clear.
The safest cleanup is usually boring. If a normal block can replace the raw markup without losing reader value, use the normal block. If the raw snippet is still needed, keep it only with a short owner note and a review trigger.
Step 2: Separate Displayed Code From Executed HTML
WordPress Code block documentation is for displaying code as code. Custom HTML is for adding markup that the page may render. Shortcode blocks rely on a shortcode handler, often supplied by WordPress, a plugin, a theme, or custom code. Mixing those three concepts creates maintenance risk.
Use this distinction table:
| Block type | What the reader expects | Audit focus |
|---|---|---|
| Custom HTML block | Rendered markup, links, embeds, or layout | Output, dependencies, and policy fit |
| Code block | A visible code example | Escaping, readability, and context |
| Shortcode block | Output generated by a handler | Plugin/theme owner and fallback |
| Standard WordPress block | Native editor-managed content | Block settings and preview state |
If the article is teaching an HTML example, the Code block is usually clearer. If the article is rendering a provider snippet, Custom HTML may be appropriate. If a shortcode generates the output, editing the surrounding HTML without checking the shortcode owner can hide the real dependency.
Step 3: Check Links Before Checking Styling
Raw HTML often appears because an editor wants link behavior that the normal editor did not expose at the time. Google link guidance emphasizes crawlable links and useful anchor text. For operators, that means the link review comes before cosmetic styling.
Use this link checklist:
- [ ] Links use ordinary
aelements with a reachablehrefwhen the goal is crawlable navigation. - [ ] Anchor text tells readers where the link goes.
- [ ] External, sponsored, user-generated, or nofollow decisions are intentional and documented.
- [ ] Buttons or badges still have visible text or accessible labels.
- [ ] Links do not point to hidden sections, stale files, private dashboards, or temporary preview URLs.
- [ ] Internal links match the article's current related-reading plan.
Do not keep a custom link only because it looks good in the editor. If a link is important for readers, it should be visible, descriptive, and maintainable. If the link exists only inside a script-generated widget, record that limitation instead of pretending it is the same as an ordinary internal link.
Step 4: Identify Scripts, Iframes, Forms, And Provider Widgets
Some Custom HTML blocks are really dependency containers. They load a newsletter form, third-party badge, calculator, calendar, social embed, video iframe, survey, or analytics-adjacent widget. That does not make the block wrong, but it changes the review.
Use this dependency table:
| Dependency | Operator question | Better evidence |
|---|---|---|
| Script | Who provides it, and what happens if it fails? | Provider URL and owner |
| Iframe | Does it fit the page, mobile width, and reader task? | Source domain and fallback note |
| Form | Where does submitted data go? | Internal owner, not public secrets |
| Badge | Is it still current and non-sponsored? | Provider note and checked date |
| Widget | Does it add reader value beyond decoration? | Visible purpose and removal trigger |
| Inline style | Should this live in theme CSS instead? | CSS owner and scope |
Keep private implementation details out of the public article. Do not paste tokens, account IDs that reveal private systems, form endpoints with secrets, raw analytics payloads, or private dashboard URLs into source notes. A public checklist can say "record the provider and owner"; it should not expose credentials.
Step 5: Preview The Rendered Output And The Failure State
The Block Editor lets operators edit content before publishing, but an editor preview is not the same as a production browser check. Custom markup may depend on theme CSS, plugin scripts, cache behavior, content security rules, provider availability, or responsive width.
Use this output review:
- [ ] Preview the page in the editor and in a public-like preview if available.
- [ ] Check mobile width for tables, iframes, badges, and forms.
- [ ] Confirm the surrounding heading and paragraph still explain the raw block.
- [ ] Check whether the block leaves a blank gap if the provider fails.
- [ ] Confirm source notes, disclosures, and internal links remain visible.
- [ ] Record whether the review was a checklist requirement or a real page inspection.
Do not make fake testing claims. If the operator did not inspect a live URL, browser console, source HTML, or production preview, the public article should not say the site was tested. It should say what the checklist requires and what evidence a future operator should attach.
Step 6: Remove Hidden, Stale, Or Search-Only Markup
Google spam policies discuss deceptive hidden text, hidden links, cloaking, and other manipulative behavior. A normal responsive layout or provider widget is not automatically a spam problem. The risk appears when markup is kept for search systems rather than readers, when important caveats are hidden, or when visitors and crawlers receive materially different messages.
Use this policy-safe cleanup:
- [ ] Remove keyword-heavy text that is not useful to readers.
- [ ] Remove hidden links that readers cannot reasonably find.
- [ ] Restore source notes, disclosures, limitations, and correction notes if they were hidden.
- [ ] Do not use Custom HTML to show one answer to crawlers and another to readers.
- [ ] Avoid hiding affiliate, sponsor, or paid-placement context if future articles ever use it.
- [ ] Keep private, legal, medical, financial, account, payment, tax, or personal data out of public markup.
The better rule is simple: if the markup matters, make its reader value visible. If it should not be public, remove it from the public post workflow. If it belongs to a private tool, keep it in an internal system rather than a public block.
Step 7: Document The Owner And Update Trigger
Custom HTML decays quietly. Providers change script URLs, browsers change behavior, plugins replace shortcodes, and editors forget why a block was added. A short register prevents the next operator from treating an unknown snippet as harmless decoration.
Use these fields:
| Field | Example value |
|---|---|
| Page or template | Pricing comparison article, footer widget, source page |
| Block location | Below comparison table, sidebar, template part, pattern |
| Purpose | Provider badge, form, custom table, HTML example |
| Owner | Editor, plugin owner, theme owner, provider owner |
| Source URL | Official provider or WordPress documentation |
| Dependencies | Script, iframe, shortcode, CSS class, form endpoint |
| Reader fallback | Plain link, screenshot replacement, removal note |
| Recheck trigger | Theme update, plugin update, provider change, failed preview |
The register does not need to be heavy. A small markdown note, spreadsheet row, or front-matter comment can be enough. What matters is that the next reviewer can tell whether the block is still useful and who is allowed to change it.
Step 8: Decide Whether To Keep, Replace, Or Retire The Block
After the review, choose one action. Do not leave every raw-code block in a vague "monitor later" state.
Use this action table:
| Finding | Action |
|---|---|
| Native block now works | Replace with the native block and note the change |
| Provider snippet is current and useful | Keep with owner, source, fallback, and review date |
| Code should be shown as an example | Convert to a Code block |
| Shortcode owner is unknown | Block publication until owner is identified |
| Link markup is weak | Rewrite links with descriptive anchors |
| Script or iframe is decorative | Remove or replace with a plain link |
| Hidden or manipulative markup appears | Remove and document the cleanup |
This keeps Custom HTML from becoming a hidden junk drawer. A raw block is acceptable when it has a current purpose. It is risky when it survives only because nobody wants to touch it.
What Should A WordPress Custom HTML Block Audit Include?
A WordPress Custom HTML block audit should include a block inventory, purpose check, native-block replacement decision, Code block versus Custom HTML distinction, shortcode owner review, link and anchor review, script or iframe dependency review, preview and failure-state check, hidden-markup cleanup, owner, fallback, and next review trigger. The audit is ready when a future operator can explain why the raw markup exists, what reader task it supports, what dependency it loads, and when it should be reviewed again.
Common Questions
Is the Custom HTML block bad for WordPress SEO?
No. The block itself is not the issue. Risk comes from weak links, hidden text, unsupported embeds, broken scripts, duplicate content, missing source notes, or markup that gives readers a worse page than the editor intended.
Should every raw HTML snippet be replaced?
No. Replace raw HTML when a standard block does the same job more safely. Keep it when the snippet has a current reader purpose, a known owner, an attributable source, a fallback plan, and a review trigger.
Is a Code block the same as Custom HTML?
No. A Code block is for displaying code examples. A Custom HTML block is for rendering markup in the page. If readers should see the code as an example, use a Code block. If the page needs to render the markup, audit it as Custom HTML.
Can this checklist prove a live page was tested?
No. It is source-derived operations guidance. It does not inspect a private editor, production page, browser console, page source, Search Console property, analytics account, AdSense account, server log, or provider dashboard. If future operators add live evidence, keep the claims limited to that verified page.
What should stay out of public source notes?
Do not publish credentials, tokens, form secrets, account IDs that expose private systems, private dashboard links, unpublished article bodies, personal data, raw analytics payloads, payment details, tax details, or security-sensitive configuration.
AdSense And Policy Fit
This checklist supports AdSense-safe publishing because it keeps raw-code blocks source-aware, reader-visible, and maintainable without encouraging scraped prose, hidden text, cloaking, fake engagement, automated traffic, click inducement, affiliate claims, sponsored recommendations, account setting changes, or unsupported testing claims. Custom HTML should help a legitimate reader task; it should not be used to hide weak content or manufacture signals.
Source Notes
- https://wordpress.org/documentation/article/custom-html/ checked 2026-06-16; used for source-derived analysis of Custom HTML block purpose, insertion, preview behavior, and raw markup review.
- https://wordpress.org/documentation/article/code-block/ checked 2026-06-16; used for source-derived analysis of Code block usage and why displayed code examples should be separated from rendered HTML.
- https://wordpress.org/documentation/article/shortcode-block/ checked 2026-06-16; used for source-derived analysis of Shortcode block usage and why shortcode ownership should be reviewed before editing raw-code sections.
- https://wordpress.org/documentation/article/wordpress-block-editor/ checked 2026-06-16; used for source-derived analysis of Block Editor review surfaces, document structure, settings panels, and publication workflow.
- https://wordpress.org/documentation/article/advanced-settings-overview/ checked 2026-06-16; used for source-derived analysis of HTML anchors, additional CSS classes, custom CSS availability, and block-level settings that can affect raw-code review.
- https://developers.google.com/search/docs/crawling-indexing/links-crawlable checked 2026-06-16; used for source-derived analysis of crawlable links, ordinary anchor markup, and descriptive anchor text in custom HTML.
- https://developers.google.com/search/docs/crawling-indexing/javascript/javascript-seo-basics checked 2026-06-16; used for source-derived analysis of JavaScript rendering considerations and why script-dependent content needs a visible fallback review.
- https://developers.google.com/search/docs/essentials/spam-policies checked 2026-06-16; used for source-derived analysis of hidden text, hidden links, cloaking, and deceptive search-manipulation boundaries.
- https://developers.google.com/search/docs/fundamentals/creating-helpful-content checked 2026-06-16; used for source-derived analysis of people-first content quality and why raw markup should support reader value rather than search-only text.
No private WordPress dashboard, editor session, Custom HTML block, page source, browser console, production URL, Search Console property, Bing Webmaster Tools account, AdSense account, analytics property, server log, provider dashboard, form endpoint, shortcode handler, plugin setting, theme file, payment setting, tax setting, or credential store was inspected for this article. If a future operator adds sanitized screenshots, public preview captures, console notes, source HTML snippets, provider changelog links, or plugin evidence, attach those artifacts internally and narrow public claims to that verified environment.
Internal Link Notes
Link to wordpress-embed-audit-checklist when the raw block loads iframe, video, social, or provider embed output. Link to wordpress-widget-area-cleanup-checklist when Custom HTML appears in sidebars, footers, or legacy widget areas. Link to wordpress-custom-css-audit-checklist when raw markup depends on CSS classes or inline styling. Link to wordpress-hidden-block-audit-checklist when raw markup hides text, links, disclosures, or source notes. Link to wordpress-internal-link-audit-checklist when custom anchors or buttons shape reader paths. Link to source-notes-workflow-for-blog-posts when the snippet needs a durable source register.
Update Note
Review this checklist every 60 days. Recheck official WordPress documentation for the Custom HTML block, Code block, Shortcode block, Block Editor, and advanced block settings. Recheck Google documentation for crawlable links, JavaScript SEO basics, spam policies, and helpful content before changing link, script, hidden-text, or source-quality guidance. Refresh earlier after a WordPress editor change, theme update, shortcode plugin change, provider script change, embed failure, layout break, Search Console warning, or discovery of unsupported raw markup in published articles.