Mirrors/super-productivity
1
0
Fork 0
mirror of https://github.com/johannesjo/super-productivity.git synced 2026-07-17 16:37:43 +00:00
Code Issues Projects Releases Wiki Activity
Page: 3.04 Short Syntax
Pages
0.01 Style Guide 0.02 Wiki QA and Maintenance 2.01 Downloads and Install 2.11 Run the Development Server 2.12 Package the App 2.13 Run with Docker 2.14 Build for Android 2.15 Develop a Plugin 2.16 Set Up Development Environment 2.17 Add a New Issue Integration 2.18 Contribute Translations 2.19 Sync Proton Drive via rclone 2.20 Import from Todoist 3.05 Web App vs Desktop 3.06 User Data 3.07 Issue Integration Comparison 3.08 Sync Integration Comparison 3.09 Theming 3.97 Obsidian Linter Config MD 3.98 Obsidian Linter Config YAML 4.01 The Today View 4.02 Inbox View 4.03 Planner View 4.04 Schedule View 4.05 Board View 4.06 Project View 4.07 Tag View 4.07a Tags_Eat the Frog 4.07b Tags_Ordinal Priorities 4.08 Time Estimates 4.09 Task Attributes 4.10 Task Notes 4.11 Subtasks 4.12 Scheduled Tasks 4.13 Repeating Tasks 4.14 How Time Is Logged 4.15 Timers and Focus Mode 4.16 Break Reminders 4.17 Idle Time 4.18 Reflection 4.19 Metrics 4.20 Task Archiving 4.21 Worklog 4.22 Quick History 4.23 Managing Your Data 4.24 Integrations
4 3.04 Short Syntax
github-actions[bot] edited this page 2026-06-08 09:49:05 +00:00
Unescape Escape
Table of Contents
This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

Short Syntax

