SEO and structured data

You do not hand-write metadata or JSON-LD. Two calls in your layout print it, from the page, the document, the site’s configuration and the type’s schema.org mapping:

• head() prints the title, the meta description, the canonical link, hreflang alternates, the robots directive, rel=prev and rel=next, and the Open Graph and Twitter card tags.
• jsonld() prints the page’s structured data as one JSON-LD @graph whose entities reference each other by @id.

The sitemap and robots.txt are generated from site.yaml.

A minimal setupCopy Anchor Link

{# templates/_shared/base.html #}
<!doctype html>
<html lang="{{ locale.code }}" dir="{{ locale.direction }}">
<head>
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width, initial-scale=1">
  {{ head() }}
  {{ jsonld() }}
  {{ feedLinks() }}
  {{ assets.css('main') }}
</head>
<body>{% block body %}{% endblock %}</body>
</html>

# config/sites/main/site.yaml
seo:
  title_template: "{{ title }} | {{ site.name }}"
  default_image: /img/share.jpg
  sitemap: { enabled: true }
  robots: { enabled: true }
  structured_data:
    organisation: { type: TouristInformationCenter, logo: /logo.svg }

# config/schema/event.yaml (a type's mapping to schema.org)
structured_data:
  type: Event
  map:
    description: description
    image: heroImage
    offers: bookingUrl
    location: venue
    organizer: { value: "Riverside Arts Centre" }

engine-dmo check warns when a layout’s <head> has no head() and its own tags have no meta description. The base.html that engine-dmo init writes has neither, so a new project prints this warning until you replace its <title> and canonical link with {{ head() }}. The warning is not counted in the check’s summary line (Testing).

head()Copy Anchor Link

head() prints, in this order:

The response also carries Content-Language with the page’s locale.

A type with no summary field and no seo field has no description. The core page type declares only title and slug, so extend it with a summary (engine-dmo dev field add page summary --type text --param multiline=true --apply) or an seo field before you rely on head() for the home, about and contact pages.

TitlesCopy Anchor Link

seo.title_template takes two placeholders, written exactly as {{ title }} and {{ site.name }} (with or without the inner spaces). Nothing else in it is evaluated. A page without a title gets the site’s name.

To let editors write a search title and description per document, give the type a field of type seo (the seo field). It stores title, description, og_title and og_description, and warns editors past 60 and 160 characters (title_max, description_max).

entry.seo gives the same decisions to a template that writes its own tags: title (the title template applied), description (the summary as plain text), image (the site’s default image, absolute), noindex and canonical. A type that declares its own field named seo keeps its field’s value there instead.

The share imageCopy Anchor Link

The Open Graph image is the image field the type’s structured_data.map names as image. When config/images.yaml defines a transform named social, the image is cut through it (its first width) and og:image:width and og:image:height are printed; otherwise the original is shared. A common definition:

# config/images.yaml
transforms:
  social:
    width: 1200
    aspect: "1.91:1"
    formats: [jpeg]

Without a mapped image, seo.default_image (a path on the site) is shared, absolute.

width: 1200 makes social a fixed-width transform, which is right for a share image of one known size. A transform written with widths: { min, max } instead is accepted too; the share image is then its first width. Both forms are described under A transform.

Canonical URLsCopy Anchor Link

page.canonical is absolute, on the site’s first configured domain with the scheme of server.base_url, never the host the request came in on.

hreflangCopy Anchor Link

Alternates list only locales in which the page is published with a live address on this site, never another site’s pages. x-default is the site’s default locale when the page exists in it, else the first alternate. With one locale, no alternates are printed. Each item of page.alternates has locale, hreflang (the code in lower case), url and path.

noindexCopy Anchor Link

The robots directive is noindex, follow when any of these holds; none is configurable:

• the page is a filtered view of an index (any facet selected);
• the page is a preview;
• the site is in embed-only mode (embed.only), which also sends X-Robots-Tag: noindex, follow;
• engine.environment is staging.

page.noindex is true for a filtered index and a preview.

jsonld()Copy Anchor Link

jsonld() prints one <script type="application/ld+json"> holding the page’s @graph:

Every URL in it is on the configured domain. jsonld(entry) prints one document’s entity alone, for a card or a fragment. Under engine-dmo serve --dev the graph is checked against the vocabulary as it is printed, and an unknown type or property fails the render.

Guides and collections also carry the graph as entry.jsonld, and landing pages as landing.jsonld. Print either with the json filter inside a script element, if you build the head yourself:

<script type="application/ld+json">{{ entry.jsonld|json }}</script>

Site-wide nodesCopy Anchor Link

# config/sites/<key>/site.yaml
seo:
  structured_data:
    organisation:
      type: TouristInformationCenter     # an Organization subtype; Organization when not given
      name: Visit Wyndmouth              # site.organisation, else the site's name, when not given
      logo: /logo.svg                    # a path on the site or an absolute URL
      same_as: ["https://example.org/wyndmouth"]
    breadcrumbs: true
    search: true

A type that is not an Organization is an error: PerformingArtsTheater is not an Organization; the site's publisher is one, such as TouristInformationCenter.

Mapping a type to schema.orgCopy Anchor Link

A type’s structured_data block in its schema file declares what its documents are:

structured_data:
  type: TouristAttraction                 # a schema.org type, or a list
  subtype:                                # an extra type by a select field's value
    field: category
    values: { stay: LodgingBusiness, eat-drink: Restaurant, shop: Store }
  map:
    description: description
    image: heroImage
    geo: location
    address: address
    telephone: phone
    sameAs: website
    openingHoursSpecification: openingHours
    amenityFeature: accessibility
    isAccessibleForFree: true
    eventAttendanceMode: { value: "https://schema.org/OfflineEventAttendanceMode" }
  faq: { items: body.faq.items, question: question, answer: answer }

Choosing a typeCopy Anchor Link

Pick the most specific schema.org type that describes what a visitor would go to, do or read. The entity’s @id suffix follows from the type, so other nodes can reference it:

A walking route can reasonably be either: TouristAttraction with geo mapped to its start point puts it on the map as a place, and TouristTrip describes the journey. Choose one; a list of both ([TouristAttraction, TouristTrip]) gives one node both types, with the #place id.

# config/schema/walk.yaml
structured_data:
  type: TouristAttraction
  map:
    description: summary
    image: heroImage
    geo: startPoint

Without a line of its own the engine fills name from the title and url from the canonical address; on a creative work headline, datePublished, dateModified and inLanguage; on a place containedInPlace, the place above it in the hierarchy; on an event its dates and status from its occurrences.

What each field type givesCopy Anchor Link

A repeater, blocks, form, seo, video or geo shape field cannot be a source. A property the document’s own types do not take is left out of its entity.

ValidationCopy Anchor Link

engine-dmo check validates every mapping against the schema.org vocabulary the engine ships:

The rich-result warnings are guidance from a dataset versioned with the engine, never a guarantee.

The sitemapCopy Anchor Link

seo:
  sitemap:
    enabled: true
    max_urls_per_file: 10000

It is served at /sitemap.xml, or at the path special.sitemap gives in routes.yaml, with Cache-Control: public, max-age=3600. It lists every document with a live page on the site in each enabled locale (lastmod the later of its locale’s and its shared revision), each type’s index page in every enabled locale, and the live landing pages. A page in more than one locale lists its alternates on this site as xhtml:link. A site in embed-only mode lists nothing. The sitemap lists pages only: it has no image or video entries. A filtered index page (any facet selected) is never listed, since it is noindex; to keep a whole path out of search engines, use robots.disallow.

robots.txtCopy Anchor Link

seo:
  robots:
    enabled: true
    disallow: ["/search"]
    allow: ["/search/help"]
    agents:
      - { user_agent: GPTBot, disallow: ["/"] }

The admin, the member portal (with the portal module) and the tracked-redirect paths are always disallowed, and repeated in every named group, since a crawler that finds its name reads only its own group. The sitemap is declared when it is enabled. A staging environment serves a blanket Disallow: /. engine-dmo check refuses a rule that is not a path, a group for *, a crawler named twice and a group that says nothing.

FeedsCopy Anchor Link

feedLinks() in the head prints the <link rel="alternate"> tags of the site’s feeds in the request locale, for feed readers to discover. Feeds are configured on a route (routes reference); see Links and URLs for feedUrl().

Checking the outputCopy Anchor Link

• engine-dmo render /whats-on/film-club --json returns the page’s HTML with the head and graph as printed (Testing).
• A template test can assert on the graph: jsonld: { "@type": "Event", "name": "Film Club" } passes when some object in the page’s JSON-LD holds those values.

RelatedCopy Anchor Link

• Site configuration reference: every seo key.
• Landing pages: their own titles, descriptions and graphs (engine-dmo).
• Images: the social transform.