Docs: Break Scheduled Publishing into multiple subheadings

CHANGELOG.txt

@@ -43,6 +43,7 @@ Changelog
  * Docs: Fix `wagtailcache` and `wagtailpagecache` examples to not use quotes for the `fragment_name` (Shiv)
  * Docs: Update tutorial to reflect the move of the "Add child page" action to a top-level button in the header as a '+' icon (Clifford Gama)
  * Docs: Fix link to `HTTPMethod` in `Page.handle_options_request()` docs (Sage Abdullah)
+ * Docs: Improve the Pages Theory page with section headings and admonitions to aid in readability (Clifford Gama)
  * Maintenance: Close open files when reading within utils/setup.py (Ataf Fazledin Ahamed)
  * Maintenance: Avoid redundant `ALLOWED_HOSTS` check in `Site.find_for_request` (Jake Howard)
  * Maintenance: Update `CloneController` to ensure that `added`/`cleared` events are not dispatched as cancelable (LB (Ben) Johnston)

docs/reference/pages/theory.md

@@ -89,12 +89,12 @@ You can apply custom behavior to this process by overriding `Page` class methods
 
 (scheduled_publishing)=
 
-## Scheduled Publishing
+## Scheduled publishing
 
 Page publishing can be scheduled through the _Set schedule_ feature in the _Status_ side panel of the _Edit_ page. This allows you to set up initial page publishing or a page update in advance.
 For pages to go live at the scheduled time, you should set up the [publish_scheduled](publish_scheduled) management command.
 
-The basic workflow is as follows:
+### Basic workflow for scheduled publishing
 
 -   Scheduling is done by setting the _go-live at_ field of the page and clicking _Publish_.
 -   Scheduling a revision for a page that is not currently live means that page will go live when the scheduled time comes.
@@ -102,12 +102,20 @@ The basic workflow is as follows:
 -   If the page has a scheduled revision and you set another revision to publish immediately (i.e. clicking _Publish_ with the _go-live at_ field unset), the scheduled revision will be unscheduled.
 -   If the page has a scheduled revision and you schedule another revision to publish (i.e. clicking _Publish_ with the _go-live at_ field set), the existing scheduled revision will be unscheduled and the new revision will be scheduled instead.
 
-Note that you have to click _Publish_ after setting the _go-live at_ field for the revision to be scheduled. Saving a draft revision with the _go-live at_ field without clicking _Publish_ will not schedule it to be published.
+```{note}
+You must click _Publish_ after setting the _go-live at_ field for the revision to be scheduled. Saving a draft revision with the _go-live at_ field without clicking _Publish_ will not schedule it to be published.
+```
+
+### Viewing and managing scheduled revisions
 
 The _History_ view for a given page will show which revision is scheduled and when it is scheduled. A scheduled revision in the list will also provide an _Unschedule_ button to cancel it.
 
+## Scheduled unpublishing
+
 In addition to scheduling a page to be published, it is also possible to schedule a page to be unpublished by setting the _expire at_ field. However, unlike with publishing, the unpublishing schedule is applied to the live page instance rather than a specific revision. This means that any change to the _expire at_ field will only be effective once the associated revision is published (i.e. when the changes are applied to the live instance). To illustrate:
 
+### Basic workflow for scheduled unpublishing
+
 -   Scheduling is done by setting the _expire at_ field of the page and clicking _Publish_. If the _go-live at_ field is also set, then the unpublishing schedule will only be applied after the revision goes live.
 -   Consider a live page that is scheduled to be unpublished on e.g. 14 June. Then sometime before the schedule, consider that a new revision is scheduled to be published on a date that's **earlier** than the unpublishing schedule, e.g. 9 June. When the new revision goes live on 9 June, the _expire at_ field contained in the new revision will replace the existing unpublishing schedule. This means:
     -   If the new revision contains a different _expire at_ field (e.g. 17 June), the new revision will go live on 9 June and the page will not be unpublished on 14 June but will be unpublished on 17 June.
@@ -116,4 +124,6 @@ In addition to scheduling a page to be published, it is also possible to schedul
     -   If the new revision contains a different _expire at_ field (e.g. 25 June), the page will be unpublished on 14 June, the new revision will go live on 21 June and the page will be unpublished again on 25 June.
     -   If the new revision has the _expire at_ field unset, the page will be unpublished on 14 June and the new revision will go live on 21 June.
 
+```{note}
 The same scheduling mechanism also applies to snippets with {class}`~wagtail.models.DraftStateMixin` applied. For more details, see [](wagtailsnippets_saving_draft_changes_of_snippets).
+```

docs/releases/6.4.md

@@ -59,6 +59,7 @@ depth: 1
  * Fix `wagtailcache` and `wagtailpagecache` examples to not use quotes for the `fragment_name` (Shiv)
  * Update tutorial to reflect the move of the "Add child page" action to a top-level button in the header as a '+' icon (Clifford Gama)
  * Fix link to `HTTPMethod` in `Page.handle_options_request()` docs (Sage Abdullah)
+ * Improve [](pages_theory) with section headings and admonitions to aid in readability (Clifford Gama)
 
 ### Maintenance