Task Scheduling (#1501)

content/collections/docs/collections.md

@@ -208,6 +208,14 @@ To get more granular and introduce _time_, add a [date field](/fieldtypes/date)
 If you don't enable the time, all entries on a given day will assume a default time of midnight, or `00:00`. If you want to make sure that multiple entries on the same day are ordered in the order you published them, turn the time on.
 :::
 
+## Scheduling
+
+If you've added a date and/or time to your entries in order to "schedule" them, you may need to set up the scheduler in order for Statamic to properly invalidate things.
+
+For example, you might need things to happen exactly when an entry is scheduled, like refreshing a cached blog listing, or sending a notification.
+
+[Learn how to use the scheduler](/scheduling)
+
 ## Ordering
 
 Flick on the "Orderable" switch in a collection's settings and you'll have a drag and drop UI in the control panel to order the entries. The collection is now "structured". Learn more about [structures](/structures).

content/collections/docs/scheduling.md

@@ -0,0 +1,60 @@
+---
+id: 0df63f01-4b97-4c15-89a9-015c02ea3748
+blueprint: page
+title: Task Scheduling
+intro: "Manage scheduled tasks using Laravel's task scheduler."
+template: page
+related_entries:
+  - 7202c698-942a-4dc0-b006-b982784efb03
+  - ffa24da8-3fee-4fc9-a81b-fcae8917bd74
+---
+Statamic leverages task scheduling via Laravel's Task Scheduler.
+
+In a nutshell, you can create a single cron job which will allow things to happen on a schedule, without any visitors needing to be on the site.
+
+[Learn more about scheduling tasks in the Laravel docs](https://laravel.com/docs/11.x/scheduling)
+
+## Running the scheduler
+
+### In Production
+
+In production, you will need to set up a single once-per-minute cron entry that runs the `schedule:run` Artisan command.
+
+Using a service like Laravel Forge makes this simple.
+
+```sh
+* * * * * cd /path-to-your-project && php artisan schedule:run >> /dev/null 2>&1
+```
+
+### In Development
+
+Typically, you would not add a scheduler cron entry to your local development machine. Instead, you may use the `schedule:work` Artisan command. This command will run in the foreground and invoke the scheduler every minute until you terminate the command:
+
+```sh
+php artisan schedule:work
+```   
+
+[Learn more about running the scheduler](https://laravel.com/docs/11.x/scheduling#running-the-scheduler)
+
+## Included tasks
+
+The following tasks will be executed whenever the task scheduler is running, without you needing to enable anything.
+
+### EntryScheduleReached
+
+Statamic will dispatch a `Statamic\Events\EntryScheduleReached` event whenever a scheduled entry reaches its target date. This event is used in multiple places such as updating search indexes and invalidating caches.
+
+The event will be dispatched on the minute _after_ the scheduled time.
+
+
+## Defining Schedules
+
+One way to add your own scheduled tasks is by adding items to your `routes/console.php` file.
+
+```php
+Schedule::command('my-command')->daily();
+
+Schedule::job(new Heartbeat)->everyFiveMinutes();
+```
+
+[Learn more about defining schedules](https://laravel.com/docs/11.x/scheduling#defining-schedules)

content/collections/docs/static-caching.md

@@ -440,6 +440,14 @@ return [
 ];
 ```
 
+### On a schedule
+
+If you have the scheduler running, Statamic will use the same set of rules mentioned above, but when scheduled entries are due to become active.
+
+For example, if you schedule an entry for Friday at 8am, and you have the scheduler running, appropriate pages will be invalidated just as if you had clicked saved on that entry at Friday at 8am.
+
+[Learn how to use the scheduler](/scheduling)
+
 ### Custom Invalidator Class
 
 You can also specify a custom invalidator class to **programatically determine which URLs should be invalidated**. To achieve that, override or extend [the default invalidator class](https://github.com/statamic/cms/blob/01f8dfd1cbe304be1848d2e4be167a0c49727170/src/StaticCaching/DefaultInvalidator.php).

content/trees/navigation/docs.yaml

@@ -115,6 +115,9 @@ tree:
       -
         id: 716bb7b8-952a-45b7-9c20-24c4e0a24e43
         entry: ffa24da8-3fee-4fc9-a81b-fcae8917bd74
+      -
+        id: a6408363-0492-4df1-86a1-98cef1205f54
+        entry: 0df63f01-4b97-4c15-89a9-015c02ea3748
       -
         id: 29526fd0-a0a1-11ec-b230-0800200c9a66
         entry: 268d444c-88e3-4b52-bfc6-165749ef3ec1