---
url: /guides/write-a-task-description.md
description: >-
  Format a task's description: headings, checklists, tables, images, and
  @-mentions of people and #-mentions of tasks.
---

# Write a task description

Write a description when a task needs more than its title:

* the steps;
* the context;
* a table of figures;
* a screenshot.

The description is made of [blocks](/reference/editor-blocks). Three characters do most of the
work:

| Type | To |
|---|---|
| `/` | add a block: a heading, a checklist, a table, an image |
| `@` | mention a person |
| `#` | mention another task |

## Before you start

::: warning Edit access needed
To change a description you need [**Edit** access](/concepts/sharing) to the task's list, and a
[permission set](/reference/permissions-and-access) that lets you change the description.
Without it you can read the description, but not edit it.
:::

## Description editor: open and type

1. Open the task and click the description, or press `E`.
   The cursor is in the text, and the toolbar's controls appear above it.

   ![The description in edit mode with the cursor in the heading and the toolbar above it: block type, text styles, link and lists](/shots/guides/write-a-task-description-1.light.webp){.light-only}
   ![The description in edit mode with the cursor in the heading and the toolbar above it: block type, text styles, link and lists](/shots/guides/write-a-task-description-1.dark.webp){.dark-only}

   ::: tip Change the key
   `E` is the default key. You can change it in **User settings** → **Hot keys**, see
   [Keyboard shortcuts](/reference/keyboard-shortcuts).
   :::

2. Type.
   Hule saves as you type; there is no Save button. If someone else edits the same description
   at the same time, each of you sees the other's changes as they type.

::: info The same editor in the New Task form
The **Description** field of the **New Task** form works the same way
([Create and edit tasks](/guides/create-and-edit-tasks)).
:::

## Budget example: a description in four blocks

Build the description of the task "Draft the Q4 budget":

1. Type `/heading` and pick **Heading 2**.
   The line turns into a heading.

2. Type the heading and press `Enter`:

   ```text
   Steps
   ```

3. Type `/checklist` and pick **Checklist**.
   A checkbox appears at the start of the line.

4. Type three steps, pressing `Enter` after each, then press `Enter` on the empty item to leave
   the list:

   ```text
   Collect the invoices
   Fill in the budget template
   Send it to the accountant
   ```

   ::: info Checklist or subtasks?
   A checklist item is text with a checkbox: it has no status, date or assignee. When a step
   needs those, make it a [subtask](/guides/break-down-with-subtasks) instead.
   :::

5. Type the start of the next line, then `@Anna`, and pick Anna from the list:

   ```text
   Ask @Anna
   ```

   Anna's name turns into a chip, and she gets a notification.

6. Type the rest of the line, then `#Q3`, and pick the "Q3 budget report" task:

   ```text
   for the Q3 numbers, see #Q3
   ```

   The task turns into a chip, and "Q3 budget report" shows the relation **is mentioned in**.

7. On a new line, type `/banner` and pick **Banner Warning**.
   A colored box appears.

8. Type the deadline:

   ```text
   The accountant needs it by October 15.
   ```

![The description of Draft the Q4 budget: the heading Steps, a checklist of three steps, a line with a chip for Anna Smith and one for the task Q3 budget report, and a warning banner with the deadline](/shots/guides/write-a-task-description-2.light.webp){.light-only}
![The description of Draft the Q4 budget: the heading Steps, a checklist of three steps, a line with a chip for Anna Smith and one for the task Q3 budget report, and a warning banner with the deadline](/shots/guides/write-a-task-description-2.dark.webp){.dark-only}

## Slash menu: add a block

The `/` menu holds every block, grouped by kind. Type a word after the `/` to narrow it, for
example:

```text
/check
```

Pick a block with the arrow keys and `Enter`, or click it. Every block, with its keys and
Markdown shortcuts, is in [Editor blocks and shortcuts](/reference/editor-blocks).

![A / typed on an empty line, with the block menu open on its Basic group and Heading 2 in it](/shots/guides/write-a-task-description-3.light.webp){.light-only}
![A / typed on an empty line, with the block menu open on its Basic group and Heading 2 in it](/shots/guides/write-a-task-description-3.dark.webp){.dark-only}

::: warning A # starts a mention, not a heading
A `#` at the start of a word opens a task search. For a heading, use `/heading` or **Block type**.
:::

::: info The toolbar follows the cursor
While the cursor is in one of these blocks, the toolbar shows that block's own controls:

