Notes on the Canvas

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/<project>/<workspace>/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/<name>.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 <note> [--workspace <selector>] [--json]
elyra canvas note write <note> (--content <text> | --content-file <path|->)
                              [--append] [--workspace <selector>] [--json]

• <note> 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.