Add a page

The schema says which pages exist and which sections each has. The database holds the content. A page renders from the schema before any content exists. The first edit creates its row. Goal: /careers/, a hero and a list of open roles editors can add to. A draft until it is ready.

1. Declare the page

src/lib/admin-schema.ts:

pages: {
  careers: {
    title: "Careers",
    draft: true,
    sections: {
      hero:  { type: "hero", props: { title: "Careers", body: "Come build with us.", image: "", imageVideo: "" } },
      roles: { type: "role-list", props: { heading: "Open roles", roles: [] } },
    },
  },
},

hero already exists in the template. role-list does not, so:

2. Build the component

src/components/careers/RoleList.astro:

---
import { stageAttrs, stagePath, stageArray } from "../../lib/stage-anchors";

interface Role { title?: string; location?: string; href?: string }
interface Props {
  heading?: string;
  roles?: Role[];
  _stageId?: string;    // "roles", from the schema key
  _stageType?: string;  // "role-list"
}
const { heading, roles = [], _stageId, _stageType } = Astro.props;
---

<section class="mx-auto max-w-content px-6 py-24" {...stageAttrs(_stageId, _stageType)}>
  <h2 class="text-3xl text-foreground" {...stagePath("props.heading")}>{heading}</h2>
  <ul class="mt-10 flex flex-col divide-y divide-border" {...stageArray("props.roles", "Add role")}>
    {roles.map((r, i) => (
      <li class="flex items-center justify-between py-5">
        <div>
          <h3 class="text-lg text-foreground" {...stagePath(`props.roles.${i}.title`)}>{r.title}</h3>
          <p class="text-sm text-muted" {...stagePath(`props.roles.${i}.location`)}>{r.location}</p>
        </div>
        <a href={r.href} class="rounded-full border border-border px-4 py-2 text-sm">Apply</a>
      </li>
    ))}
  </ul>
</section>

3. Register it

src/lib/components.ts:

import RoleList from "../components/careers/RoleList.astro";

const registry = {
  hero: Hero,
  "role-list": RoleList,
  // …
};

4. Make roles addable

src/lib/admin-schema.ts, under components:

"role-list": {
  arrays: {
    "props.roles": {
      kind: "modal",
      addLabel: "Add role",
      title: "New role",
      noun: "role",
      reorderable: true,
      form: [
        { key: "title",    label: "Title",    type: "text", required: true, placeholder: "Senior engineer" },
        { key: "location", label: "Location", type: "text", placeholder: "Auckland or remote" },
        { key: "href",     label: "Apply link", type: "url" },
      ],
    },
  },
},

The href has no anchor on the page, so it is set in this form and edited from the item’s cog.

5. Run dev

pnpm dev, open /careers/. The page renders from the schema. No row exists yet.

<main data-e-sections="">
  <section data-e-id="hero" data-e-type="hero">
    <h1 data-e-path="props.title">Careers</h1>
    <div data-e-path="props.body" data-e-rich="">Come build with us.</div>
  </section>
  <section data-e-id="roles" data-e-type="role-list">
    <h2 data-e-path="props.heading">Open roles</h2>
    <ul data-e-array="props.roles" data-e-add-label="Add role"></ul>
  </section>
</main>

6. Edit

Open /admin, go to Careers, press Edit. The bar reads “Draft page”. Press the tab on the roles list, Add role, fill the form. Click the hero title and change it. Publish. That first Publish creates the row:

{
  "slug": "careers",
  "title": "Careers",
  "version": 1,
  "components": [
    { "id": "hero", "type": "hero",
      "props": { "title": "Careers at Acme", "body": "Come build with us.", "image": "", "imageVideo": "" } },
    { "id": "roles", "type": "role-list",
      "props": { "heading": "Open roles", "roles": [
        { "id": "c_k2Xp9Qm1", "title": "Senior engineer", "location": "Auckland or remote", "href": "https://jobs.example.com/123" }
      ] } }
  ]
}

hero and roles are the schema keys. The role’s id was generated when it was added.

7. Ship

Remove draft: true, merge. The next production build includes /careers/.