Super Productivity supports five main short syntax forms for quickly adding metadata to tasks: tags (#), projects (+), time estimates (m/h), due dates (@), and deadlines (!). The project, tag, and due/deadline/time forms can be enabled or disabled in 3.02-Settings-and-Preferences#global-settings.Short-Syntax.

Supported Syntax Forms

Tag Syntax (#)

  • Symbol: #
  • Purpose: Add tags to the task.
  • Grammar: #<tag-name>. A space is required before #.
  • Parameters: Tag name (case-insensitive).
  • Valid: "Task #urgent", "Meeting #work #important". Multiple tags allowed.
  • Invalid: "Task#urgent" (no space before #) — the whole short-syntax run returns no changes. If other tokens are valid (e.g. "Task#urgent #other"), only the valid tag is applied and the invalid token is left in the title.

Project Syntax (+)

  • Symbol: +
  • Purpose: Assign the task to a project.
  • Grammar: +<project-name>. A space is required before +.
  • Parameters: Project title or partial title; minimum 3 characters. Matching is prefix-based, case-insensitive, with spaces removed for comparison. The shortest matching project title is preferred when several match.
  • Valid: "Task +Important Project", "Task +Project" (partial match). Project names containing +, #, @, or similar are supported; the parser uses lookahead so these characters inside the name do not end the token.
  • Invalid: "Task+Project" (no space before +) — no project is applied.

Time Estimate Syntax

  • Symbols: m (minutes), h (hours). Optional prefix t. Optional / to separate time spent from time estimate.
  • Purpose: Set time spent and/or time estimate.
  • Grammar: [t]<number><unit>[ <number><unit>...][/ <number><unit>...]. Units: m, h. Decimal numbers allowed (e.g. 1.5h). Before /: time spent on the current day. After /: time estimate. Clusters like 1h 30m are supported.
  • Parameters: Time spent (before /): e.g. 30m, 1.5h. Time estimate (after /): e.g. 1h, 90m. One side can be omitted: 30m/ sets only time spent; 1h sets only estimate.
  • Valid: "Task 10m", "Task 1h/2h", "Task 30m/", "Task t1.5h", "Task 1h 30m / 2h".
  • Defaults: h = 60 minutes.

Due Date Syntax (@)

  • Symbol: @
  • Purpose: Set due date/time for the task.
  • Grammar: @<date-time-expression>. No space is allowed between @ and the expression.
  • Parameters: Date/time expressions supported by the Chrono-based parser (e.g. 4pm, friday, tomorrow 19:00, 2030-10-12T13:37).
  • Valid: "Task @4pm", "Task @friday", "Task @tomorrow 19:00", "Task @2030-10-12T13:37".
  • Invalid: "Task @ tomorrow" (space after @) — due date is not applied and the expression is stripped from the title. Two-digit years 50–99 are corrected to the current or next calendar year to avoid Chrono interpreting them as years (e.g. 90m in a date context).

Deadline Syntax (!)

  • Symbol: !
  • Purpose: Set a deadline date/time for the task.
  • Grammar: !<date-time-expression>. A space is required before ! when it is not at the start of the title.
  • Parameters: Date/time expressions supported by the Chrono-based parser (e.g. 14:30, friday, next month).
  • Valid: "Task !14:30", "Task !friday", "Task @monday !friday".
  • Invalid: "Done!" (no space before !) — the exclamation mark is treated as punctuation and no deadline is applied.

Formal Grammar and Regex Patterns

The parser uses regular expressions for each syntax form. Time: optional t prefix, digits and decimal with m/h, optional / for spent/estimate. Project: + with lookahead so delimiters (#, @, time-like tokens) inside the project name do not terminate the match. Tag: # followed by characters until a special character or whitespace. Due: @ followed by characters until a special character. Deadline: ! followed by characters until a special character. Exact patterns are defined in short-syntax.ts (e.g. SHORT_SYNTAX_TIME_REG_EX, SHORT_SYNTAX_PROJECT_REG_EX, SHORT_SYNTAX_TAGS_REG_EX, SHORT_SYNTAX_DUE_REG_EX, SHORT_SYNTAX_DEADLINE_REG_EX).

Default Values and Behavior

  • Time units: m = minutes, h = 60 minutes.
  • Time spent only: e.g. 30m/ sets time spent on the current day and no estimate.
  • Time estimate only: e.g. 1h sets estimate without time spent.
  • Date parsing: Uses a custom Chrono-based parser with year correction for two-digit years 50–99 (current/next year).
  • Project matching: Prefix-based, case-insensitive, spaces removed; shortest matching project title wins.
  • Tag mode: combine (default) or replace; configurable in settings.

Where Short Syntax Is Supported

Supported:

  • Add Task Bar (primary place for creating tasks with short syntax).
  • Task creation when adding new tasks (e.g. via the shared add-task action).
  • Task title updates when the only change is the title (syntax is re-parsed).

Unsupported or disabled:

Parsing and Evaluation Rules

  1. Order of processing: Due/deadline/time → Project → Tag.
  2. Title cleanup: Parsed syntax is removed from the task title after processing.
  3. Tag creation: Tags that do not exist yet are collected in a newTagTitles array for creation.
  4. Return value: The shortSyntax() function returns an object with task changes (and newTagTitles, remindAt, projectId) or undefined if nothing was parsed or syntax is disabled.

Error Handling

Malformed syntax:

  • Invalid syntax is ignored; the function may return undefined or only apply valid parts.
  • No exception is thrown; invalid tokens are skipped or left in the title as appropriate.
  • If a syntax type is disabled in settings, that form is not processed.

Edge cases:

  • Project names containing +, #, @, or time-like patterns are handled so that the project token is parsed correctly.
  • Two-digit years 50–99 in date expressions are corrected to the current or next year.
  • Time estimate tokens (e.g. 90m) in the same title as date expressions are parsed separately so Chrono date parsing does not consume the time estimate.

Add Task Bar Behavior

  • Toggle new task position: A toggle in the Add Task Bar controls whether the new task is added at the top or the bottom of the list.
  • Autocomplete: The Add Task Bar can suggest tags, projects, and date expressions while typing.

Notes

  • Short syntax is processed by the shortSyntax() function; it returns task changes or undefined when no changes are needed.
  • The five syntax forms are controlled by the global Short Syntax settings for project, tag, and due/deadline/time in 3.02-Settings-and-Preferences.

1.00-Quickstarts

2.00-How_To

Using Super-Productivity

Contributing to Super-Productivity

3.00-Reference

4.00-Concepts

Data-and-Integrations

Organizing

Planning

Doing

Reviewing

If you have further questions, please refer to the discussions page.