Situation. You maintain a repository: a README, specifications, plans, an AGENTS.md and a docs/ folder. The text must remain clean Markdown because Git, your team and your tools read it directly.
What you get at the end. Updated documentation, a readable Git diff and no conversion to explain during review.
1. Open the repository as a workspace
Choose File > Open… (⌘O), then the repository’s folder rather than a file.
Balise indexes it and shows two views on the left: Files and Outline.
Add the folder to Favorites through the toolbar’s locations menu. You can then reopen it in two clicks without returning to the macOS panel.
2. Write in the mode that suits the moment
The Visual and Source selector switches between modes on the same document at any time.
Visual mode helps with structure, tables and task checkboxes. Source mode is faster for correcting specific syntax or pasting technical content.
What you save remains Markdown in either mode.
3. Keep links working
The Document inspector reports links to missing files, missing images and missing anchors. Use it to maintain documentation as it grows.
4. Rename without breaking links
Rename a document from the file list, rather than Finder.
Balise first shows a full preview: the new name, any resource-folder move, the files whose links need updating and the line number of each change.
It then applies the rename and link updates together.
5. Insert a diagram when words are not enough
Insert opens the Mermaid gallery and places the source in the document as one undoable change.
The diagram renders locally without a network request. It remains text in your file, readable in a Git diff.
See Maintain a diagram alongside your code.
6. Review your diff before committing
Open the file’s diff in your usual Git tools before committing. Check exactly what the commit will contain.
Balise never writes to Git. Commit with your usual tools.
Share context with an assistant
Choose Copy context in the toolbar, then paste into Codex, Claude Code or your usual local agent. The last prepared summary comes first, followed by the filename linked to its absolute path. Neither the Markdown source nor the file itself is attached; a summary predating unsaved changes is flagged.
If something goes wrong
- Saving refused after a Git operation: When saving is refused
- Folder no longer opens: When Balise can no longer read a file or folder
- Every command in detail: The Markdown workspace