8. Add a section later

One line under sections:

benefits: { type: "icon-grid", props: { title: "Why Acme", items: [] } },

icon-grid already exists, so nothing else to build. It renders on the next dev start. The row is untouched until someone edits the new section. Remove a line and the section stops rendering. Its content stays in the row.

The keys

Key	Does
`title`	The page’s title. Marks the entry as a page
`draft`	Out of the production build. Remove to ship
`sections`	The page’s sections, in order. The key is the component id. `props` fill a section until someone edits it
`palette`	Optional. Section types editors may add from the tab on the right

Slugs may nest: "help/faq". Keys ending in * are palettes for a family of pages, not pages.

More examples

A fixed page with three sections and nothing addable:

about: {
  title: "About",
  sections: {
    hero:    { type: "hero", props: { title: "About us", body: "", image: "", imageVideo: "" } },
    story:   { type: "prose", props: { body: "<p>Founded in 2019…</p>" } },
    team:    { type: "team-grid", props: { heading: "The team", members: [] } },
  },
},

A page editors compose. One fixed hero, then whatever they add:

"landing/spring": {
  title: "Spring launch",
  draft: true,
  sections: {
    hero: { type: "hero" },
  },
  palette: [
    { type: "feature-grid", label: "Features",    starter: { heading: "", items: [] } },
    { type: "testimonial",  label: "Testimonial", starter: { quote: "", name: "" } },
    { type: "cta",          label: "Call to action", starter: { heading: "", button_label: "", button_href: "" } },
  ],
},

A family of pages with a shared palette:

"help/*": {
  palette: [
    { type: "prose", label: "Text", starter: { body: "" } },
    { type: "faq",   label: "FAQ",  starter: { items: [] } },
  ],
},
"help/billing":  { title: "Billing",  sections: { hero: { type: "hero", props: { title: "Billing" } } } },
"help/shipping": { title: "Shipping", sections: { hero: { type: "hero", props: { title: "Shipping" } } } },

Ids

The section key is the component id. The page template passes it to the renderer, the renderer puts it on its wrapper, and the editor saves under it. You never type an id anywhere else.

schema     team: { type: "team-grid" }
page       <Component _stageId="team" _stageType="team-grid" … />
html       <section data-e-id="team" data-e-type="team-grid">
row        { "id": "team", "type": "team-grid", "props": { … } }

Sections editors add get generated ids with a c_ prefix. Another page can point at a section by name:

<span {...stageRef({ kind: "page", key: "about", id: "team", path: "props.heading" })}>{heading}</span>

A page that already exists

Its sections have generated ids. Declare it by title only, or declare only the sections you are adding:

about: {
  title: "About",                                   // existing sections untouched
  sections: {
    awards: { type: "logo-row", props: { title: "Awards", items: [] } },   // the new one
  },
},

Declaring an existing section under a new key adds an empty copy beside it.

Drafts

Where	Shown
Local dev	Yes
Preview deploy	Yes
Production	No
`/admin`	Yes

Public routes read getSitePages() from lib/pages.ts. The preview route reads getPreviewPages(). Both come with the template. admin, preview and api cannot be pages.

Next steps

Add a component

A renderer, then one line in sections.

Page schemas

Everything the schema can declare.

Start

Making content editable

Making content addable

Media

Next.js

Analytics SDK

Recipes

Platform reference

1. Declare the page

2. Build the component

3. Register it

4. Make roles addable

5. Run dev

6. Edit

7. Ship

8. Add a section later

The keys

More examples

Ids

A page that already exists

Drafts

Next steps

Add a component

Page schemas

​1. Declare the page

​2. Build the component

​3. Register it

​4. Make roles addable

​5. Run dev

​6. Edit

​7. Ship

​8. Add a section later

​The keys

​More examples

​Ids

​A page that already exists

​Drafts

​Next steps

Add a component

Page schemas

1. Declare the page

2. Build the component

3. Register it

4. Make roles addable

5. Run dev

6. Edit

7. Ship

8. Add a section later

The keys

More examples

Ids

A page that already exists

Drafts

Next steps