--- id: "canvas.notas.visao-geral" titulo: "Notes on the Canvas" resumo: "Use note cards as project memory: where the files live, how to edit them and how to search inside a note." idioma: "en" tipo: "guia" categoria: "telas" aplicavelDesde: "0.0.16" capabilities: ["note.cards.create", "note.cards.edit", "note.cards.find", "note.cards.colors", "note.files.location"] estadoEditorial: "aprovado" nivelEvidencia: "artefato-distribuido" refFonte: "27574c339b58316408f6be2d62169d59041d07bf" revisaoFonte: "2026-09-24" revisor: "mantenedor (v1, 2026-10-03)" rota: "/docs/en/canvas/notas/visao-geral/" fonte: "pt-br/canvas/notas/visao-geral.md" caminhoPublico: "docs/publica/en/canvas/notas/visao-geral.md" hashFonte: "sha256:83a99a861ff0206366df451aeb82561a66b89f13f47bf4121a7a19e34be9cd14" hashDestaPagina: "sha256:d173e03be7974522605e57dd4354b1f95fa42e8c57aefade1b1e1c7cb02889b9" traducaoAssistidaPorIA: true traducaoDesatualizada: false corpoRetido: false --- A **note card** is **Markdown** text stored in a `.md` file. It serves two purposes at once: it is your project memory on the board, and it is the material agents can read and write. Because it is a real file, the note outlives the app: closing and reopening loses no text, and any tool outside Elyra can read the same file. ## Where the files live Notes do **not** live inside the project. They live in a folder managed by the app, outside the repository, with one path per workspace, in the format: ``` ~/.elyra/projetos///notas/ ``` The project and workspace folder names carry an identifier suffix, so the exact path is not predictable offhand. **The real absolute path is what the command line returns in the `noteFilePath` field** when listing or reading a note — use that value when you need the file on disk. That decision has a practical reason: when notes lived inside the repository, a cleanup of untracked files (`git clean -xdf`) took the notes with it. Outside the project, that does not happen. Two consequences: - **A remote workspace over SSH is the exception.** In that case the notes folder stays **inside the checkout**, on the remote host. That is declared temporary, until remote home resolution exists — do not count on parity between local and SSH for notes. - **The note's stored identifier is not an address.** The card stores an identity in the `.elyra/notas/.md` format, which is not where the file actually is. Only `noteFilePath` is the real path. > **Old notes.** Notes that lived inside the project, in the two old folders, are **moved** to the managed folder. The migration runs at startup, **does not overwrite** a file already existing at the destination (a taken name gets a suffix) and, if it fails, **leaves the file where it is** to try again on the next startup. It is **best-effort**: a file can be left behind on a failure. ## Creating a note From the top bar: **Add Note › Note**. By right-clicking the background: **"Add here" › Note**. Both create the card and the file, and the newly created note's editor **receives focus automatically** — you can start writing. From the command line, the note is born with content already: ``` elyra canvas create note --title "Meeting summary" --content "First line" elyra canvas create note --content-file ./text.md ``` - `--content` writes the text into the file at birth. - `--content-file` reads from a file, or from `-` to read standard input. It is the path for **multi-line text** — shell quoting mangles newlines. - With `--title`, the file is born with that name and **the name is fixed**. - Without `--title`, **the name follows the content's first line**. Until you type a name, the card shows "automatic"; typing a name fixes it. The file name is sanitized: invalid characters become `-`, reserved system names get a prefix, and there is a length ceiling. You do not have to deal with that. ## Editing The card's body is a **rich editor** for Markdown, with a toolbar and a writing field with the hint "Write your note…". - **Saving is deferred by about 600 ms** after the last keystroke. That is why stopping typing for a moment and looking at the file on disk is how you confirm it was saved. - **Edits made outside the app show up in the card.** The app watches the file and reflects what changed. - **A read failure blocks the editor** instead of emptying the file. If the note cannot be read, the card warns and offers **Try again** — nothing was deleted, and you should check whether the file was moved or deleted outside Elyra. - **Closing during a pending edit** flushes the deferred save before deleting, so it does not recreate a file that should go away. ### Note tools The note's bar carries **bold**, **italic**, **strikethrough**, **list** and **numbered list**, plus the color palette. ### Background color The palette offers **Default**, **Yellow**, **Green**, **Blue**, **Pink**, **Purple** and **Gray**. Choosing **Default** clears the color. The color is a property of the **card**, not of the text: it **does not change the `.md` file** and therefore does not travel with the note if you open the file elsewhere. ## Searching inside the note The **"Search in note"** bar highlights and navigates results inside the card's body, with **Previous**, **Next** and a counter in the `current of total` format, plus **"No results"** when there is no match. **Esc** closes the search. The search is interface-only and changes neither the file nor the process. ## Writing to a note from the command line An agent can read and write the note without opening the editor: ``` elyra canvas note read [--workspace ] [--json] elyra canvas note write (--content | --content-file ) [--append] [--workspace ] [--json] ``` - `` accepts the **card id**, the **card title** or the **note name**. - **Without `--append`, the content replaces the whole file.** With `--append`, the text goes to the end, after a line break. - Without `--json`, the read prints **the raw content** of the note. > **Concurrent writing with the editor.** The command is the **newer writer**: text still in the editor's deferred save is discarded on purpose, and the card on screen picks up the new content through the file watcher. Before writing to a note that is open, save what you typed. > **The app must be open.** Without an application window, those operations are refused instead of writing to a state nobody sees. ## Limits - **A remote workspace over SSH.** Notes stay **inside the checkout** on the remote host, and the migration to the managed folder **does not run** in that case. There is no parity between local and SSH for notes. - **A note whose file is gone mounts no editor and writes nothing.** That is deliberate: it prevents autosave from recreating the empty file over what existed. The card shows the error, preserves the text it already knew, and offers **Try again**. - **Two cards with the same name make the selector ambiguous.** The command line asks you to use the **id** in that case — the name is convenience, not a unique address. - **There is no documented size limit for a note.** A large note is read and written whole; do not count on truncation or on a "too large" warning.