Headless Building Blocks — WordPress + Astro demo

01 — Core WordPress fields

The editor's own content

Sourcepage.content · page.featuredImage · page.readingTime

Field typesWYSIWYG · Media · Computed field (PHP)

GraphQL

page(id: $uri, idType: URI) {
  title
  content
  readingTime          # added with register_graphql_field()
  featuredImage { node { sourceUrl altText mediaDetails { width height } } }
}

4 min read — computed in PHP and exposed as a first-class GraphQL field, so the front end does no content maths of its own.

Placeholder body copy

This block is the WordPress content field — everything an editor types into the main editor arrives as a single HTML string. The front end renders it verbatim, which is why the markup below is styled by a WYSIWYG stylesheet rather than by components.

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Integer posuere erat a ante venenatis dapibus posuere velit aliquet. Nullam quis risus eget urna mollis ornare vel eu leo.

Lists, headings and links keep their editor formatting.
Images pasted into the editor arrive as raw <img> tags.
Structured content should live in ACF fields instead — see below.

Give editors structure where structure matters, and free text where it does not.

02 — ACF Repeater

SourceACF field group `page_stats` → pageStats.stats

Field typesRepeater → Text, Text, Textarea

GraphQL

pageStats {
  heading
  stats {            # an array; one object per editor-added row
    value
    label
    description
  }
}

Numbers come from a Repeater

01
Repeater rows
Each row is one entry an editor can add, reorder or delete.
100%
Static output
No client-side fetching — the HTML ships fully rendered.
1
Request per page
One GraphQL document supplies the entire route at build time.
0
Theme files
WordPress renders nothing; it is a content API only.

03 — ACF Flexible Content

A page builder, served as a union type

SourceACF field group `page_sections` → pageSections.sections

Field typesFlexible Content → text_media · quote · gallery · cta

GraphQL

pageSections {
  sections {
    __typename                                   # dispatch on this
    ... on PageSectionsSectionsTextMediaLayout { heading body mediaPosition }
    ... on PageSectionsSectionsQuoteLayout     { quote attribution role }
    ... on PageSectionsSectionsGalleryLayout   { images { nodes { sourceUrl } } }
    ... on PageSectionsSectionsCtaLayout       { heading body style }
  }
}

Text and media, side by side

A Flexible Content layout behaves like a page builder block. The editor picks a layout, fills the fields, and the front end maps that layout name to a component. Placeholder copy continues here so the block has realistic weight.

Placeholder link

Structured fields are the difference between a site an editor can run and one that needs a developer for every change.

Placeholder NamePlaceholder Role, Placeholder Company

The same layout, mirrored

Reusing one layout with a mediaPosition select keeps the component count low while still giving editors control over rhythm down the page.

Gallery field

Closing call to action

Placeholder supporting copy for the final block on the page.

04 — ACF Relationship

SourceACF field group `page_related` → pageRelated.posts

Field typesRelationship → real Post objects

GraphQL

pageRelated {
  heading
  posts {
    nodes {
      ... on Post { title uri date excerpt featuredImage { node { sourceUrl } } }
    }
  }
}

Field map

Every piece of content on this page, and the file that renders it.

On the page	Where it lives in WordPress	Field type	Front-end file
Hero	ACF group `pageHero`	Text, Textarea, Image, Link	`Hero.astro`
Featured image	Core `featuredImage`	WP media	`WPImage.astro`
Body copy	Core `content`	WYSIWYG (HTML string)	`RichText.astro`
Stats	ACF group `pageStats`	Repeater	`Stats.astro`
Page sections	ACF group `pageSections`	Flexible Content	`FlexibleSections.astro`
Related posts	ACF group `pageRelated`	Relationship	`RelatedPosts.astro`
Head metadata	ACF group `pageSeo`	Text, Textarea, Image, True/False	`BaseLayout.astro`
Reading time	`Custom GraphQL field`	register_graphql_field() in PHP	`index.astro`

Every content type, one API call

The editor's own content

Placeholder body copy

Numbers come from a Repeater

A page builder, served as a union type

Text and media, side by side

The same layout, mirrored

Gallery field

Closing call to action

Related posts (Relationship field)

Placeholder post title one

Placeholder post title two

Placeholder post title three

Field map