sticky notes doc (#1157)

* sticky notes changelog

* add sticky note doc

* add tip in the flow quickstart

* fix changelog link

---------

Co-authored-by: Henri Courdent <122811744+hcourdent@users.noreply.github.com>

Author: Guilhem-lm

changelog/2025-11-20-sticky-notes-in-flows/index.md

@@ -11,5 +11,5 @@ features:
     'Group notes that anchor around a group of nodes to explain sections or logical blocks.',
     'Drag and position notes freely to annotate your workflow.'
   ]
+docs: /docs/flows/sticky_notes
 ---
-

docs/assets/flows/free_note_example.png

@@ -207,6 +207,12 @@ The Flow editor has the following features which are the subject of specific pag
 		description="When a step is mocked, it will immediately return the mocked value without performing any computation."
 		href="/docs/flows/step_mocking"
 	/>
+	<DocCard
+		color="teal"
+		title="Sticky notes"
+		description="Annotate flows with documentation using free notes and group notes."
+		href="/docs/flows/sticky_notes"
+	/>
 </div>
 
 <br />

docs/assets/flows/group_note_example.png

@@ -0,0 +1,119 @@
+import DocCard from '@site/src/components/DocCard';
+
+# Sticky notes
+
+Sticky notes allow you to annotate flows with documentation, comments, and organizational information directly on the flow canvas. Notes help document workflow logic, add TODOs, or explain complex sections to team members.
+
+<video
+	className="border-2 rounded-lg object-cover w-full h-full dark:border-gray-800"
+	controls
+	src="/videos/sticky_notes_intro.mp4"
+/>
+
+<br />
+
+There are two types of sticky notes:
+
+- **Free notes**: Can be placed anywhere on the canvas for general comments or documentation
+- **Group notes**: Attached to a selection of nodes to document specific workflow sections
+
+## Creating sticky notes
+
+### Free notes
+
+Create free notes to add general documentation or comments anywhere on the flow canvas.
+
+**Method 1: Toolbar button**
+
+1. Click the sticky note button in the top toolbar
+2. Drag and drop on the canvas to position the note
+
+**Method 2: Context menu**
+
+1. Right-click anywhere on the canvas
+2. Select "Add sticky note" from the context menu
+
+![Sticky notes interface](../assets/flows/sticky_notes_interface.png 'Sticky notes interface - toolbar with sticky note button and toggle')
+
+### Group notes
+
+Group notes attach to multiple selected nodes to document specific workflow sections or logical blocks.
+
+**Creating group notes:**
+
+1. Enter selection mode by clicking the cursor/hand button in the top-right of the flow pane
+2. Select multiple nodes by clicking and dragging or clicking individual nodes while holding Shift
+3. Click "Create group note" button that appears when nodes are selected
+
+**Selection mode tips:**
+
+- In selection mode: Hold Ctrl/Cmd to temporarily pan the canvas
+- In pan mode: Hold Ctrl/Cmd to temporarily select nodes
+
+![Group note example](../assets/flows/group_note_example.png 'Group note attached to multiple flow nodes')
+
+## Managing sticky notes
+
+### Editing content
+
+Double-click any note to edit its content. Notes support GitHub-flavored Markdown (GHMd) for formatting.
+
+### Customizing appearance
+
+Each note has an action bar in the top-right corner with the following options:
+
+- **Color picker**: Change note color (supports both light and dark themes)
+- **Lock icon**: Lock the note to prevent accidental editing or movement
+- **Delete button**: Remove the note from the flow
+
+![Sticky note action bar](../assets/flows/sticky_note_action_bar.png 'Action bar with color picker, lock, and delete buttons')
+
+### Positioning notes
+
+Drag notes freely around the canvas to position them where most relevant. Locked notes cannot be moved until unlocked.
+
+## Hiding and showing notes
+
+Use the toggle button in the top-left of the flow pane to hide or show all sticky notes. This is useful when you need a clean view of the flow logic or when presenting to stakeholders.
+
+## Free note example
+
+Free notes are ideal for:
+
+- General flow documentation
+- TODO items for future improvements
+- Warnings or important considerations
+- Links to related resources or documentation
+
+![Free note example](../assets/flows/free_note_example.png 'Standalone free note with sample content')
+
+## Working with group notes
+
+Group notes automatically maintain their association with the selected nodes. However, there are some limitations when editing the grouped nodes:
+
+**To modify nodes in a group note:**
+
+- **Option 1**: Delete the note, make your node changes, then create a new group note with the updated selection
+- **Option 2**: Edit the flow directly in YAML/JSON format to modify the grouped nodes while preserving the note
+
+Group notes are particularly useful for:
+
+- Documenting complex logic blocks
+- Explaining error handling sections
+- Describing data transformation steps
+- Marking deprecated or experimental features
+
+<div className="grid grid-cols-2 gap-6 mb-4">
+	<DocCard
+		color="teal"
+		title="Flow editor components"
+		description="Details on the flow editor's major components including toolbar and canvas features."
+		href="/docs/flows/editor_components"
+	/>
+	<DocCard
+		color="teal"
+		title="Testing flows"
+		description="Iterate quickly and get control on your flow testing."
+		href="/docs/flows/test_flows"
+	/>
+</div>

