Adding a page, a block, a list

The page template#

A single route file builds every page, in every language: src/pages/[lang]/[...slug].astro. getStaticPaths decides which URLs to produce.

---
import { getCollection } from 'astro:content';
import { DEFAULT_LOCALE, LOCALES, localePath, mergeWithDefault } from '../../lib/locales';

export async function getStaticPaths() {
  const entries = await getCollection('pages');
  const byId = new Map(entries.map((entry) => [entry.id, entry]));

  // The page list comes from the reference language: it is the authority.
  const pages = entries
    .filter((entry) => entry.id.startsWith(`${DEFAULT_LOCALE}/`))
    .map((entry) => entry.id.slice(DEFAULT_LOCALE.length + 1));

  return LOCALES.flatMap((locale) =>
    pages.map((page) => {
      const reference = byId.get(`${DEFAULT_LOCALE}/${page}`);
      const translation = byId.get(`${locale}/${page}`);
      const { data, untranslated } = mergeWithDefault(reference.data, translation?.data);

      return {
        // “home” is the root of its language: no extra segment.
        params: { lang: locale, slug: page === 'home' ? undefined : page },
        props: { locale, page, data, untranslated },
      };
    }),
  );
}
---

Adding a page in four gestures#

1. Write the content, in each language

   src/content/pages/fr/services.json
   src/content/pages/en/services.json

   File name in lowercase letters, digits and hyphens. It becomes the URL segment: /en/services/.

2. Decide how it renders

   If the page looks like the others, the existing template is enough. Otherwise map a layout component to a page name — routing stays in a single file:

   ---
   import Home from '../../components/pages/Home.astro';
   import Services from '../../components/pages/Services.astro';
   
   const TEMPLATES = { home: Home, services: Services };
   
   const { locale, page, data, untranslated } = Astro.props;
   const Template = TEMPLATES[page] ?? Home;
   const missing = new Set(untranslated);
   ---
   
   <Base title={data.meta.title} description={data.meta.description} …>
     <Template data={data} untranslated={missing} />
   </Base>

3. Place the editable zones

   One component per field type. The path is the same as in the JSON.

   ---
   import Editable from 'inline-core/components/Editable.astro';
   import Media from 'inline-core/components/Media.astro';
   
   const { data, untranslated } = Astro.props;
   ---
   
   <section class="hero">
     <Editable data={data} path="blocks.hero.title" as="h1" untranslated={untranslated} />
     <Editable data={data} path="blocks.hero.intro" as="p" untranslated={untranslated} />
   </section>
   
   <Media data={data} path="blocks.hero.visual" widths={[480, 800, 1200]} sizes="(max-width: 48rem) 100vw, 48rem" />

4. Add the navigation link

   src/content/site.json, navigation section. That is structure: the client does not change it from the overlay.

Then:

npm run build && npm run check

The three components#

Editable — text and richtext

<Editable data={data} path="blocks.hero.title" as="h1" />
<Editable data={data} path="blocks.pitch.detail" as="p" class="lead" />

The component applies style classes for a text field, and places the markup as-is for a richtext one. In both cases the rendering is purely static: the value is in the raw HTML.

Media — image and video

<Media
  data={data}
  path="blocks.showcase.visual"
  widths={[480, 800, 1200, 1600]}
  sizes="(max-width: 48rem) 100vw, 48rem"
/>

<Media data={data} path="blocks.showcase.film" />

For an image, the component uses <Image /> from astro:assets: AVIF and WebP, a set of widths, dimensions written into the HTML. For a video it renders a <figure> with the provider iframe and the title — and the title is in the served HTML.

Collection — lists

---
import Collection from 'inline-core/components/Collection.astro';
import Testimonial from '../components/Testimonial.astro';
---

<Collection
  data={data}
  name="testimonials"
  item={Testimonial}
  untranslated={missing}
  blank={{
    quote: {
      type: 'text',
      value: 'Their feedback, in one sentence.',
      style: { size: 'lg', weight: 'regular', italic: true, align: 'left', color: 'primary' },
    },
    author: {
      type: 'text',
      value: 'First name L., role',
      style: { size: 'sm', weight: 'medium', italic: false, align: 'left', color: 'muted' },
    },
  }}
/>

The item component receives the item and its path:

---
import type { CollectionItem } from 'inline-core/schema';
import Editable from 'inline-core/components/Editable.astro';

const { item, path, untranslated } = Astro.props;
---

<blockquote>
  <Editable path={`${path}.quote`} field={item.quote} as="p" class="testimonial-quote" untranslated={untranslated} />
  <Editable path={`${path}.author`} field={item.author} as="footer" class="testimonial-author" untranslated={untranslated} />
</blockquote>

npm run check fails if a collection is rendered without its <template>: the “Add” button would have nothing to clone.

The attributes placed in the HTML#

These attributes are inert in production: zero cost, no SEO effect. They only serve the overlay, which is loaded only after authentication.

The hydration rule#

This is the project's number one trap, and it is invisible in the rendered source. Astro accepts React, Vue and Svelte; inline does too, under a condition that is not the one people expect.

check-html.mjs enforces exactly that rule: it verifies that every JSON value is in the raw HTML, and that no editable zone sits inside a hydrated island.

What the build refuses#

After adding a page#

• The file exists in every declared language.
• npm run build passes.
• npm run check passes — content in raw HTML, language parity.
• A single <h1> on the page, heading hierarchy without skipped levels.
• Every list has its <template> (guaranteed if you go through Collection).
• The navigation link is added to site.json if the page must be reachable.
• Images are in src/media/, lowercase and unaccented.