🔁 Repeat Extension plugin

NotePlan has a simple built-in repeat mechanism, which allows for @repeat(1/n). That wasn't flexible enough for my purposes, so I wrote this plugin to allow repeats every x days, weeks, months, quarters or years. It does the work of creating the next task using information from completed tasks that include a @repeat(interval) string and a completed @done(...) date.

Here are some examples:

See below for more details.

Compared with the built-in functionality, it also allows you to easily change the text of an existing repeated task, which otherwise means visiting all the future notes with repeats.

Task sorting and section headings

It also gives you the option of (re)sorting the tasks in a section after new repeat(s) have been generated. This is helpful if you want tasks in date order. It will only runs when the completed repeat sits under a sectoin heading (## … or ### …, etc.) in the note. The plugin finds that heading from the line above the task.

When using the onEditWillSave trigger, sorting kicks in 50ms after the new repeat is generated, to avoid race conditions in the Editor.

Running it Automatically

The plugin can automatically generate the new repeated task immediately after you complete an existing one. Here's an example where it will repeat 6 weeks after completion:

This works by adding the following trigger line to the frontmatter at the start of every note you wish to automate in this way:

triggers: onEditorWillSave => jgclark.RepeatExtensions.onEditorWillSave

With this trigger in place, and if the setting Allow repeats in cancelled paragraphs? is enabled, repeats are also generated for newly cancelled tasks that include @repeat(...).

Tip: This is most easily done by using the /add trigger to note command from my Note Helpers plugin. Note: The title: of the note also needs to be in the frontmatter.

Note: Unfortunately this trigger does not fire if you complete tasks in the references section of a note. This is a limitation in NP, which I've asked to be addressed, but so far has not been.

For this reason I've added the /Generate @repeats in recent notes command to the separate Tidy Up plugin, which when you run it checks all recently-changed notes, generating any new @repeats that are required. It does not require triggers to be in place. If you include this command in a daily Template, then this is as good as a fully automated command. For example, I have this "template tag" in my end-of-day template:

<% await DataStore.invokePluginCommandByName("Generate @repeats in recent notes","np.Tidy",['{"runSilently":true}']) -%>

Running it Manually

On the currently open note, open the command bar and type the /generate repeats command.

• When run on a Project note, it creates the new repeated task straight before the completed task.
• When run on a Calendar note, it creates the new repeated task on the date of the new repeat. This uses the same calendar note type: so a repeat in a weekly note will go to the appropriate weekly note, etc. The new task is appended to the note.

Specifying the Intervals

The time intervals have two parts: number and then a character. The character is one of:

• b or B: business days (ignore weekends, but doesn't ignore public holidays, as they're different for each country)
• d or D: days
• w or W: weeks
• m or M: months
• q or Q: quarters
• y or Y: years

When the number starts with a + (e.g. +1m) it will duplicate the task for 1 month after the date the task was completed. When the number doesn't start with a + (e.g. 1m) it will duplicate the task for 1 month after the date the task was last due. This is found from a >yyyy-mm-dd scheduled date. When there is no scheduled date, then for Calendar notes it will duplicate the task for 1 month after the note date, and for Project notes it will duplicate the task for 1 month after the task was completed.

You can specify scheduled dates to all the other calendar note types supported by NotePlan:

• weekly (e.g. >2023-W28)
• monthly (e.g. >2023-07)
• quarterly (e.g. >2023-Q3)
• yearly (e.g. >2023)

The resulting repeat lines will also be specified using that same note type, and will write to the appropriate new calendar note (unless it came from a project note, in which case it will stay in the same project note).

Specifying a Concrete Base Date

As well as an interval, @repeat(...) can also take a concrete base date to repeat from: @repeat(interval, <date>). When present, the next repeat is calculated from that fixed date, rather than from the task's scheduled date or completion date. After each completion (or cancellation) the date is automatically advanced by the interval, so it keeps in step for future cycles.

<date> can be given in any of NotePlan's calendar-note date formats, and works the same whether the task is in a project note or a calendar note:

• day: YYYY-MM-DD
• week: YYYY-Wnn
• month: YYYY-MM
• quarter: YYYY-Qn
• year: YYYY

For example, the next repeat is always calculated from the base date — not the completion date, and not the scheduled >date either, even if the task had been rescheduled away from its base date:

* project reporting @repeat(1m, 2026-05-13) >2026-05-17
(completed on 2026-05-20)
* project reporting @repeat(1m, 2026-06-13) >2026-06-13

* do expenses @repeat(1m, 2026-05-12)
(completed on 2026-05-20)
* do expenses @repeat(1m, 2026-06-12) >2026-06-12

* review backlog @repeat(1w, 2026-W19)
(completed on 2026-05-20)
* review backlog @repeat(1w, 2026-W20) >2026-W20

If the interval has a + prefix (e.g. @repeat(+1m, 2026-05-12)), the + takes precedence as usual: the next repeat is scheduled from the completion/cancellation date, and the concrete date is ignored for scheduling (though it's still advanced in the new task).

Configuration

For Repeat Extensions plugin to work, you need to have the 'Append Completion Date' setting turned on in Preferences > Todo, and not to mind the time portion of the @done(...) tag being removed, as a sign that the line has been processed.

Note: because NotePlan never appends the completion date to completed checklists or cancelled tasks, this plugin unfortunately cannot be used to generate repeats from checklists. (Though if you use the trigger, it then does have enough data to pick up cancelled tasks.)

There are some settings in the Plugin Settings pane for this plugin:

• 'Delete completed item?', which deletes the completed repeated item (on either done or cancelled tasks).
• Don't look for repeats in Done or Archive note sections? If set, it will not look for repeats in the ## Done or ## Archive sections of notes.
• Allow repeats in cancelled paragraphs? If set, it will generate a new repeat when a task with @repeat(...) is newly changed to cancelled ([-]) in a note that has the save trigger enabled.
• Run Task Sorter after changes? If turned on, it will run the Task Sorting plugin on the section that includes the new repeat, using the sort order from the 'Order for Task Sorting' setting above (or Task Sorting defaults). Requires the Task Sorting & Tools plugin to be installed.

Support

If you find an issue with this plugin, or would like to suggest new features for it, please raise a Bug or Feature 'Issue' in GitHub.

If you would like to support my late-night work extending NotePlan through writing these plugins, you can through

Thanks!

Changes

Please see the CHANGELOG.