Balise opens files that existed before it and will continue to exist after it. This page describes what happens on entry and exit.
Create a file
File > New file (⌘N) opens the creation center. Choose explicitly what to start:
- an empty Markdown document;
- a Markdown document based on an agent brief, feature, bug report, README, project decision or meeting notes;
- a CSV data file;
- a Mermaid diagram.
Each creation opens its own window. You can keep several documents, datasets and diagrams open in parallel.
Use a Markdown template
In New file > Markdown, choose Balise templates or My templates. Search finds a template; the star puts it at the top of its list. A click shows its preview; a double-click creates the document directly.
Balise templates offer an Outline and a Filled example. Create document always uses the outline, even while viewing the example. The example is not added to the created document.
To reuse your own structure, open a Markdown document and choose File > Save copy as template…. Balise saves an independent .md copy without saving or replacing the starting document.
The gallery’s folder menu lets you choose another template folder, reveal it in Finder or refresh it. Its .md and .markdown files appear in My templates. You can edit them elsewhere; the gallery reloads them when you return to Balise.
Edit template opens the original file. Create document opens an independent copy whose edits do not change the template. Returning to the default folder deletes no files from the previous folder.
Open the examples
Choose Help > Show Balise Examples. Balise opens a new window with an editable copy of the original examples included in the installed version. Examples follow the language selected in Settings > General > Language.
You can edit them to try Markdown editing, data and diagrams. The next use of Show Balise Examples starts from the originals, even if you changed a previous copy. After updating Balise, this command uses the examples included in the new version. It does not download content from the Internet.
Previous experiments remain in their own copies; opening new examples does not overwrite them. To keep a document in a location of your choice, use File > Save As (⇧⌘S). To resume a saved experiment, reopen its file with File > Open… (⌘O).
Open a file
File > Open… (⌘O) accepts multiple selections and creates one window per file. You can also drag a file onto Balise’s icon, open it from Finder or run open -a Balise file.csv in a terminal.
Opening a folder is different: Balise makes it a Markdown workspace. It indexes compatible files inside it, and you navigate among them without returning to Finder.
Folders with names ending in .assets are hidden from navigation. They still hold associated images and other files; your documents' links continue to use them. Open these folders in Finder to inspect them.
Import a file
File > Import… converts an external document to a new Markdown or CSV copy. A preview shows the result before creating the document. The copy remains unsaved and uses the converti suffix; choose its location on first save.
Structured documents may offer Markdown and CSV. For multi-sheet files, import one sheet or all sheets. Local images follow the Markdown copy into its assets folder.
See Formats and conversions for the exact formats and security limits.
Find your locations
The toolbar’s locations menu keeps frequent folders and files. Open a target, add the current file or folder to Favorites, then rename, reorder, reconnect or remove a favorite.
Favorites are separate for each workspace: Markdown, Data and Mermaid have their own lists. Only Markdown accepts complete folders.
In the locations menu, Open Parent Folder moves up one level from the displayed folder. The action is disabled when no parent folder is available.
Save
File > Save (⌘S) writes directly to the standard file. There is no intermediate export step: the document you edit is the file your other tools will read.
File > Save As (⇧⌘S) writes a copy elsewhere and continues the session on that copy.
Opening and saving without changes leaves the file identical, byte for byte.
When a file changes while you work
Before replacing a file, Balise checks that it has not changed on disk since opening. If another application modified it, saving is refused and a comparison opens.
You see the saved baseline, your local version and the disk version side by side. Three outcomes are offered: leave the conflict without acting, reload the disk version or save yours under a new name.
None replaces the disk version without your request. See When saving is refused for details.
Close without losing work
A tab or window indicates unsaved changes. Before closing, Balise offers to save, discard or cancel.
Meanwhile, a recovery copy is periodically written for modified documents. It is for abrupt interruptions only and never replaces your file. See Local versions and recovery.
What this surface does not do
- Balise does not automatically save over your file: ⌘S remains your decision.
- Balise never replaces an imported file; it creates an unsaved copy.
- Balise does not merge conflicting file versions; it shows three states and lets you choose.
- Balise does not synchronize with a remote service.