Schema.org

Schema.org provides structured data that helps search engines understand your content and display rich, engaging results.

Alpha automatically generates a valid and extensive <script type="application/ld+json"> using sensible defaults, which you can further refine for more accurate schema via frontmatter.

How to populate

To generate a unique schema for each page, simply fill the relevant frontmatter keys that match your content.

For example, if you add an author:

# Authoring
author = "John Smith"

Alpha will generate this schema snippet:

  "author": {
    "@type": "Person",
    "name": "John Smith"
  },

If the author is omitted, the schema defaults to:

  "author": {
    "@type": "Organization",
    "name": "[Your Site Title]"
  },

The same behavior applies to most frontmatter keys: Alpha will populate or omit schema entries as appropriate. In most cases, you only need to fill the frontmatter as you normally would. Alpha takes care of the rest.

Schema-specific keys

Some frontmatter keys are used strictly for SEO and schema purposes:

# Advanced SEO
seo_type = ""
seo_image = ""

seo_type

The seo_type frontmatter key overrides the default @type value in the schema.

Alpha uses these defaults:

"@type": "Website",       // For homepage
"@type": "CollectionPage",// For _index.md if paginate = true
"@type": "WebPage",       // For _index.md if paginate = false or for layout = "utility"
"@type": "Article",       // For every other page

You can override this with a more specific type if needed.

Attention

Only use appropriate @types values as referenced in the official schema.org documentation.
If in doubt, the defaults are generic enough to cover almost all use cases.

seo_image

The seo_image frontmatter key is used for rich results and social sharing previews.

Place the image in the page bundle or in the assets/img/ folder.
Recommended dimensions: 1200×630px.
Alpha will verify the image size and resize it if different; if the aspect ratio is incorrect, Alpha will use the original, un-resized image to avoid distortion. In your local development, LiVa will alert you to this mismatch. This ensures images will appear properly in rich results and social previews.

Global Overrides

In the config/_default/params.toml you can define some global values for the schema. Review the params.toml reference for more information.

Validation

The schema generated by Alpha is tested thoroughly for validity, but is still recommended to validate each published page.

Extensive Example

The following is the generated schema for the current page. It is populated only by frontmatter values.

<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@type": "TechArticle", 
  "author": {
    "@type": "Person",
    "name": "oxypteros" 
  },
  "copyrightHolder": {
    "@type": "Person",
    "name": "oxypteros"
  },
  "copyrightYear": "2025", 
  "datePublished": "2025-09-12T15:51:19+02:00", 
  "description": "Learn how to set schema.org for your pages in the Alpha Hugo theme.", 
  "headline": "Schema.org",
  "image": {
    "@type": "ImageObject",
    "height": 630,
    "url": "https://alpha.oxypteros.com/img/schema-alpha-docs-seo.png", 
    "width": 1200
  },
  "inLanguage": "en",
  "isPartOf": {
    "@type": "CreativeWorkSeries",
    "name": "Alpha Docs",
    "url": "https://alpha.oxypteros.com/series/alpha-docs/"
  },
  "license": "https://creativecommons.org/licenses/by-sa/4.0/",
  "mainEntityOfPage": {
    "@id": "https://alpha.oxypteros.com/docs/seo/schema/",
    "@type": "WebPage"
  },
  "name": "Schema.org",
  "position": 45,
  "publisher": {
    "@type": "Organization",
    "logo": {
      "@type": "ImageObject",
      "url": "https://alpha.oxypteros.com/alpha/img/logo-alpha.svg"
    },
    "name": "Alpha Theme",
    "url": "https://alpha.oxypteros.com/"
  },
  "timeRequired": "PT3M",
  "url": "https://alpha.oxypteros.com/docs/seo/schema/",
  "wordCount": 542
}
</script>
<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@type": "BreadcrumbList",
  "itemListElement": [{
        "@type": "ListItem",
        "position":  1 ,
        "name": "Alpha Theme",
        "item": "https://alpha.oxypteros.com/"
      },{
        "@type": "ListItem",
        "position":  2 ,
        "name": "Alpha Docs",
        "item": "https://alpha.oxypteros.com/docs/"
      },{
        "@type": "ListItem",
        "position":  3 ,
        "name": "SEO \u0026 Social",
        "item": "https://alpha.oxypteros.com/docs/seo/"
      },{
        "@type": "ListItem",
        "position":  4 ,
        "name": "Schema.org",
        "item": "https://alpha.oxypteros.com/docs/seo/schema/"
      }]
}
</script>