Pro 9889 jsx conversion by BoDonkey · Pull Request #565 · apostrophecms/docs

BoDonkey · 2026-09-02T14:28:00Z

Please indicate which branch this PR should merge into:

Check one

main
latest
stable
Check if this PR will be resubmitted against another branch

Summary

Summarize the changes briefly, including which issue/ticket this resolves. If it closes an existing Github issue, include "Closes #[issue number]"
This PR converts a large majority of the templates to JSX. It also introduces a number of fixes. It should not be published until the two starter kit JSX branches land. Closes PRO-9889.

What are the specific steps to test this change?

For example:

Run the website and log in as an admin

Open a piece manager modal and select several pieces

Click the "Archive" button on the top left of the manager and confirm that it should proceed

Check that all pieces have been archived properly

What kind of change does this PR introduce?

(Check at least one)

Make sure the PR fulfills these requirements:

It includes a) the existing issue ID being resolved, b) a convincing reason for adding this feature, or c) a clear description of the bug it resolves
The changelog is updated
Related documentation has been updated
Related tests have been updated

If adding a new feature without an already open issue, it's best to open a feature request issue first and wait for approval before working on it.

Other information:

…avigation

linear · 2026-09-02T14:28:03Z

PRO-9889

boutell

Some initial feedback. Recommend you back out the unplanned moves of files (which are showing up as deletions and creations) and address the points around needing to show how access to global and home is actually obtained, then re-request review

boutell · 2026-09-02T14:32:13Z

@@ -1,336 +0,0 @@
---


Why does this die?

Not linked from anywhere, but will be cleaned up in another PR. Reverted.

boutell · 2026-09-02T14:37:29Z

 | `APOS_BASE_URL` | Astro staging frontend URL (set after Part 2) | `https://your-project.vercel.app` |
 | `NODE_ENV` | Sets production mode | `production` |
-| `APOS_RELEASE_ID` | Unique ID per deploy for cache busting | `${{RAILWAY_GIT_COMMIT_SHA}}` |
+| `APOS_RELEASE_ID` | Unique ID per deploy for cache busting | <span v-pre>`${{RAILWAY_GIT_COMMIT_SHA}}`</span> |


why the funny span with v-pre thing for this and not other columns?

Vitepress tries to interpret double curly braces through mustache interpolation. The wrapping prevents that. This sweep of the docs picked up a few that missed being escaped.

boutell · 2026-09-02T14:37:46Z

 > **`APOS_EXTERNAL_FRONT_KEY`:** Generate a long random string for this value. It authenticates the Astro frontend with ApostropheCMS. Both Railway and Vercel must use the exact same value or requests will be rejected. Treat it like a password.

-> **`APOS_RELEASE_ID`:** Setting this to `${{RAILWAY_GIT_COMMIT_SHA}}` uses Railway's built-in reference variable to automatically generate a unique value from the git commit hash on every deploy. This is preferable to a static random string, which would remain the same across redeployments.
+> **`APOS_RELEASE_ID`:** Setting this to <span v-pre>`${{RAILWAY_GIT_COMMIT_SHA}}`</span> uses Railway's built-in reference variable to automatically generate a unique value from the git commit hash on every deploy. This is preferable to a static random string, which would remain the same across redeployments.


same question each time this appears

boutell · 2026-09-02T14:38:13Z

 For filter links, prefer `aposData.filters` (derived from `req.data.filters`) over the legacy `aposData.piecesFilters` pattern where possible. This provides filter metadata and pre-built URLs that are consistent with how static paths are generated.

-Note that static mode only supports a single active filter at a time. Combined filters will not have pre-rendered paths and will return 404s. See the note in [Backend Configuration](#3-configure-piece-filters-for-static-generation) above.
+Note that static mode only supports a single active filter at a time. Combined filters will not have pre-rendered paths and will return 404s. See the note in [Backend Configuration](#_3-configure-piece-filters-for-static-generation) above.


sanity checking that _3 is correct? I mean maybe

Yup - the anchor link is numbered and #3-XXX is invalid in, get this, CSS. So, VitePress slugifies during anchor link creation to make them valid.

boutell · 2026-09-02T14:41:53Z

-        {# 👇 Referencing `data.home._children` and looping over them. #}
-        {% for page in data.home._children %}
+        {/* 👇 Referencing `home._children` and looping over them. */}
+        {home._children.map((child) => (


Does not show how we got hold of home and global in the first place. A more complete example that does that is called for

Fixed here and in one other instance on guide/pages.md.

boutell · 2026-09-02T14:45:29Z

(global and home are available the same way page is available)

As a matter of fact they are properties of the data prop given to the page template, just like in Nunjucks, so it's extra strange the way claude wrote it here without capturing that to a variable first

boutell

LGTM 😄 I did a bunch of spot checking; it's rather epic, of course, but feels good to me.

boutell · 2026-09-04T22:17:33Z

Let me know when this lands, I want to bring in WYSIWYG Fields documentation after that.

BoDonkey added 18 commits August 18, 2026 09:42

Remove orphaned cookbook duplicates of html-conversion and building-n…

7a7c81a

…avigation

Initial JSX conversion

bb14572

Remove stray .bak files committed with the JSX conversion

077ba54

Add skill with links

fd4f5f3

Add missing section.

8ec37c4

Convert and update reference docs

f0e86ea

First guides.

cc946a6

Guide and ref fix

d7b8674

first round tutorials

1bed539

super() removal

fc28787

Fix missed fences

c03a90e

More guide conversion after answers

5e8318a

Update last references

589ded1

fix prose only mentions

641c4e2

Promote JSX

938254a

Non-JSX fixes

acbd61f

Convert some Nunjucks only content

56f92ad

Update starter kits

fee6791

BoDonkey requested review from boutell and a lite review from Copilot September 2, 2026 14:28

BoDonkey removed the request for review from Copilot September 2, 2026 14:28

Copilot started reviewing on behalf of BoDonkey September 2, 2026 14:28 View session

boutell requested changes Sep 2, 2026

View reviewed changes

Changes in response to first comments

a75377f

BoDonkey requested a review from boutell September 3, 2026 10:18

boutell approved these changes Sep 3, 2026

View reviewed changes

Uh oh!

Conversation

BoDonkey commented Sep 2, 2026

Please indicate which branch this PR should merge into:

Summary

What are the specific steps to test this change?

What kind of change does this PR introduce?

Make sure the PR fulfills these requirements:

Uh oh!

linear Bot commented Sep 2, 2026

Uh oh!

boutell left a comment

Choose a reason for hiding this comment

Uh oh!

boutell Sep 2, 2026

Choose a reason for hiding this comment

Uh oh!

BoDonkey Sep 3, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

boutell Sep 2, 2026

Choose a reason for hiding this comment

Uh oh!

BoDonkey Sep 3, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

boutell Sep 2, 2026

Choose a reason for hiding this comment

Uh oh!

boutell Sep 2, 2026

Choose a reason for hiding this comment

Uh oh!

BoDonkey Sep 3, 2026

Choose a reason for hiding this comment

Uh oh!

boutell Sep 2, 2026

Choose a reason for hiding this comment

Uh oh!

BoDonkey Sep 3, 2026

Choose a reason for hiding this comment

Uh oh!

boutell commented Sep 2, 2026

Uh oh!

boutell left a comment

Choose a reason for hiding this comment

Uh oh!

boutell commented Sep 4, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

BoDonkey Sep 3, 2026 •

edited

Loading

BoDonkey Sep 3, 2026 •

edited

Loading