Frontmatter Reference

Every markdown file under content/<type>/ starts with a YAML frontmatter block delimited by ---. The frontmatter declares everything pageflare needs to know about the page that isn’t in the body itself.

---
title: "Using Pageflare with Astro"
description: "Generate SEO metadata, canonicals, and Open Graph tags from Markdown."
draft: false

seo:
  canonical: "https://example.com/docs/astro/pageflare/"
  robots: "index,follow"
  keywords: ["pageflare", "astro", "seo"]
  og:
    image: "/content/assets/og-astro.png"
    type: article
    image_alt: "Pageflare + Astro"
  twitter:
    card: "summary_large_image"
    creator: "@shivakumar"

taxonomy:
  tags: ["seo", "astro"]
  category: "guides"

publish:
  date: 2026-05-06
  updated: 2026-05-12
  author: "Shiva Kumar"
---

The only required field is title. Everything else has sensible defaults or is optional.

Top-level fields

Field	Type	Description
`title`	string	The page title. Used as `<title>` and as the default `seo.title` and `og:title`.
`description`	string	Plain-text page summary. Used as `<meta name="description">` and as the default `seo.description` and `og:description`.
`slug`	string	Override the resolved URL absolutely. See URL resolution precedence.
`draft`	boolean	When `true`, the page is excluded from `sitemap.xml` and `llms.txt`. The HTML is still optimized — drafts are about discoverability, not deployment. Default `false`.

`seo:` — head tag overrides

The seo: block lets a page override what gets injected into <head> without changing the top-level title / description (which often double as the body H1 and lede). Every field is optional — anything you leave out falls back to either the top-level field or site.yaml -> defaults.seo.

Field	Default	Description
`seo.title`	top-level `title`	Override the `<title>` tag specifically — useful when the H1 is long and you want a shorter SERP title.
`seo.description`	top-level `description`	Override `<meta name="description">`.
`seo.canonical`	absolutized page URL	Absolute canonical URL. Set this explicitly when the same content exists at multiple URLs.
`seo.robots`	`defaults.seo.robots`	`index,follow` / `noindex,nofollow` / etc.
`seo.keywords`	`[]`	Comma-joined into `<meta name="keywords">`. Modern crawlers largely ignore this — kept for completeness.
`seo.hreflang`	`{}`	Map of `locale → href` for translated versions. Emitted as `<link rel="alternate" hreflang="...">` tags.

`seo.og` — Open Graph

Field	Default	Description
`seo.og.image`	`site.default_og_image`	Image for `og:image`. Path or absolute URL.
`seo.og.image_alt`	—	`og:image:alt` text.
`seo.og.type`	inferred from content type	One of `article` / `website` / `product` / `profile`. Drives both `og:type` and the JSON-LD page type — see JSON-LD.

`seo.twitter`

Field	Default	Description
`seo.twitter.card`	`defaults.seo.twitter.card`	`summary` / `summary_large_image` / `app` / `player`.
`seo.twitter.creator`	—	`@handle` of the content author.

`seo.jsonld` — custom schema.org overrides PRO

An array of YAML mappings that emit as additional <script type="application/ld+json"> blocks, one per entry. Use this for schema.org types pageflare doesn’t auto-build — FAQPage, HowTo, Recipe, Event, Course, etc.

seo:
  jsonld:
    - "@type": FAQPage
      mainEntity:
        - "@type": Question
          name: "What is pageflare?"
          acceptedAnswer:
            "@type": Answer
            text: "An SEO toolkit for static and edge-deployed sites."

@context: "https://schema.org" is added automatically when absent. See JSON-LD overrides for details.

`taxonomy:` — tags and category

Field	Type	Description
`taxonomy.tags`	string[]	Free-form tags. Surfaces in templates, doesn’t affect SEO output directly.
`taxonomy.category`	string	Single category, e.g. `guides`, `tutorials`.

Taxonomy is metadata for templating today; future versions may emit category/tag archive pages.

`publish:` — dates and authorship

Field	Type	Description
`publish.date`	ISO date (`YYYY-MM-DD`)	Original publish date. Emitted as `Article.datePublished` in JSON-LD and as `<lastmod>` in `sitemap.xml` when `publish.updated` is unset.
`publish.updated`	ISO date (`YYYY-MM-DD`)	Last meaningful edit. Wins over `publish.date` for `<lastmod>`. Emitted as `Article.dateModified`.
`publish.author`	string	Author display name. Emitted as `Article.author.name`.

When neither field is set, pageflare uses the file’s mtime as a last resort for <lastmod>.

`navigation:` — sidebar / menu hints

Reserved for sidebar generation in template integrations. Not consumed by the SEO/JSON-LD pipeline.

Field	Type	Description
`navigation.title`	string	Short label for sidebars / menus.
`navigation.order`	integer	Sort order within a section.
`navigation.parent`	string	Parent page URL for nested navigation.

Idempotency markers

Every tag pageflare injects carries a data-pf="<field>" attribute, e.g. <meta name="description" data-pf="description"> or <script type="application/ld+json" data-pf="jsonld.article">. The next pipeline run strips and re-emits anything carrying data-pf — so running pageflare twice produces identical output.

If you hand-author SEO tags without the data-pf marker, they’re left alone. This lets you mix pageflare-managed and hand-authored head content without conflict.

Round-tripping with `seo fix --bootstrap-content`

If your site has hand-authored SEO meta tags but no content/ directory yet, you can reverse-engineer markdown content from existing HTML:

pageflare seo fix --bootstrap-content

The bootstrap pass scans optimized HTML pages, extracts <title>, <meta name="description">, canonical URLs, JSON-LD blocks (skipping pageflare-managed ones), and writes them to content/pages/*.md with valid frontmatter. After running, you have a starting point you can edit by hand and re-run the pipeline against.

Content Model — directory layout, site.yaml, URL patterns.
JSON-LD — how seo.og.type and content type map to schema.org page types.

Frontmatter Reference

Top-level fields

seo: — head tag overrides

seo.og — Open Graph

seo.twitter

seo.jsonld — custom schema.org overrides PRO

taxonomy: — tags and category

publish: — dates and authorship

navigation: — sidebar / menu hints