How to Add JSON-LD Schema to a Static Site

June 19, 2026 · 12 min read · How-to

Structured data helps search engines interpret your pages—article headlines, FAQs, organization name, and site search potential. JSON-LD is Google's recommended format: a <script type="application/ld+json"> block in <head> without altering visible HTML. Static sites implement it the same way frameworks do—you paste or generate JSON. This how-to follows schema.org types and Google's structured data guidelines for common LaunchStatic page patterns.

Choose the right schema type per page

Match schema to visible content—misleading markup can trigger manual actions. Use WebSite on the homepage, Organization in a sitewide partial, Article or TechArticle on guides, and FAQPage only when FAQs are user-visible on that URL. Product landing pages may qualify for SoftwareApplication if you disclose price and operating system honestly.

Add Organization and WebSite on the homepage

Combine related entities with @graph so you declare one JSON-LD script.

<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@graph": [
    {
      "@type": "Organization",
      "name": "Example Inc",
      "url": "https://example.com",
      "logo": "https://example.com/assets/img/logo.png",
      "contactPoint": {
        "@type": "ContactPoint",
        "email": "hello@example.com",
        "contactType": "customer support"
      }
    },
    {
      "@type": "WebSite",
      "name": "Example",
      "url": "https://example.com"
    }
  ]
}
</script>

Use HTTPS logo URLs at least 112×112 px. Keep email addresses current with your contact page.

Mark up articles and how-to guides

Article schema supports headline, datePublished, author, and image. Align values with on-page meta and Open Graph tags.

<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@type": "Article",
  "headline": "How to Deploy a Static Site",
  "description": "Step-by-step deploy guide for HTML landing pages.",
  "datePublished": "2026-06-19",
  "dateModified": "2026-06-19",
  "author": {
    "@type": "Organization",
    "name": "Example Inc"
  },
  "publisher": {
    "@type": "Organization",
    "name": "Example Inc",
    "logo": {
      "@type": "ImageObject",
      "url": "https://example.com/assets/img/logo.png"
    }
  },
  "mainEntityOfPage": "https://example.com/how-to/deploy.html"
}
</script>

LaunchStatic's article renderer injects similar JSON automatically when you generate pages from Python content modules—hand-authored HTML should mirror the same fields.

Implement FAQPage for visible FAQs

FAQ rich results require questions and answers displayed to users, not hidden SEO text. Map each accordion or heading to a Question entity.

{
  "@context": "https://schema.org",
  "@type": "FAQPage",
  "mainEntity": [
    {
      "@type": "Question",
      "name": "Do I need a backend for forms?",
      "acceptedAnswer": {
        "@type": "Answer",
        "text": "No. Services like Formspree handle POST requests from static HTML."
      }
    }
  ]
}

Answer text must be plain language without misleading promises. Keep answers concise; Google may truncate verbose blocks.

Validate before requesting indexing

Use Google's Rich Results Test and Schema Markup Validator (schema.org). Fix parse errors—trailing commas are invalid in JSON. Confirm the tested URL is publicly reachable; validators fetch live pages. After deploy, monitor Search Console Enhancements for FAQ or Article warnings.

Avoid duplicate and conflicting graphs

Multiple JSON-LD scripts on one page are allowed if they describe distinct entities, but conflicting headlines confuse parsers. Prefer one @graph per page when types relate to the same content. Do not duplicate microdata attributes and JSON-LD for the same properties unless you maintain both carefully—pick JSON-LD for static simplicity.

Maintain schema when content changes

Update dateModified when you revise guides. If you remove an FAQ from the page, remove its Question entity the same deploy. Automate injection via templates or static site generators to prevent drift between visible copy and structured data.

  • JSON validates without syntax errors
  • headline matches visible H1
  • FAQ schema only on pages with visible Q&A
  • URLs in schema use production HTTPS host
  • Rich Results Test passes for target types

BreadcrumbList for guide hierarchies

How-to and guide pages benefit from BreadcrumbList JSON-LD mirroring visible breadcrumbs. Declare itemListElement entries with position, name, and item URL. This reinforces site structure for crawlers interpreting deep content hubs like /how-to/ and /guides/.

{
  "@type": "BreadcrumbList",
  "itemListElement": [
    {"@type": "ListItem", "position": 1, "name": "Home", "item": "https://example.com/"},
    {"@type": "ListItem", "position": 2, "name": "How-to", "item": "https://example.com/how-to/"},
    {"@type": "ListItem", "position": 3, "name": "Add JSON-LD", "item": "https://example.com/how-to/add-json-ld-schema-static.html"}
  ]
}

SoftwareApplication for product landings

If your static page markets downloadable software or a SaaS trial, SoftwareApplication schema can describe operating system, application category, and offers. Only include offers with price and currency when the on-page pricing section matches exactly—Google penalizes inconsistent structured data. For pre-launch waitlists without public pricing, omit price fields rather than fabricating zero-dollar offers.

HowTo schema for step articles

Tutorial pages like this one can add HowTo schema listing steps matching visible ordered lists. Each HowToStep needs a name and text aligned with on-page instructions. Do not mark up steps that exist only in schema—Google's rich result policies require parity with user-visible content. Combine HowTo with Article in a @graph when both types describe the same page responsibly.

Testing in staging

Rich Results Test fetches live URLs. Deploy schema changes to a public preview or production before validating—localhost JSON will not be crawled. Keep a changelog entry when schema types change so you can correlate Search Console enhancement warnings with specific git commits.

Validate JSON with python -m json.tool before embedding in HTML. A trailing comma breaks the entire graph and silently removes structured data benefits until someone notices missing rich results weeks later.

Reuse the same Organization object across pages with identical @id URLs (for example https://example.com/#organization) so parsers connect entities consistently across your static site.

When LaunchStatic's Python renderer generates articles for you, inspect the emitted JSON-LD in one output file before bulk publishing—template bugs replicate across every page instantly.

Mirror Open Graph og:title and og:description with Article schema fields—divergent metadata confuses social previews and search snippets alike.

Add dateModified when you materially update guides—stale dates misrepresent freshness to crawlers even when body copy changed significantly. Re-run Rich Results Test after each schema edit.

Related: Generate sitemap.xml Write converting headlines Pillar guides Privacy policy how-to

Is JSON-LD better than microdata?

For hand-written static HTML, JSON-LD is easier to maintain and is Google's recommended format.

Will schema guarantee rich snippets?

No. Eligibility depends on quality, policy compliance, and Google's discretion.

Can I add schema without JavaScript execution?

Yes. JSON-LD is inert script content; crawlers read it without running your site JS.

Should every page use Article schema?

Use Article on editorial content. Use WebPage or more specific types on utility pages like contact or pricing.

Structured pages, faster

Generated LaunchStatic articles include JSON-LD and FAQ markup out of the box.

More how-to guides Browse templates