* a table;
* an image;
* a code block;
* a banner;
* columns;
* a chip.
  :::

## Mention a person or a task

1. Type `@` at the start of a word.
   A **Search people…** chip opens, with a list under it.

2. Type part of the person's name (spaces are fine), then pick them with the arrow keys and
   `Enter`, or click. `Esc` cancels.
   The chip shows the person's name.

   ![@Ann typed: the Search people chip with two people under it, Anna Smith and Annie Walsh](/shots/guides/write-a-task-description-4.light.webp){.light-only}
   ![@Ann typed: the Search people chip with two people under it, Anna Smith and Annie Walsh](/shots/guides/write-a-task-description-4.dark.webp){.dark-only}

   ::: info Who you can mention
   The list offers the [workspace's](/concepts/hule-model) members and the people the list is
   [shared](/guides/share-a-folder-or-list) with.
   :::

3. For a task, type `#` at the start of a word.
   A **Search tasks…** chip opens, with your recent tasks under it.

4. Type part of the task's title or its [Task ID](/reference/task-ids), and pick it.
   The chip shows the task's title and status.

   ![#Q3 typed: the Search tasks chip with three tasks under it, Q3 budget report first](/shots/guides/write-a-task-description-5.light.webp){.light-only}
   ![#Q3 typed: the Search tasks chip with three tasks under it, Q3 budget report first](/shots/guides/write-a-task-description-5.dark.webp){.dark-only}

What a mention does:

| Mention | What Hule does |
|---|---|
| `@` a person | sends them a [notification](/guides/set-up-notifications) once, when you add the mention, and adds them to the task's [watchers](/guides/assign-and-watch-tasks) |
| `#` a task | adds a **mentions** [relation](/concepts/relations) from this task to that one; the other task shows **is mentioned in** ([Link related tasks](/guides/link-related-tasks)) |

## Pasted links and screenshots

* **Paste a web link on its own**, with nothing selected: it becomes a link preview, a chip with
  the page's title and icon. Click it to open the page.
* **Paste a screenshot**: it becomes an **Image** block, uploaded to the workspace.
* **Paste a link to a Hule task on its own**: it becomes a task mention.
* **Paste formatted text or Markdown**: it turns into blocks.

::: warning Workspace storage
If an upload fails with **Workspace storage limit reached**, the workspace has used its storage.
Remove files you no longer need from tasks and comments. **Storage** in **Workspace settings**
shows what is used ([Limits](/reference/limits)).
:::

Every case is in [Paste rules](/reference/editor-blocks#paste-rules).

## If it doesn't work

* **Typing `#` opens a task search instead of a heading.** `#` at the start of a word starts a
  task mention. Press `Esc`, then use `/heading` or **Block type** in the toolbar
  ([Slash menu: add a block](#slash-menu-add-a-block)).
* **The person you want isn't offered after `@`.** Only the workspace's members and people the
  list is shared with can be mentioned.
  [Share the list](/guides/share-a-folder-or-list) with them, or
  [invite them to the workspace](/guides/invite-members-and-grant-permissions).
* **The task you want isn't offered after `#`.** The search covers the task's own workspace, and
  only lists you can open. Paste the other task's link on its own: it becomes a mention chip, but
  a task in another workspace gets no relation
  ([Paste rules](/reference/editor-blocks#paste-rules)).
* **You can't type in the description, and there is no toolbar.** Either you have no **Edit**
  access to the list ([Share a folder or a list](/guides/share-a-folder-or-list)), or your
  permission set can't change the description
  ([Permissions and access](/reference/permissions-and-access)). Ask a workspace admin.
* **Pasted text brought formatting you don't want.** Undo, then paste with
  **Paste as plain text**: `Cmd+Shift+V` (`Ctrl+Shift+V`)
  ([Editor keys](/reference/editor-blocks#editor-keys)).
* **A pasted link stayed a plain link, not a preview.** A preview appears only when you paste one
  link on its own, with no text selected
  ([Pasted links and screenshots](#pasted-links-and-screenshots)).

## Related

* [Editor blocks and shortcuts](/reference/editor-blocks): every block, shortcut and paste rule.
* [Create and edit tasks](/guides/create-and-edit-tasks): the rest of a task's fields.
* [Link related tasks](/guides/link-related-tasks): the relations a `#` mention adds, and the
  other types.
* [Comment and mention people](/guides/comment-and-mention): the same editor in comments, where
  your text is saved when you post it.
* [Keyboard shortcuts](/reference/keyboard-shortcuts): every key in one table.