docs/assets/flows/sticky_note_action_bar.png

@@ -34,6 +34,9 @@ Here are the different options available in the toolbar:
 - **Tutorial button**: follow the tutorials, reset them or skip them.
 - **Diff**: view the diff between the current and the last [version](../core_concepts/0_draft_and_deploy/index.mdx) of the flow.
 - **AI Builder**: [build flow with AI](./17_ai_flows.mdx).
+- **Sticky notes button**: add [sticky notes](./24_sticky_notes.mdx) to annotate the flow.
+- **Notes toggle**: hide or show all sticky notes on the canvas.
+- **Selection/Pan mode toggle**: switch between selection mode for creating group notes and pan mode for navigation.
 - **Test flow**: open the flow [test](../core_concepts/23_instant_preview/index.mdx) slider.
 - **Test up to**: open the flow [test](../core_concepts/23_instant_preview/index.mdx) slider.
 - **Draft**: save the flow as [draft](../core_concepts/0_draft_and_deploy/index.mdx) (you can do it with shortcut `Ctrl + S` / `⌘ S`).

docs/assets/flows/sticky_notes_interface.png

@@ -137,6 +137,10 @@ On the left of the editor, you'll find a graphical view of the flow. From there
 
 ![Flow editor menu](./flow_editor_menu.png.webp)
 
+:::tip Pro tips
+Keep your flows organized and documented with [sticky notes](../../flows/24_sticky_notes.mdx)! Add free notes anywhere on the canvas for comments and TODOs, or create group notes to explain complex workflow sections to your team.
+:::
+
 There are four kinds of scripts: [Action](../../flows/3_editor_components.mdx#flow-actions), [Trigger](../../flows/10_flow_trigger.mdx), [Approval](../../flows/11_flow_approval.mdx) and [Error handler](../../flows/7_flow_error_handler.md). You can sequence them how you want. Action is the default script type.
 
 Each script can be called from Workspace or [Hub](https://hub.windmill.dev/), you can also decide to write them inline.
@@ -167,15 +171,15 @@ Your flow can be deepened with [additional features](../../flows/1_flow_editor.m
 While loops execute a sequence of code indefinitely until the user cancels or a step set to [Early stop](../../flows/2_early_stop.md) stops.
 
 <video
-    className="border-2 rounded-xl object-cover w-full h-full dark:border-gray-800"
-    controls
-    src="/videos/while_early_stop.mp4"
+	className="border-2 rounded-xl object-cover w-full h-full dark:border-gray-800"
+	controls
+	src="/videos/while_early_stop.mp4"
 />
 
-<br/>
+<br />
 
 <div className="grid grid-cols-2 gap-6 mb-4">
-<DocCard
+	<DocCard
 		color="teal"
 		title="While loops"
 		description="While loops execute a sequence of code indefinitely until the user cancels or a step set to Early stop stops."
@@ -310,4 +314,4 @@ Flows are not the only way to write distributed programs that execute distinct j
 		description="Automate tasks and their flow with only code."
 		href="/docs/core_concepts/workflows_as_code"
 	/>
-</div>
+</div>

docs/flows/1_flow_editor.mdx

@@ -746,7 +746,8 @@ const sidebars = {
 						'flows/early_return',
 						'flows/flow_approval',
 						'flows/sleep',
-						'flows/step_mocking'
+						'flows/step_mocking',
+						'flows/sticky_notes'
 					],
 					collapsed: true
 				},