apostrophecms · BoDonkey · Aug 18, 2026 · Aug 25, 2026 · Aug 27, 2026 · Aug 27, 2026
diff --git a/.gitignore b/.gitignore
@@ -3,3 +3,4 @@ node_modules
 docs/.vitepress/cache
 docs/.vitepress/dist
 docs/public/version.json
+docs-planning
diff --git a/docs/.vitepress/sidebarGuide.js b/docs/.vitepress/sidebarGuide.js
@@ -11,7 +11,7 @@ const sidebarGuide = [
         link: 'guide/introduction.md'
       },
       {
-        text: 'Why Apostrophe',
+        text: 'Why ApostropheCMS',
         link: 'guide/why-apostrophe.md'
       },
       {
@@ -51,11 +51,11 @@ const sidebarGuide = [
             link: 'guide/migration/overview.md'
           },
           {
-            text: 'Upgrade From Apostrophe 2',
+            text: 'Upgrade From ApostropheCMS 2',
             link: 'guide/migration/upgrading.md'
           },
           {
-            text: 'Upgrade From Apostrophe 3',
+            text: 'Upgrade From ApostropheCMS 3',
             link: 'guide/migration/upgrading-3-to-4.md'
           },
           {
@@ -205,6 +205,10 @@ const sidebarGuide = [
             text: 'JSX Templates',
             link: 'guide/jsx-templates.md'
           },
+          {
+            text: 'Nunjucks Templates',
+            link: 'guide/nunjucks-templates.md'
+          },
           {
             text: 'Custom Nunjucks Tags',
             link: 'reference/template-tags.md'

diff --git a/docs/cookbook/deploying-to-heroku.md b/docs/cookbook/deploying-to-heroku.md
@@ -1,9 +1,9 @@
-# Deploying Apostrophe in the Cloud with Heroku
+# Deploying ApostropheCMS in the Cloud with Heroku
 
 There are many cloud hosting services, but they all present the same challenges. For example, separate servers often don't share a single filesystem. The database usually needs its own scalable cloud hosting. And performing tasks like minifying assets is often best done in your development environment, minimizing what has to be done in production.
 
 
-## Deploying Apostrophe to Heroku
+## Deploying ApostropheCMS to Heroku
 
 [Heroku](http://heroku.com) is a great starting point for cloud hosting because it is simple to set up, but all of the cloud's challenges come into play. What we learn by deploying to Heroku can be applied equally to Amazon EC2, Microsoft Azure, and other cloud hosting services.
 
@@ -12,10 +12,10 @@ To reduce costs for this how-to, we'll be using free services from Amazon Web Se
 ## Before you begin
 
 ### Create the project (or use your own)
-First, build an Apostrophe site! See the [setting up page](../guide/development-setup.md) to get started with the installation of the CLI. We will create a project called `heroku-tut`. Alternatively, you can use an existing Apostrophe site by simply skipping this step.
+First, build an Apostrophe site! See the [setting up page](../guide/development-setup.md) to get started. We will create a project called `heroku-tut`. Alternatively, you can use an existing Apostrophe site by simply skipping this step.
 
 ```bash
-$ apos create heroku-tut
+$ npm create apostrophe@latest heroku-tut
 ```
 ### Commit to Git
 After creation, the project needs to be committed to a Git repository. If you don't already have Git installed on your system, you can learn about installation at the [official site](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git).

diff --git a/docs/cookbook/index.md b/docs/cookbook/index.md
@@ -1,10 +1,10 @@
 ---
-title: Code Cookbook
+title: ApostropheCMS Code Cookbook
 prev: false
 next: false
 ---
 
-# Apostrophe code cookbook
+# ApostropheCMS code cookbook
 
 Welcome to the cookbook. These code recipes show how to execute specific tasks, from hosting setup to commonly used module configurations. For more general information about Apostrophe configuration and concepts see [the main documentation](../guide/introduction).
 

diff --git a/docs/cookbook/using-docker.md b/docs/cookbook/using-docker.md
@@ -1,4 +1,4 @@
-# Hosting an Apostrophe project with Docker
+# Hosting an ApostropheCMS project with Docker
 
 [Docker](https://www.docker.com/) is a containerization platform that lets developers build an image for their projects and then run it anywhere. This guide is for production, not development. If you want to use Docker as a development environment, you can explore using a persistent Docker volume for your project, but bear in mind that commands like npm install can be very slow in such a configuration.
 

diff --git a/docs/cookbook/using-s3-storage.md b/docs/cookbook/using-s3-storage.md
@@ -1,4 +1,4 @@
-# Using S3 services with Apostrophe
+# Using S3 services with ApostropheCMS
 
 Deploying Apostrophe to production requires that you specify hosting for the code base, the MongoDB instance, and storage for any uploaded content. Many hosting services can provide all three, but it is also possible and sometimes desirable to split these between different services. This tutorial looks at file storage solutions using the S3 API.
 

diff --git a/docs/cookbook/windows-development.md b/docs/cookbook/windows-development.md
@@ -1,7 +1,7 @@
 ---
 next:
-  text: 'Code Organization - Modules'
-  link: '/guide/modules.html'
+  text: 'Creating a project'
+  link: '/guide/development-setup.html#creating-a-project'
 ---
 # Windows Development with WSL 2 (Optional)
 

diff --git a/docs/guide/adding-custom-widget-placeholder-content.md b/docs/guide/adding-custom-widget-placeholder-content.md
@@ -41,34 +41,38 @@ module.exports = {
 You can bypass the call to `determineBestAsetUrl()` for your images or videos stored in the `public` folder and instead pass the path to the asset using `placeholderUrl` in place of `placeholderImage`. This is discouraged because errors can be made in this path. It is better to let Apostrophe figure this out for you.
 :::
 
-### Altering the widget.html file
+### Altering the widget template
 
-The specific alteration of the `widget.html` template will depend on the type of placeholder content being delivered. Irrespective of file type, the template will have access to `data.widget.aposPlaceholder` and `data.manager.options.placeholderUrl` to populate the markup. 
+The specific alteration of the widget template will depend on the type of placeholder content being delivered. Irrespective of file type, the template will have access to the widget's `aposPlaceholder` property and the manager's `placeholderUrl` option to populate the markup — `data.widget.aposPlaceholder` and `data.manager.options.placeholderUrl` in Nunjucks, or the destructured `widget.aposPlaceholder` and `manager.options.placeholderUrl` in JSX, since `manager` arrives on the same data object as `widget`.
 
-The first, `data.widget.aposPlaceholder`, allows for confirmation that the placeholder should be displayed. This will return `true` when the widget is first added and return `false` once the widget has been edited.
+The first, `aposPlaceholder`, allows for confirmation that the placeholder should be displayed. This will return `true` when the widget is first added and return `false` once the widget has been edited.
 
-The second, `data.manager.options.placeholderUrl`, will contain the path to the content placeholder asset. If you set the `placeholderImage`, this will either be the path computed by the call to `determineBestAssetUrl()`. Otherwise, it will be the URL passed directly through the `placeholderUrl` option.
+The second, `placeholderUrl`, will contain the path to the content placeholder asset. If you set the `placeholderImage`, this will either be the path computed by the call to `determineBestAssetUrl()`. Otherwise, it will be the URL passed directly through the `placeholderUrl` option.
 
 This example demonstrates adding an image.
 
 <AposCodeBlock>
 
-``` nunjucks
-<section data-custom-widget>
-  <h1>Custom Widget</h1>
-  {% if data.widget.aposPlaceholder and data.manager.options.placeholderUrl %}
-  <img
-    src="{{ data.manager.options.placeholderUrl }}"
-    alt="{{ __t('nameSpace:imagePlaceholder') }}"
-    class="custom-widget-placeholder"
-  />
-  {% else %}
-    <!-- markup displayed after the user edits the widget -->
-  {% endif %}
-</section>
+```jsx
+export default function({ widget, manager }, { __t }) {
+  return (
+    <section data-custom-widget>
+      <h1>Custom Widget</h1>
+      {widget.aposPlaceholder && manager.options.placeholderUrl ? (
+        <img
+          src={manager.options.placeholderUrl}
+          alt={__t('nameSpace:imagePlaceholder')}
+          className="custom-widget-placeholder"
+        />
+      ) : (
+        <>{/* markup displayed after the user edits the widget */}</>
+      )}
+    </section>
+  );
+}
 ```
 <template v-slot:caption>
-  modules/custom-widget/views/widget.html
+  modules/custom-widget/views/widget.jsx
 </template>
 
 </AposCodeBlock>
@@ -77,21 +81,25 @@ This example demonstrates adding a self-hosted video.
 
 <AposCodeBlock>
 
-``` nunjucks
-<section data-custom-widget>
-  <!-- For videos uploaded to the `public` folder -->
-  {% if data.widget.aposPlaceholder and data.manager.options.placeholderUrl %}
-    <video controls width="250">
-      <source src="{{ data.manager.options.placeholderUrl }}" type="video/mp4" />
-    </video>
-  {% else %}
-    <!-- markup displayed after the user edits the widget -->
-  {% endif %}
-</section>
+```jsx
+export default function({ widget, manager }) {
+  return (
+    <section data-custom-widget>
+      {/* For videos uploaded to the `public` folder */}
+      {widget.aposPlaceholder && manager.options.placeholderUrl ? (
+        <video controls width="250">
+          <source src={manager.options.placeholderUrl} type="video/mp4" />
+        </video>
+      ) : (
+        <>{/* markup displayed after the user edits the widget */}</>
+      )}
+    </section>
+  );
+}
 ```
 
 <template v-slot:caption>
-  modules/custom-widget/views/widget.html
+  modules/custom-widget/views/widget.jsx
 </template>
 
 </AposCodeBlock>
@@ -100,7 +108,7 @@ This example demonstrates adding a self-hosted video.
 Your placeholder content should be added to the `public` folder of the custom widget. It should be named `placeholder.extension`, where the extension matches the extension passed into the `placeholderImage` option. In the first example above, the file should be `modules/custom-widget/public/placeholder.png`.
 
 ## Adding a placeholder with a custom name
-In some cases, a widget might need to have more than a single piece of placeholder content, or you might want to give the placeholder content a different name than `placeholder.extension`. In this case, once again you need to modify the main module options, the Nunjuck template, and the contents of the public folder.
+In some cases, a widget might need to have more than a single piece of placeholder content, or you might want to give the placeholder content a different name than `placeholder.extension`. In this case, once again you need to modify the main module options, the widget template, and the contents of the public folder.
 
 ### Altering the `index.js` file for custom placeholders
 
@@ -110,9 +118,9 @@ For each self-hosted placeholder, the initialization function should call the `d
 
 If electing to add multiple placeholders to a single page, as soon as the user makes any edits, all placeholder content will be removed from the page because `aposPlaceholder` is only checked once to determine if the widget has been edited.
 
-### Altering the Nunjucks template for custom placeholders
+### Altering the widget template for custom placeholders
 
-The template will still have access to `data.widget.aposPlaceholder` to determine if the widget has been edited and remove placeholder content. The URL for the placeholder can be accessed using `data.manager.options.<name>Url`. For example, `data.manager.options.customOneUrl` or `data.manager.options.videoOneUrl`. This will be available for each `<name>Image` and `<name>Url` option in the module.
+The template will still have access to the widget's `aposPlaceholder` property to determine if the widget has been edited and remove placeholder content — `data.widget.aposPlaceholder` in Nunjucks, or the destructured `widget.aposPlaceholder` in JSX. The URL for the placeholder can be accessed using `<name>Url` on the widget manager's options — `data.manager.options.<name>Url` in Nunjucks, or the destructured `manager.options.<name>Url` in JSX, since `manager` arrives on the same data object as `widget`. For example, `customOneUrl` or `videoOneUrl`. This will be available for each `<name>Image` and `<name>Url` option in the module.
 
 The same conditional block that was used for a single basic placeholder should be used for each custom placeholder added to the template.