Previewing and Testing Content

Content is authored as Markdown — see Content as Markdown. To see how it renders and to check that every block works, you serve those same files through the mock API and run the block sanity test. Both read the content directly, so there is nothing to generate first.

Serving content with the mock API

The mock API turns a content tree into a Plone REST API. It reads the .md files live, with no build step, so editing a page and refreshing the admin shows the change immediately.

These commands run from a checkout of the Inka repository. By default the mock API mounts Inka's own content:

• /docs — the documentation pages (this site's own source).
• /_test_data — fixtures used by the automated tests.
• / — the demo site root.

To serve your own content instead, set CONTENT_MOUNTS, for example CONTENT_MOUNTS=/:/path/to/your/content.

Before it starts, the mock checks the content it will serve, and refuses to start on content with a broken link, a list item without an id, and the like. To have your own blocks checked against their schemas too (each field's value against its widget, and every field against what the block declares), set CONTENT_SCHEMAS to the file your frontend keeps its block schemas in: a JavaScript module (its default export, plain data your config also imports, so a field set shared by several blocks is written once) or a JSON file, shaped { "blockType": { "blockSchema": …, "schemaEnhancer": … } }. bin/plone-content.cjs served runs the same check without starting a server.

The scripts take their ports from environment variables and have no defaults, so set them first:

pnpm start:mock-api needs HYDRA_MOCK_API_PORT. pnpm start:test needs all six: it lists the test frontend, Nuxt, Next.js and F7 example front ends in the editor's front-end switcher, whether or not they are running.

Start the mock API:

Then start the admin, which is configured to talk to the mock API, and open a page to edit:

The admin renders the page through whichever frontend you select and updates the live preview as you edit — the same round trip a real editor gets, backed by your local Markdown. The test suite README covers the full harness.

Testing with the block sanity test

The block sanity test is the safety net for content. It does not hard-code a list of blocks to check — instead it discovers every block on the served content and, for each one, verifies that it renders, that its sub-blocks render, and that its editable fields carry the annotations the admin needs. Because discovery reads the live content, authoring a new example is all it takes to put a block under test — there is no separate test to write.

That is the working rule: every block type needs an example somewhere in the content, and a block type with no example is treated as a gap to fix, not something to skip.

The test runs each discovered block against several frontends. A core set — the mock frontend, Nuxt, and Next.js — is enforced: a block that fails to render there fails the suite. The remaining example frontends carry partial coverage on purpose and are checked on a best-effort basis.

Run it from the root of the Inka checkout, with every HYDRA_*_PORT variable set (the full list is in the CI example):

A failure names the block and the frontend, and points at the page it was found on, so the fix is usually either the renderer for that block in that frontend or the content that produced an unexpected shape.

To run it against your own front end and content, in your own CI, see Test your blocks in your own CI.

How the pieces fit

You edit a .md file; the mock API serves it as block JSON; the admin previews it through a frontend; and the sanity test confirms — across frontends — that every block on it renders and stays editable. One source of content feeds all three, so what you preview is what is tested and what ships.

Where to look next

• Content as Markdown — the authoring format itself.
• The block reference under Examples — a worked example of every block, and the corpus the sanity test discovers.
• The test suite README (linked above) — running the full Playwright harness, ports, and per-frontend projects.