Bref

Bref is a fast, minimal note-taking app. Your notes are plain Markdown files in a folder you choose, styled as you type. It is written in Rust with GPUI, a GPU-accelerated UI framework.

New here? Install Bref, then read First steps.

What it does

Bref speaks English and French, following the language of your system.

Conventions in this guide

• Keys are written for Linux and Windows. On macOS, read Cmd for Ctrl, and Alt for Ctrl when moving by word.
• The keys shown are the defaults. The help panel (F1) always shows the ones in effect, and lets you change them.
• Bold names a button, a menu entry or a palette command, as written in the app.

Install

Arch, macOS and Windows have a ready-made download. Everywhere else, Bref is compiled on your machine. The first build takes a few minutes.

Compiling needs a recent stable Rust. If rustc --version shows less than 1.88, install Rust with rustup.

Arch Linux

Every release ships a ready-to-install package. No compiler is needed, and pacman tracks it as bref.

curl -LO https://github.com/alarboulletmarin/bref/releases/latest/download/bref-x86_64.pkg.tar.zst
sudo pacman -U ./bref-x86_64.pkg.tar.zst

Download the file first, as above. The package is not signed: given a URL, pacman looks for a .sig file and warns when there is none.

To follow main, build the development package from a checkout. It needs cargo and git, and conflicts with bref.

git clone https://github.com/alarboulletmarin/bref.git
cd bref/aur/bref-git
makepkg -si

To build the latest tagged release yourself, run makepkg -si from the root of the repository.

Bref is not on the AUR yet.

macOS

Download bref-macos.dmg. It runs on Apple Silicon and Intel. Open it and drag Bref to Applications.

The app is not notarized, because that needs a paid Apple Developer account. So macOS blocks the first launch:

1. Open System Settings, then Privacy & Security.
2. Scroll down and click Open Anyway.

Or run this once in a terminal:

xattr -dr com.apple.quarantine /Applications/Bref.app

To compile it yourself, you need Xcode (the full app, for the Metal shader compiler) and Rust:

git clone https://github.com/alarboulletmarin/bref.git
cd bref
cargo install --path . --locked

This installs the bref command in ~/.cargo/bin, without the .app bundle. Start it from a terminal.

Windows

Download bref-windows-x86_64-setup.exe and run it. It installs for your user only, with no administrator rights, and adds a Start menu entry and an uninstaller.

To install nothing, take bref-windows-x86_64.zip instead. Unzip it anywhere and run bref.exe.

The files are not signed, because a code-signing certificate costs a few hundred euros a year. SmartScreen may show "Windows protected your PC": click More info, then Run anyway.

To compile it yourself, you need the Visual Studio C++ build tools with the Windows SDK, and Rust with the MSVC toolchain:

git clone https://github.com/alarboulletmarin/bref.git
cd bref
cargo install --path . --locked

This installs bref.exe in %USERPROFILE%\.cargo\bin.

Ubuntu, Linux Mint, Debian

1. Install the build tools and libraries:

   sudo apt install build-essential pkg-config libfontconfig-dev libfreetype-dev \
     libwayland-dev libxcb1-dev libxkbcommon-dev libxkbcommon-x11-dev libvulkan1 \
     fonts-noto-color-emoji
   

2. Install Rust with rustup. The cargo from apt is usually too old.

3. Build and install:

   git clone https://github.com/alarboulletmarin/bref.git
   cd bref
   make
   sudo make install
   

Fedora

Follow the steps above with these packages. Their names have not been tested.

sudo dnf install gcc pkgconf-pkg-config fontconfig-devel freetype-devel \
  wayland-devel libxcb-devel libxkbcommon-devel libxkbcommon-x11-devel vulkan-loader \
  google-noto-color-emoji-fonts

Other Linux distributions

You need:

• the development files of fontconfig, freetype, Wayland, libxcb and libxkbcommon (with its X11 part);
• a Vulkan driver for your GPU;
• an emoji font, such as Noto Color Emoji, for 🎉 in notes and names;
• Rust.

Then:

make                    # cargo build --release --locked
sudo make install       # PREFIX=/usr/local by default, PREFIX=/usr for a system-wide install

make install adds the bref command, an entry in your application menu, and its icon. sudo make uninstall removes them.

Upgrading

On Arch (prebuilt package), macOS and Windows (installer), Bref updates itself: click Update in the banner. Otherwise:

Coming from encre

Bref was called encre until version 0.1.4. Your notes are untouched. Settings saved under the old name are still read, and written under the new one the next time they change.

First steps

Choose a vault

On first launch, Bref asks for a vault: the folder that holds your notes.

• Start in ~/Documents/Notes creates it there, or in your home folder if you have no Documents. A folder already there is opened as it is.
• Open another folder… picks an existing one. Dropping a folder on the welcome screen does the same.
• Clone a vault from a git address… fetches a vault kept in git. See Syncing a vault.

That is the only setup. Bref remembers the vault and the last note you had open. Ctrl + O changes the vault at any time.

On Linux, you can put Bref one key away: bind the command bref in your desktop settings (GNOME: Settings → Keyboard → Custom Shortcuts).

Write

Start typing. The first line is the title of the note, and the name of its file. There is no save button: notes are written to disk as you type. See Files on disk for how files are named and saved.

Ctrl + N creates a new note. Ctrl + J opens today's note, or creates it.

The bottom right of the note counts its words and characters, or those of the selection. Characters are counted as written, Markdown markers included, line ends excluded.

The blank page

An empty note shows, under the line you write on:

• today's date (a click opens the note of the day);
• the keys that matter;
• what to read again: the daily notes of a week, a month and a year ago, and one note you have not touched for a month or more, a different one each day.

A click opens any of them. The first key you type clears the page.

Find anything: the palette

Ctrl + P opens the palette. Type to search, Enter opens the selected note.

• Notes whose name matches come first. CSV tables, pictures and diagrams are found by their file name too (contacts.csv).
• Then come the notes whose text contains every word you typed (from two letters), with the line where the first word appears.
• Each row shows the note's folder and, on the right, how long ago it was written. A line of keys under the list reminds the main gestures.
• If no note has that name, the last row creates it.
• # lists the notes carrying a tag.
• > switches to the command palette: >bold, >delete row.

With nothing typed, on a CSV table or in a table of a note, the palette offers their gestures under the recent notes.

Every command: the command palette

F10 (or Ctrl + Shift + P, or the first button of the rail) opens the command palette. It lists every command the current view can do, with an icon, a short name and its keys. Commands are grouped, and those of what you are on (a block, a table, a diagram) come first.

Type to find a command by what it does, then Enter runs it where you were. Any word of its name works, accents ignored:

• folder offers New folder;
• table offers the settings of the CSV table on display (delimiter, encoding, header row, copy as, export);
• diagram, theme, font and update offer theirs too.

Every shortcut: the help panel

F1 (or Ctrl + /) opens the list of shortcuts, on the keys of what is on display: a CSV table, a diagram, a table of the note.

• A link per section sits at the top.
• Type to search, by key or by effect (ctrl+p, graph). Esc empties the search, then closes.
• Click the keys of a row to change them.
• At its foot: the version of Bref, and links to its source and to its Ko-fi page.

The full list is also in Keyboard shortcuts.

Menus

A right click in a note opens a menu: open the link under the pointer or copy its address, cut, copy, paste, bold, italic, underline, strikethrough, highlight, code, make or edit a link, comment (or resolve the comment under the pointer), and turn the lines into a bulleted, numbered or task list, or plain text.

Shift + F10 (or the Menu key) opens the same menu at the cursor. In the panel, it opens the menu of the selected line. Arrows, Home and End walk it, Enter runs, Esc closes and gives the keys back.

The menus show, beside each action, the shortcut that does the same. Pointing at an icon of the rail or of a bar names it, with its shortcut.

Quit

Ctrl + Q quits. Bref reopens with the panel, tabs and panes as you left them.

Writing notes

What you type is what is saved. Bref only changes how it looks: markers stay visible but dimmed, and the file on disk is always plain Markdown.

Markdown

Some details:

• Panels: NOTE, TIP, IMPORTANT, WARNING and CAUTION each have their color, as on GitHub.
• Code blocks: name the language (```rust) to get it colored. The copy icon on the first line copies the content of the block.
• Mermaid: the diagram is drawn under its block once the cursor has left it. The magnifier next to the copy button shows it full size, to zoom and move around.
• Formulas: a formula is drawn under its line, not within the text. Only the first one of a line is drawn.
• Arrows: the symbols are shown everywhere except on the line you are editing and inside code.
• Not rendered: footnotes and pictures given as a web address are kept as you typed them.

Inline styles

• With a selection, the key wraps it in the signs. The same key takes the style off again.
• Without a selection, the signs are inserted and the cursor waits between them.
• Over several lines, each line gets its own signs. Bullets, blanks and code blocks stay as they are.
• == does not highlight inside a word, so the abc== of an address stays as it is.
• <mark> is plain HTML, so other apps still show the text highlighted.
• In a table, a selection over several cells, or a row, column or table taken by its grip, styles the text of each cell (| **Léa** | **31** |), never a |. Empty cells are skipped. One Ctrl + Z undoes the whole gesture.

The formatting bar

A small bar at the bottom of the note, centered, applies styles with a click: bold, italic, underline, strikethrough, highlight (with a choice of five colors), code, link, then bulleted, numbered and task lists, and a table.

• A button lights up when the selection already has the style. A second click removes it.
• Inside a table, the table button gives way to row and column buttons: add, delete.
• With two panes, only the one you write in shows the bar.
• When the word count needs room, the bar slides left. When the note is too narrow for both, it folds into one button (a letter with an underline) that opens it above the text. In a very narrow window its buttons wrap onto several lines. Esc or a click in the text closes it.

Formatting bar in the palette shows or hides it. See Settings.

Lists

• - , 1. and [] start a list. Enter continues it. On an empty item, Enter leaves the list.
• Numbering stays in order as you add, remove or indent items.
• Tab and Shift + Tab indent and outdent the selected lines, or the current list item.
• Ctrl + Enter checks or unchecks a task or a [ ] box, and turns a bullet into a task. In a table cell, it adds a box.

Ctrl + Shift + B turns the selected lines (or the line of the cursor) into a list, then into the next kind each time: bullets, numbered, tasks, plain text.

• The right-click menu and the palette (bulleted, numbered, task, plain text) go straight to the kind you want. The same kind again gives back plain text.
• Indentation is kept. A numbered list restarts at 1 on each level. A ticked box stays ticked from one task list to another.
• Headings, tables, quotes and code are left alone.
• One Ctrl + Z undoes it. Each kind can get its own key in the help panel.

Slash commands

Type / at the start of a line or of a word: a list offers what can be inserted there.

• Keep typing to filter it by name (/h2, /todo, /table) or by label (/panel lists the five panels).
• Up and Down choose, Enter or Tab inserts, Esc dismisses.

What lands in the note is plain Markdown.

Blocks

Pointing at a line shows a grip on its left (⋮⋮). A block is a heading, a line of text, a list item with what is indented under it, a quote or a panel, a code block, or a table.

• Drag the grip to move the block. A line shows where it lands.
• Click the grip to select the block and open its menu: turn it into text, a heading, a list, a quote or a code block; duplicate it; move it up or down; copy, cut, comment or delete it.
• The + left of the grip adds a line under the block and opens the / list.
• Alt + Up and Alt + Down move the block of the cursor. In a table, they move its row.

Blank lines between blocks travel with them. The first line, the title of the note, stays first.

Links in the text

• [text](address) is a link to an address with a protocol (https://, mailto:…). A file of the vault is linked with [[name]] instead.
• Ctrl + K makes the selection a link, [text](address). On a link, it selects the address to change it. It does not work over several cells of a table.
• Ctrl + V over a selection: a pasted address makes it a link.
• Ctrl + click opens a [[link]], a #tag, a URL or a [text](address) link.

Links between notes are covered in Links, embeds and files.

Several cursors

• Ctrl + D selects the word under the cursor. Pressed again, it adds a cursor on its next occurrence.
• Alt + click adds a cursor where you click (not in a table).

What you type, delete or move then applies to every cursor, and one undo undoes it for all. Esc goes back to one cursor.

Outline

Ctrl + Shift + O (or Outline of the note in the palette) lists the headings of the note, indented by level. The section the cursor is in is selected.

• Type to filter.
• ↑ and ↓ show each heading in place as you move.
• Enter leaves the cursor there. Esc puts it back where it was.

Headings inside code blocks are not listed.

Copy

Ctrl + Shift + C copies the code block the cursor is in, otherwise the whole note. The icon at the bottom right of the note copies the note too.

Editing keys

Tables and formulas

Make a table

• /table opens a grid under the cursor. Move the pointer over it, or use the arrows, to choose the number of columns and rows, then click or press Enter. The empty table is written, and the cursor waits in its first cell. For a table larger than the grid, type its size while the grid is open, columns first: 12x5.
• By hand: | a | b | then Tab is enough. The line of dashes is written for you.
• The formatting bar has a table button too.

How a table looks

A table is drawn as a grid, like on the web:

• Columns share the width of the page. A long cell wraps inside its column, and its row grows. A short column keeps its natural width.
• The header row is in bold. :--, :-: and --: under it align a column.
• The text underneath is plain Markdown. The |, the line of dashes and the padding are not drawn.
• A literal | in a cell is written \| and shown as |.
• The columns of the text are aligned as you type, so the file reads well in other editors. Wide characters (ideograms, emoji) count as two. A table too wide to stay aligned is written compactly.
• A table wider than the text can spill out on both sides of the column, or scroll inside it. See wide tables in Settings. Only a table with more columns than the page can show, even at their narrowest, scrolls sideways (Shift + wheel or a horizontal swipe), following the cursor.

Move and type

• Tab and Shift + Tab go to the next and previous cell, and select its content: typing replaces it. After the last cell, Tab adds a row.
• Enter adds a row under the current one. On a last row left empty, it removes that row and leaves the table.
• Arrows move from cell to cell without stopping on the |. Up and Down follow the lines of a wrapped cell, then go to the cell below.
• Backspace and Delete stop at the edge of a cell.
• Selecting several cells and erasing, cutting or typing empties them, without merging the columns.
• Ctrl + Shift + L, E and R align the column of the cursor left, centered or right.

Rows and columns

Two + buttons appear when the pointer or the cursor is on a table: the one below adds a row, the one on the right adds a column.

Grips. With the pointer over a table, a small grip (three dots) shows above the column and left of the row under it. A round one sits near the top left corner. A click takes the column, the row or the whole table, and outlines it. Then:

• Ctrl + C and Ctrl + X copy and cut it as a Markdown table. It pastes as a table in another note, an issue or a mail.
• Delete empties its cells. The shape of the table stays.
• Drag a column or row grip to move it. A line shows where it will land, and Esc lets go. The header row stays first.
• The + between two grips inserts a column or a row right there.
• A right click on a grip takes it and opens the menu.

The menu. Right click in a table, or type the name of the gesture in the palette (row, column, sort, swap):

• insert a row above or below, or a column left or right;
• duplicate, move or delete a row or a column;
• sort the rows on the column of the cursor, A to Z or Z to A: numbers by value, empty cells last, the header stays put;
• swap rows and columns;
• delete the whole table.

Gestures apply to every row and column the selection touches. One Ctrl + Z takes a gesture back.

Keys. Alt + Up and Alt + Down move the row (the header stays first). Ctrl + Shift + Backspace deletes it, or the columns taken by their grip. Every gesture is in the help panel, where it can get a key of its own.

Deleting the header makes the next row the header. Deleting the last column or row deletes the table. To remove a column by hand, delete its cells.

Paste

• In a table, text goes into one cell, on one line, its | escaped. Cells copied from a spreadsheet or a web page (tab-separated), or from another Markdown table, fill the grid from the current cell. Rows and columns are added as needed.
• Under a table, a pasted line becomes part of it, and its columns line up.
• Anywhere else, a pasted Markdown table or tab-separated cells become a table on their own lines, aligned, with the line of dashes added.

Formulas

A cell that starts with = computes. The file keeps the formula; other apps show its text.

=B*C
=sum(above)
=avg(B1:B9)
=round(B/C, 2)
=if(B>10, "big", "small")

References

• Columns are letters. Rows are numbers, counted from the first row under the header, as in a spreadsheet: C2, B1:B10.
• B alone is column B of the formula's own row, so the same formula works on every line.
• above, left and column (the other cells of the column) are ranges by position.

Functions and operators

• Functions: sum, avg (or average), min, max, count, round, abs, if.
• Operators: + - * / ^ %. 15% is a hundredth, 7 % 3 a remainder.
• Comparisons: = <> < <= > >=. Parentheses group.
• Arguments are separated by , or ;. Decimals in a formula use a point.

Numbers in cells are read as written: 1 234,5, 1,234.5, 12.50 €, $3, 15%. With a single separator, it is the decimal one: 1,234 is 1.234. Write 1 234 or 1,234.00 for a thousand. The sort of a table reads numbers the same way. Text and empty cells are left out of sums.

Results

• The result shows in the cell, right-aligned, in another color. With the cursor in the cell, the formula shows instead, ready to edit.
• A cell with no result shows #ERR. Pointing at it says why: unknown function, reference out of the table, a cell that depends on itself, a text where a number is needed, a division by zero…
• Results follow what you type. Only a table that has formulas is computed, and not a very large one. A table of 1,400 rows with a running total in each row takes about 25 ms per keystroke.

Helpers

• Alt + = writes a total in the cell: the sum of the cells above, or on its left when only those hold numbers. A cell with something else in it is not overwritten.
• After =, completion offers functions, ranges, and the columns by letter or header.
• Ctrl + C on cells keeps the formulas: they paste back as formulas.
• Ctrl + Alt + C, or copy the cells with their results in the palette, copies the taken cells (or the table) with their results, as tabs and line breaks, for a spreadsheet.

Formulas are for the tables of a note, not for the CSV grid.

Very large tables

Past 1,500 rows (a whole CSV turned into Markdown, for instance), a table is no longer laid out as one block:

• Its columns are sized from its first 300 rows.
• Cells stop wrapping, and what overflows is cut, so every row has the same height.
• Only the rows near the screen are drawn.

A table of 300,000 rows opens in about 40 ms, and typing in it takes under 10 ms.

Such a table keeps Tab, Shift + Tab and Enter, but has no grips, no row and column gestures, and its columns are not realigned as you type.

Links, embeds and files

Links between notes

• [[ suggests your notes. A link to a note that does not exist creates it.
• [[Groceries]] finds the note by file name, in any subfolder, ignoring case.
• [[Note|alias]] shows another text. [[Note#Heading]] points at a heading.
• @ suggests days and links to the daily note of that day: @today, @tomorrow, @yesterday, a weekday (@monday: the next one, never today), or a date (@2026-10-09). French names work too (@demain, @lundi). An address such as name@domain suggests nothing.
• Ctrl + click opens a link. Ctrl + Shift + click opens it in the pane beside.
• Each name in the aliases of a note's front matter is another name for it: suggested after [[, and followed by links, backlinks and the graph.

When a note is renamed, the links to it follow. See Renaming.

Backlinks

The Backlinks view of the panel (Ctrl + L) lists the notes that link to the open one, each with the line that holds the link.

• Links written with an alias, and links inside tables, count.
• Embeds count too, marked embedded.
• The list follows the note you open, not the one you preview while moving through the list. So you can look at each linking note in turn.

Tags

A #tag in the text, or a tags key in the front matter, tags a note.

• # in the palette lists the notes carrying a tag.
• The Tags view of the panel (Ctrl + T) lists every tag of the vault with its number of notes.
• Ctrl + click opens a tag of the text.

Embedded sections

A line holding only ![[Note#Heading]] shows that heading, and what is under it up to the next heading of the same level, in place and live.

• Look: the section is drawn in a frame, with a thin bar on its left in the accent color and the name of its note at the top right. It follows the theme and wraps to the page.
• Open the source: click the name, double click the frame, or press Alt + Enter on its line. The note opens at that section, and Alt + Left comes back. Ctrl + click on a [[Note#Heading]] link does the same.
• Suggestions: typing ![[Note# suggests the headings of the note, and ![[Note#^ its blocks. This works after [[ too.
• Read-only: to change the text, change it in its note.
• Loops: an embed that leads back to a note already in the chain says circular embed. Three levels are shown at most.
• Renames: renaming the note rewrites the embeds and links to it. Renaming the heading (the same headings but one, saved) rewrites #Heading in the other notes.
• Only alone on its line: inside a sentence, a list item or a code block, it is a plain link. ![[picture.png]] is still a picture.

The file stays plain Markdown: other apps show the line as a link.

Pictures

![](picture.png) or ![[picture.png]] shows the picture under its line: PNG, JPEG, GIF, WebP, SVG, BMP, TIFF or AVIF. Bref looks for it next to the note, then at the top of the vault, then by its file name anywhere in the vault.

• Ctrl + V with a picture in the clipboard saves it next to the note and inserts its ![](…) line.
• Typing ![[ suggests the diagrams and pictures of the vault.
• Enlarge: point at a picture (PNG, JPEG, GIF, WebP…), a formula, an SVG or a Mermaid diagram, and a magnifier button appears at its corner, or beside it when it is too small to hold it. It opens a viewer: Ctrl + wheel zooms around the pointer, and dragging moves the picture. See the viewer.
• A click on the picture itself still places the cursor. A missing or unreadable picture has no button.

Pictures are part of the vault. See Files on disk.

Dropping files

Drag files or folders from your file manager onto the window. The originals never move, and nothing is overwritten: a name already taken becomes name 2.

On a note. A line shows between two lines of the text, never inside a table, a code block or the YAML header. A label next to the pointer says where the items will land. They are copied next to the note, like a pasted picture, and each gets a line at that place:

One Ctrl + Z takes the lines back; the copies stay.

On the tree. The folder under the pointer is tinted (on a file, the folder that holds it), and the label names it. A drop between rows goes to the root of the vault. The new files are shown and selected, and a message says how many files were copied and how many items were left out.

On the welcome screen, a dropped folder becomes the vault.

What is copied: folders with everything in them, except hidden files and symbolic links, which are counted, not copied. A folder is never copied into itself. The copy runs in the background, so a large video does not freeze the window.

Files the vault lists: pictures, CSV and TSV tables, and attachments (pdf, video and audio, archives, Office and OpenDocument files, txt, json…). They show in the tree and the palette. [[name.pdf]] opens them in the application of your system, and renaming one rewrites the links to it. Other types are copied but not listed, so no link is written for them.

[[Folder]] opens the folder as a list page when no note has that name.

Not possible: pasting files copied in a file manager (the toolkit only passes text and pictures), and playing video or audio inside a note.

Comments

Ctrl + Shift + M annotates a word, a line or the line of an image, without changing its text. Without a selection, it comments the line.

In the file

The comment is kept in the note itself, as CriticMarkup:

{==the text==}{>>the comment<<}

The file stays plain Markdown. In Bref, the text is highlighted and the comment follows it, faded.

The comments panel

A panel to the right of the note lists its comments.

• Click a comment to go to it.
• Click its check mark (it shows under the pointer) to resolve it: the markup goes, the text stays.
• The comment of the passage under the caret is on a tint, and the panel scrolls to it.
• The speech bubble at the bottom right of the note, next to the copy button, closes and opens the panel. So does the panel's cross.
• A badge on the bubble counts the comments (9+ beyond nine).
• comments in the palette lists them, to jump to one from the keyboard.

On a comment, Ctrl + Shift + M resolves it. On a line of its own (see below), the line goes.

In a table

• A cell: the comment is on the text of the cell. A selection over several cells gets one comment per cell, never across a |. A | typed in the comment is written \|.
• A row, a column or the whole table, taken by its grip: the comment goes on a line of its own under the table, named by its content. A row is named by its first cell, a column by its header: {>>Column "Age": in years<<}.

Because the comment is named by content, a sort leaves it where it belongs:

• Renaming that first cell or header renames the comment.
• Deleting the row, the column or the table deletes it.
• Moving, inserting, duplicating, sorting or swapping rows and columns keeps it with what it is about. One Ctrl + Z brings both back.

How it shows:

• A commented cell is tinted, with a mark in its corner.
• A commented row, column or table is outlined, with a dot on its grip. It is stronger while the cursor is in the comment.
• The panel says where each comment is: Cell C2, Row Léa, Column Age, Table.

A comment on an empty cell is refused: there is nothing to highlight.

Daily notes, templates and capture

Today's note

Ctrl + J (or Today's note in the palette) opens the note of the day, 2026-10-09.md, wherever it is in the vault. If there is none yet, it creates it, with the date as its title.

• @today, @tomorrow, @yesterday, @monday or @2026-10-09 in the text links to the daily note of that day. See Links between notes.
• The blank page offers the daily notes of a week, a month and a year ago.
• With a template named Daily, Journal, Today, Note du jour or Aujourd'hui, Ctrl + J creates the note of the day from it.

The calendar

The Calendar view of the panel (Ctrl + Shift + J) shows one month.

• Today is a round pill. A dot under a day means it has its daily note.
• The last days of the neighbouring months are dimmed, and open their note too.
• Arrows change the day. Page Up and Page Down change the month.
• Enter or a click opens the note of the day, or creates it.
• The week starts on Monday in French, on Sunday in English.

Templates

Put notes in a folder named Templates (or Modèles) at the root of the vault: each one is a template.

• Case and accents of the folder name do not matter, and templates may sit in sub-folders.
• Templates are left out of the graph, the tags, the links and the notes to read again. A [[link]] never points at one.

New note from a template: new note from a template in the palette, or in the right-click menu of a folder of the tree.

1. Choose the template.
2. Type the name of the note.
3. The note is written in the folder selected in the tree (the root of the vault otherwise) and opened, with the cursor where the template says.

A name already taken is refused; nothing is overwritten.

Placeholders

Any other {{word}} stays as written.

Insert a template: insert a template in the palette puts one at the cursor, filled with the name of the open note. One Ctrl + Z takes it back.

Make a template of a note: make a template of this note in the palette saves the open note in the templates folder, created if there is none. Its first # title becomes {{title}}.

Quick capture

An idea rarely comes while Bref is open. bref --capture opens a window that is one line and nothing else, as fast as the app itself.

1. Type.
2. Press Enter. The line is added to the note of the day as a list item (- call Léa). Type - [ ] first to make it a task.

The note is created if the day has none yet, and found wherever you keep your daily notes in the vault. Esc, or a click beside the line, closes the window without writing anything.

Put it under a key: open the palette, type capture and choose Set up the quick capture shortcut.

• GNOME: done. Bref adds the shortcut Super + Shift + N to your keyboard settings and tells you so. If those keys are taken, it adds none and says so: set your own keys in Settings › Keyboard › Custom Shortcuts, under Bref: capture. Asking again never adds a second one.
• Elsewhere (KDE, macOS, Windows…): an app cannot take a system-wide shortcut by itself. Bref copies the command to the clipboard, ready to paste into a new shortcut of your system settings.

Without any setup, on Linux, right click the icon of Bref in the dock or the app grid: Quick capture is there.

If Bref is open on today's note, the line appears there a moment later. Without a vault chosen yet, the command opens Bref as usual.

The palette and the panel

The palette (Ctrl + P) finds and creates notes. The panel shows the vault in several views.

The rail and its views

A rail of icons stays on the left of the window. It opens a panel beside the note, in one of these views:

The rail also holds, at the top: the command palette, back and forward, the views, search and new note. At the bottom: the trash, the sync of a vault kept in git (it turns while it runs, and a red dot says the last one failed), backup, theme and help.

• Fold: press the key of the view on display, or click its icon. The panel folds back to the rail.
• Resize: drag the line between the panel and the note. Dragged all the way left, the panel folds to its rail. All the way right, it takes the whole window. Double-click the line for the default width.
• Whole window: Ctrl + M, or the arrows button at the top of the panel, puts the panel on the whole window, and back.

Views can also sit on the right of the window, or stack. See Docks.

Keys in the panel

The same keys work in every view. The calendar has its own arrows.

A previewed note only counts as opened once you click or type in it. It then moves to the top of the recent list, and its tab stays.

The tree

• Order: names are sorted as in a file manager: Note 2 before Note 10.
• Fold all: the double-chevron button at the top of the tree folds every folder. When they are all folded, it unfolds them all.
• New note: with the tree on display, Ctrl + N creates the note in the folder of the selected line. The button left of the folder button, at the top of the tree, creates it at the root of the vault instead.
• New folder: the folder button, Ctrl + Shift + N, or new folder in the palette. The field says where the folder goes.
• Several lines: Ctrl + click adds a line to the selection or takes it out. Shift + click selects everything from the last line chosen. Dragging, duplicating, copying links or paths, and moving to the trash then apply to all of them.
• Drag and drop: drag a note or a folder onto a folder to move it there, or below the last line to move it to the top of the vault. Nothing is ever overwritten: if the name is taken, the move is refused.
• Rename: F2. Renaming a note whose first line is its name rewrites that line too. The links to it follow, see Names and renaming.

The menu. Right click a line, or press Shift + F10 (the Menu key) on the selected line:

• open, or open to the side;
• new note here, new note from a template, new diagram here, new folder;
• copy the [[link]], the path, or the path relative to the vault;
• show in the file manager (Finder, Explorer);
• duplicate (Ctrl + D), rename, move to a folder chosen in a list (what dragging does);
• set an icon;
• show as a list (on a folder, see List pages);
• move to the trash.

A right click below the last line acts on the vault itself. For the open note, the same entries are in the command palette: Open in the other pane, Copy the [[link]] of the note, Copy the path of the note, Copy the relative path of the note, Move the note to a folder…, Icon of the note…, Show the note's folder as a list.

Icons

Right click a note, a file or a folder in the tree, then Icon…. Pick one of forty in the grid (arrows and Enter work), or the cross to remove it.

• Without one, every row shows a small icon of its kind (folder, note, table, diagram, picture, other file), so the names line up.
• A file that is not a note shows its extension next to its name, lighter (contacts.csv). A long name is cut before its extension.
• The icon you give replaces the default one, before the name. It follows a rename or a move.
• Icons are kept in .bref-icons at the root of the vault, so they travel with it.

The graph

One dot per note, bigger with its links.

• The open note is in the accent colour. Its neighbours and their lines are darker.
• Notes without links sit on a ring around the rest. A rounded square is an attachment, such as a picture.
• Names show for the open note, its neighbours and the most linked notes. Pointing at any dot shows its name, and lights up the notes it is linked to.
• Drag the background to move around. Scroll to zoom. The target button glides back to the whole graph.
• Drag a note to move it: the notes linked to it follow, the closest ones the most.
• With the graph on the whole window, a click only selects. Enter or a double click brings the note back.

Links to notes that do not exist yet are left out.

The trash

The trash is the hidden folder .trash at the top of the vault. Deleting moves a note or a folder there; nothing is ever destroyed.

• Undo: moving something to the trash shows a message with Undo. It puts the item back exactly where it was. Its folder is made again if it is gone, and nothing is overwritten.
• Restore later: click the bin at the bottom of the rail, or type trash in the palette. It lists the trash, and Enter returns the chosen item to the top of the vault. The trash does not remember where an item came from. A name already taken gets another one.
• Empty the trash with your file manager.

Tabs, panes and docks

Tabs

A pane holds as many files as you like, as in a code editor.

• Opening: a click on a file in the tree, a note chosen in the palette, a link followed, a new note: each opens in a tab of its own, right of the one shown. If the file is already open, its tab comes to the front instead. A note is open only once.
• Previewing: browsing the tree with the arrows previews notes in a single tab, in italics. The next note browsed replaces it. Opening it for good keeps it.
• The tab bar appears at the top of the pane as soon as it holds two tabs, each a rounded pill. A click shows a tab. Its cross, or the middle button, closes it.

A tab can be dragged along the bar, into another pane, or to an edge to split one. See Drag a tab.

Tabs come back at the next start. A tab out of sight keeps its text, cursor and undo, but lets go of what it drew, so a hundred tabs cost little memory.

Back and forward

Alt + Left and Alt + Right (Cmd + [ and Cmd + ] on macOS) walk through what you opened: notes, pictures, diagrams, tables and list pages alike. So do the back and forward buttons of the mouse, the two arrows at the top of the rail, and Back and Forward in the palette.

• You land where you were: same line, same scroll.
• Back and forward go from tab to tab, and bring a closed file back in a tab.
• It works like a browser: opening something after going back drops what was ahead.
• A note only previewed (arrows in the tree, a click in the graph) does not count. A renamed file is followed, a deleted one is skipped.
• The history is not kept between two launches. The recent notes are.

Panes

Ctrl + \ splits the pane to the right, Ctrl + Alt + \ below, as many times as the window has room for. Write a note while reading two others, or keep a table under a note.

• A new pane opens on the palette, to choose what goes there. Each pane shows anything Bref can show.
• A pane is split only if both halves keep room to write: 300 px wide, 200 px high. Otherwise a message says so. The very first split folds the panel onto its rail when that is enough.
• The pane with the focus is marked by a line at its top, and a thin accent ring. The palette, the tree and the shortcuts act on it.
• A note already shown in one pane is not opened twice: the focus moves to it.
• The layout comes back at the next launch.

Open to the side in the menu of the tree does the same. The palette also has Move the tab to the pane on the left (right, above, below; a pane is split off when there is none on that side) and Even out the panes.

Sizes: every border between panes can be dragged, down to the smallest size of a pane. A double click shares that split evenly. A window too small for every pane shows the one with the focus alone, and all of them again once it is big enough.

Drag a tab

Drag a tab to arrange the window:

• dropped on a tab bar, it moves there (a line shows where);
• dropped on the middle of a pane, it joins it;
• dropped near one of its edges, the pane splits on that side and the tab takes the new half.

The part that would receive it is tinted while you drag. Esc lets go without moving anything.

A file dragged from the tree does the same. Dropped on the right half of a window that has a single pane, it opens a second pane. A folder opens as its list page.

Docks

Each view of the panel can live on either side of the notes. So the tree and the backlinks, or the graph and the calendar, can stay in sight together.

• Move a view: the arrow in its header, or Move the panel's view to the other dock in the palette, sends it to the dock on the right, and back.
• Show or hide: the rail shows or hides a view where it lives.
• Stack: Shift + click on its icon stacks a view under the views already shown in its dock. Each has a header that folds it (the chevron) or hides it (the cross).
• Drag a view by its title to put it elsewhere. A line shows where it lands in a dock. While it is dragged, a strip on the right edge of the window opens the right dock. Esc lets go without moving anything.
• As a tab: the graph and the calendar also open as a tab of a pane, to get room: the button next to the arrow, or Open the graph or the calendar as a tab. Closing the tab gives the view back to its dock.

The right dock hides when the window leaves the notes too little room. Where everything is comes back at the next launch.

Search and replace

Find in the note

Ctrl + F opens a search bar at the top right of the note. Ctrl + R opens it with the replace field.

• Matches are highlighted as you type. The current one is stronger, with its rank (3 / 12).
• The search runs on the text of the file, so Markdown markers (**, [[) can be searched too. It works inside tables and code blocks.
• A selection held on one line becomes the search. The first key typed replaces it.
• A selection over several lines keeps the search to those lines, as long as the in the selected lines button is on.
• The search and the replacement are kept when the bar closes, and come back selected.
• Both fields edit like any other: cursor, selection, word moves, paste, and the input method of your language (Japanese, dead keys). A long search scrolls in its field.

• With the bar open, Ctrl + R and Ctrl + F switch modes, and the keys go to the matching field. The search and its options are kept.
• Regular expressions: ^ and $ are the ends of each line, and the replacement can reuse groups with $1. An expression that does not compile says « Invalid expression » in the bar.
• Edit while searching: click in the note to edit it while the bar stays open. The matches follow the text. F3, Alt + C and Alt + W still work, and Esc closes the bar.
• With no bar open, F3 opens it.

Search the vault

Ctrl + Shift + F (or the rail's icon with lines and a magnifier) shows the search of the whole vault in the panel. If the note's search bar is open, it starts from its search.

• It takes the same options as the bar: Alt + C, Alt + W, Alt + R, or the Aa, “ab” and .* buttons.
• Under the count of matches and notes, each note lists its matches, one line each, with the line number and the match marked. A note's header folds its matches.
• ↑ ↓ walk the list. Enter or a click opens the note on that match, with its search bar on the same search. Esc gives the keys back to the note.
• The search runs in the background as you type. It follows the notes as they change, from outside the app too.

Replace in the vault

From the vault search, Ctrl + R (or the chevron) shows the Replace with field. From the note's search bar, Ctrl + Shift + Enter does the same job.

• The field's button, Ctrl + Enter, or Enter in the field replaces in every note.
• Bref first shows how many matches in how many notes, and writes nothing until you accept.
• The button on a note's header replaces in that note only.
• The cross at the end of a match sets it aside: it is neither listed nor replaced.
• A note that cannot be written is reported; the others are replaced.

Undo the replacement in the vault, in the palette, puts every note back, except those changed since.

Kanban boards and list pages

Kanban boards

Type kanban in the palette and choose New kanban board. A note opens as a board with three columns.

With the mouse

• + Add a card opens a card to type in. Enter adds it and opens the next one; Esc stops.
• A double click rewrites a card or a column title in place. A card emptied this way is removed.
• The + on the right adds a column.
• Pick a card up and it follows the pointer, while a dashed slot opens where it would land: between two cards, or at the bottom of a column. Held near the edge of the window, it scrolls the board.
• Click a card's box to tick it.

With the keys

A card being written is a real line of text: arrows, word by word with Ctrl, selection with Shift, Ctrl + Backspace, copy and paste, a click to place the cursor. The same goes for the palette and a cell of a CSV table.

Columns narrow to fit the window.

In the file, the note stays plain Markdown, in a common Markdown kanban layout: one ## heading per column, and one task per card. The key kanban: true in its front matter is what makes it open as a board. Typing that key into a note leaves you in the text.

The button at the bottom right, left of the copy button, shows that text, and comes back to the board.

List pages

Right click a folder in the tree, or a tag in the tags panel, then Show as a list. Its notes become the rows of a table, and the keys of their front matter (author:, rating:…) its columns.

• Filter: type to filter the rows. author:austen looks in one column only. Esc clears.
• Sort: click a column title to sort by it, again to reverse.
• Open: click the name of a note.
• Edit: click any other cell to rewrite it. Enter confirms, Esc gives up. Only that key changes in the front matter of the note: it is added if it was missing, removed if you empty it. Nothing else in the file changes.

A folder dragged from the tree onto a pane, or a [[Folder]] link when no note has that name, also opens as a list page.

Diagrams

Mermaid turns text into a diagram. When you would rather place things yourself, Ctrl + Shift + D opens a canvas. New diagram is also in the palette and in the menu of the tree.

Each diagram is a plain SVG file in your vault, shown in your notes. For class, use case, state, sequence, activity, package, component and deployment diagrams, see UML diagrams.

Tools

Pick a tool, from its key or from the dock at the bottom of the canvas (select, shapes, arrows and relationships, text, library), then drag. A click drops the shape at its usual size.

• The shapes and arrows buttons open a menu that names each one with its key. A shape can also be dragged from a menu or from the library and dropped on the canvas.
• Undo, redo and export sit in a small cluster at the top left.
• With a menu open (shapes, relationships, the right click, the library), the arrow keys go along its rows and Enter picks the one that is lit.

The bar over the selection

Select something and a bar floats over it, with what can be changed in it. It goes above or below the selection, whichever covers fewer shapes. It wraps in a narrow window and hides while you drag.

• 1 to 6 give the selection one of the six colors. The bar also offers a tinted background, a dashed outline, duplicate and delete.
• The buttons for the heads and the route of an arrow show their present state in their icon.

Shapes

• Handles: point at a shape and it lights up with four handles, one in the middle of each side. Drag one to another shape and an arrow is drawn, with the look of the last arrow or relationship picked.
• Right click: a menu of what is under the pointer: write in it, turn an arrow around, its route, duplicate, delete, fit a container. On the empty canvas: a text there, select all, fit.
• Selection: click, Shift + click or Ctrl + click to add a shape or take it out, or drag on the empty canvas.
• Move and resize: drag to move, on a grid. Drag a corner to resize. The arrow keys move by one step.
• Keys: Delete or Backspace removes, Ctrl + D duplicates, Ctrl + A selects everything, Ctrl + Z undoes and Ctrl + Shift + Z redoes.

Arrows

• Hooked: an arrow started or ended on a shape holds on to it. Move the shape, and the arrow follows.
• Where it leaves: an end dropped in the middle of a shape leaves by the side that faces the other end. Dropped near an edge, it stays at that spot (the dots shown while you drag).
• Re-hook: select an arrow and drag one of its ends to hook it elsewhere.
• Heads and dashes: two buttons of the bar change the head at each end (none, arrow, triangle, diamonds, cross, ball, socket), and another makes the arrow dashed.

Routes. An arrow is elbowed (right angles, leaving the shape by its side), straight or curved. With an arrow selected, a button of its bar goes from one route to the next, and new arrows take the last one chosen.

• An elbowed arrow goes around the shapes in its way, by the path with the fewest bends. It keeps that path as long as nothing new stands in it.
• A frame or a swimlane is crossed; what is in it is not.
• An end hooked on a side keeps that side.
• Arrows between the same two shapes run side by side instead of stacked.

Text

• Enter or a double click writes in the selected shape, or on the arrow. While writing, Enter starts a new line and Ctrl + V pastes text. Esc when done.
• A double click on the empty canvas starts a text there.
• A shape grows to hold what you write.
• Texts are styled with the marks of notes: **bold**, *italic*, <u>underlined</u>, ~~struck~~, `code`. They show as typed while you write, and styled once you leave. The SVG file and the PNG export carry the styles.
• A diagram made before styles existed keeps its stars as they are until you ask, with the italic button at the top left.

Ends of an arrow. Besides the text in its middle, an arrow carries one text at each end: a role, a multiplicity (1, 0..*, +items).

• Write in them with two buttons of the bar over the arrow, with Tab (start, middle, end; one step of undo for the three), or with a double click near an end.
• They are placed beyond the head: above a lying stroke, beside a standing one. So they cover neither the shape nor the head.
• Drag one along the stroke to move it away from the end.

Containers

A package (G), a frame (F) or a swimlane (W) holds the shapes dropped on it, to any depth.

• A shape drawn or dragged over a container belongs to it. Dragged out, it leaves it. One step of undo puts back both its place and its holder.
• Moving the container moves what it holds. Copying it copies them, with the arrows between them. Removing it removes them.
• Resizing it leaves them where they are. Once it holds something, a button of its bar fits it around what it holds.
• An arrow can join a held shape to anything outside.
• A package has its name in its tab and the lines after it under the tab. A frame has its title at the top left. A swimlane has its name in its header.

Library

S, or the last button of the dock, opens a drawer of shapes for each family of diagrams, each with its text and its size. For example: a class, an abstract class, an interface, an enumeration, an object, a package, a note, an n-ary association; a use case, an actor, a system boundary.

It also holds starting points: a new diagram that already holds a few shapes. There is one for class, use case, package, state machine, sequence, activity, component and deployment diagrams.

• Typing searches it, by name or family, accents and case ignored. Enter picks the first answer.
• A click on a row makes it the tool for the next shape: a click on the canvas draws it at its size, a drag at the size dragged.
• A row dragged onto the canvas drops it there, inside the container it is over.
• Esc closes the drawer.

The view

• The wheel moves the canvas, and so does dragging with the middle button.
• + and - zoom, as do Ctrl + +, Ctrl + -, Ctrl + wheel and the buttons at the bottom right. Ctrl + 0 fits too.
• 0, or a click on the percentage, fits the whole diagram.
• The canvas has a faint grid of dots: one every other step of the grid that shapes snap to.
• A dashed line shows when what you move lines up with another shape, by side or by middle.
• With a shape tool picked, the shape it would drop follows the pointer as a dashed outline.

In a note

![](Diagram.svg) or ![[Diagram.svg]] shows the diagram in the colors of your theme, and follows its changes. Typing ![[ suggests the diagrams and pictures of the vault.

The file

A diagram is a plain SVG, saved at each change. It opens in a browser and displays on GitHub. It also carries its own source, which is what Bref reads to keep editing it.

A diagram saved by a newer Bref than yours opens in the viewer, read-only, with a notice: your version would lose what it does not know if it saved the file.

Export: the button at the top left saves a PNG next to the diagram, dark on white.

From Mermaid to the canvas

When a classDiagram, sequenceDiagram or stateDiagram is enlarged (the magnifier of its block), a pencil button at the top left makes a canvas diagram of it. It is written next to the note, which is not touched, and opened to carry on by hand.

• Classes keep their members (+String name becomes + name: String), stereotypes, and relations with their multiplicities and labels.
• Sequence diagrams keep their lifelines, their messages in order (->>, -->>, -x, -)), autonumber, and their alt, opt, loop, par, critical and break blocks with their else branches.
• State diagrams keep their states and descriptions, [*], choices, forks, joins and composite states.

The shapes are placed by layers, parents above their children. What Bref cannot draw (notes, styles, rect colours, regions) is left out, and a message says how many lines.

Import

import in the palette takes an Excalidraw file (.excalidraw) or a draw.io file (.drawio, saved without compression: untick File › Properties › Compressed).

Shapes, texts, arrows and what they hold on to are kept. Freehand strokes and pictures are not, and arrows are routed again by Bref. The message counts what could not be drawn (« 3 items not imported »).

SVG files from elsewhere

An SVG from draw.io, Mermaid.js, Inkscape or a browser opens in a viewer, fitted to its width. Pictures, formulas and Mermaid diagrams enlarged from a note open in the same viewer.

• Drag or use the wheel to move. + and - (or Ctrl + wheel) zoom from 5 % to 800 %. 0 fits. Esc goes back to the note.
• It is drawn in tiles at the resolution of the zoom, so a diagram several thousand pixels tall stays sharp.
• Text written in HTML (draw.io labels, Mermaid.js) is turned into SVG text, with its bold, colors and line breaks. light-dark() colors follow the theme.

In a note, ![](file.svg) shows it the same way.

UML diagrams

The canvas reads and draws UML notation. The shapes of each family are in the library (S), with a starting point for each kind of diagram.

What the notation does not read (a sentence, a comment) is drawn as typed, never refused.

Classes

In a rectangle, a line made of --- starts a new compartment:

1. the name of the class, with a stereotype line first if any: «interface», «enumeration», «abstract» or <<interface>>;
2. the attributes;
3. the operations;
4. any other compartment, which can open with a title (Responsibilities:).

A member is written as the specification does:

+ name
- /derived: Type[0..*] = default {readOnly}
# area(width: int): f32

• + - # ~ are the visibilities.
• static is drawn underlined and abstract in italics. The keyword itself is not drawn.
• An abstract class has its name in italics: write «abstract», or {abstract} after the name.
• The literals of an enumeration stay as typed.

Objects

An object (an instance) is written name : Type, or : Type with no name, and is underlined. Its slots are the attributes below it: total = 12.

An object diagram is made of such boxes, linked by arrows that carry a name in the middle and a role at each end.

Packages

A package is a container (G). Its name is in the tab. The lines after it, such as a qualified name (pkg::billing), are under the tab.

Packages nest to any depth. «import», «access» and «merge» between them are in the relationships menu.

Use cases

• A use case is an ellipse with its name (O). A --- line in it starts the compartment of its extension points, under the name, behind a separator that stays inside the ellipse.
• The system boundary is a frame (F) that holds the use cases. The actors (P) stay outside.
• An association is a line (L).
• «include» (K then L), «extend» (K then E, with its condition on the next line), and the generalization of actors or of use cases (K then H) are in the relationships menu.

State machines

• A state is a rounded box (U). Its name is on top. Its internal activities (entry / action, do / activity, exit / action) are in a compartment under a --- line.
• A composite state is a rounded container with its name in a header. It holds its substates, and its regions are cut by a dashed divider.
• The library holds the pseudostates: the initial state (a filled dot), the final state, the choice (a small diamond), the junction, the fork and join (a bar), the shallow and deep history (H, H*), the terminate (a cross), and the entry and exit points.
• A transition is an arrow whose text reads trigger [guard] / effect. The guard, between brackets, is in italics.
• A transition that stays in its state is a loop: with a shape selected, a button of the bar adds it and writes its label.

Sequence diagrams

Lifelines come from the library. They stand side by side, their heads on one line.

Messages. An arrow drawn from one lifeline to another is a message. A lifeline is joined whole, whatever the height.

• A message's height is not stored: it follows from its order. The first is under the heads, the next ones 44 below each other. Inserting one pushes the others down.
• Dragging a message up or down puts it where its height says, in one step of undo. The lifelines keep their places and grow to hold the last message.
• A button of the bar numbers the messages (3: find()). The number is shown, never typed.

Kinds of messages

Calls inside calls nest their bars.

Combined fragments (alt, opt, loop, par, break, critical, neg, ref) are in the library.

• With messages selected, picking one wraps them in it: a frame with the operator in its tab and the guard beside it, as wide as the lifelines they touch and as tall as they need. Otherwise it is a shape to draw.
• The first line of its text is the operator. Each line after it is an operand (alt, [ok], [else]), with a dashed line between operands.
• A message is picked through the fragment as usual.
• A message dragged into a fragment is held by it; dragged out, it leaves. Let it go low in the fragment to reach the next operand.
• Fragments nest. Removing a fragment keeps its messages.

Activity diagrams

The library has the nodes of an activity:

• an action (a rounded box), and a call behaviour (the same, with a rake in its corner);
• an object node;
• the initial node, the activity final, and the flow final (a cross in a circle);
• the decision and the merge (a small diamond);
• the fork and the join (a bar that stretches to any length, horizontal or vertical);
• the activity frame (act Name) and the «interruptible» region (a dashed frame that holds shapes).

Swimlanes are a column (a name in a header on top) or a row (a name in a header on the left). Both hold the shapes dropped on them, and move, copy and remove them together.

Pins are small squares. Dropped within a few pixels of the border of a shape, a pin sits on that border and is held by the shape: it follows it, stays on its border when it is resized, and goes with it when it is removed. Its name is written outside. Dragged far from every border, it is let go.

Flows: control and object flows are arrows (A, N). Their [guard] is their text.

A starting point in the library shows an order in two swimlanes, with a pin, a decision and two ends.

Components and deployment

• A component is a box with its small icon in a corner.
• A port is the pin of activity diagrams: it sits on the border of the component, follows it and goes with it.
• The node, the device and the execution environment are 3D boxes whose stereotype is their first line. They hold the shapes dropped on them (nodes inside nodes) and move, copy and remove them together.
• The artifact is «artifact».
• The provided interface is the ball (K then B), the required one the socket (K then Q). Two arrows that end at the same point meet there.
• The communication path is a line (A) with its stereotype as text («HTTPS»).
• «deploy» (K then J) puts an artifact on a node. «manifest» (K then V) makes it the form of a component.

Two starting points: a shop and its payment service, and a laptop and a server.

Relationships

K, or the arrows button of the dock, opens a menu of the UML relationships by family. Each has its name and its letter. With an arrow selected, the first button of its bar names its relationship and opens the same menu.

• The menu also offers the n-ary association (Y, a small diamond).
• The association class is a dotted line from a class that holds on to the middle of an association, and follows it.
• Picked with nothing selected, a relationship is the tool for the next arrow. With arrows selected, it changes them.
• A relationship is not marked in the file. An arrow is recognised from its two heads, its dashes and its stereotype, so one made by hand with the same look is the same relationship.

CSV and TSV files

A .csv or .tsv file of the vault shows in the tree and opens in a grid, in place of the note. The file is read and written directly: there is no import, and the rows you did not touch are written back byte for byte.

Detection

• Encoding: from the byte order mark; else UTF-8 if the file is valid UTF-8; else Windows-1252. Bref reads and writes UTF-8, UTF-16, ISO-8859-1 and Windows-1252.
• Delimiter: , ; tab | : or space. Bref picks the one that splits most lines into the same number of fields, quotes respected.
• Header row: the first row is a header unless it holds numbers.

To change them, click one in the bar above the grid, or search table in the palette. The file is read again that way, and the choice is kept for that file. Detect automatically forgets it.

Move

Click a cell, or use the wheel (Shift + wheel sideways) and the scroll bars.

Select

• Shift + arrows, or drag with the mouse.
• Click a row number or a column header for the whole row or column. The corner, or Ctrl + A, selects everything.
• From the keyboard, Shift + Space takes the whole rows of the selection, and Ctrl + Space its whole columns, as in a spreadsheet.
• Ctrl + click (on a cell, a row number or a header) keeps what is selected and starts another selection. Copy and cut take them all, one block under the other. Delete empties them all, and Ctrl + Delete removes all their rows (all their columns, when they are whole columns). Typing and pasting go to the last one.

Write

• Typing replaces the cell. Enter or F2 opens it as it is.
• Enter validates and goes down. Tab validates and goes right. Esc cancels.
• Delete empties the selection.
• A cell being written edits like any line of text: word moves, selection, paste.

Rows and columns

Rows: Ctrl + Enter inserts one below, Ctrl + Shift + Enter above. Ctrl + Delete (or Ctrl + Shift + Backspace, as in a note) removes the selected ones.

With whole columns selected (Ctrl + Space), the same keys act on columns: as many empty columns to the right or to the left, or the selected columns removed.

More gestures are the same as for the tables of a note. Find them in the palette (column, sort, row), or give them keys in the help panel:

• insert a column left or right of the selection;
• duplicate, move or delete the selected columns;
• move or duplicate the selected rows (Alt + Up, Alt + Down move them; the header stays on top);
• sort the rows under the header on the column of the cursor, A to Z or Z to A: numbers by value, empty cells last.

The bar above the grid names whole columns or rows when they are selected (a click on their header, or Ctrl + Space), next to the name of the file. It offers their gestures as icons: for columns, insert left or right, move, sort, delete; for rows, insert above or below, move, duplicate, delete. Pointing at an icon names it, with its keys.

Ctrl + Z and Ctrl + Shift + Z undo and redo. One undo takes each gesture back, a paste included, and the file gets its exact bytes again.

The last column cannot be deleted. Columns and sorting read the whole file, which is fine up to a few hundred thousand rows. Moving columns on a row shorter than they are leaves it a few empty cells longer after the way back.

Copy, paste, export

• Ctrl + C copies the selection as tab-separated text, which spreadsheets and the tables of your notes paste as they are. Ctrl + X cuts it.
• Ctrl + V pastes cells from a spreadsheet, a Markdown table or CSV text from the selected cell, adding the rows that are missing. One value fills the whole selection.
• In a note, copying cells of a Markdown table gives a Markdown table. A spreadsheet pastes its lines in one column, so use the grid's copy for a spreadsheet.
• copy table as and export table in the palette (or the buttons of the bar) offer TSV, CSV (with the delimiter of the file), Markdown and JSON. They take the selection, or the whole table when only one cell is selected. An export is written next to the table, under a name that is still free.

Saving

The file is saved about half a second after the last change, in the background, atomically, in its own encoding and with its own line endings.

• A character the encoding cannot hold (a € in ISO-8859-1) is reported, and the file is left alone.
• If another program rewrites the file and nothing waits to be saved, the grid reads it again.

Limits

• Files up to 1 GiB, read whole in memory (about the size of the file). A million rows are parsed in under a tenth of a second on the author's machine.
• No formulas: they are for the tables of a note.

CSV and TSV files can be renamed (they keep their extension), moved, duplicated or trashed like a note. They are not in the graph, and a note does not link to them.

Files on disk

A vault is an ordinary folder of plain files. Bref adds nothing to your notes that another Markdown app could not read.

Notes

• One .md file per note. Notes in subfolders are found too. Hidden folders (.git…) are ignored.
• New notes are created at the top of the vault, or in the selected folder when the tree is on display.
• A note is saved shortly after you stop typing, and when you switch note or quit. Saving is atomic: a crash never leaves a half-written file.
• A note opens with the cursor at the start of its body, under its title and its front matter. What you type first goes into the text; it does not rename the note.

Names and renaming

• A new note is named after its first line: # Groceries becomes Groceries.md. The file is renamed when you change that line.
• A new note left empty leaves no file behind.
• A note whose file name did not already match its first line (typical of an existing vault) keeps its name. It takes the name of its first line only once you add or change a # title there.
• Renaming a note from the tree also rewrites its first line, when that line is its name.
• When a note is renamed, from the tree or by changing its first line, the [[links]] to its old name are rewritten in every note. They keep their |alias and #heading. After a change of title, this happens when you leave the note, not at each keystroke.
• If another note still carries the old name, the links are left alone: they may be meant for it.
• Nothing is ever overwritten. A name already taken is refused.

Front matter

A YAML front matter is a block that starts on the first line with --- and ends with --- or ....

• It is shown dimmed, and never interpreted or rewritten. Renaming a note or rewriting its links leaves the block byte for byte as it was.
• The title of the note is the first line after it.
• Two keys are read:
  • tags (tags: [a, b], tags: a, b, or a dashed list) count like #tags in the text;
  • each name in aliases is another name for the note, suggested after [[ and followed by links, backlinks and the graph.
• Other keys and nested YAML are ignored, except by list pages and kanban boards (kanban: true).

/meta inserts a front matter. See Slash commands.

Pictures, CSV and other files

• Pictures are part of the vault. The tree lists them under the notes of their folder, and the graph shows them as squares, linked to the notes that display them. Selecting one shows it in place of the note. It can be renamed (the notes that display it follow), moved or trashed like a note.
• CSV and TSV files are listed with the notes of their folder and open in a grid.
• Pictures shown and listed: png, jpg, jpeg, gif, webp, svg, bmp, tif, tiff, avif.
• Attachments are listed, found in the palette, linked with [[name.pdf]], and open in the application of your system: pdf; video and audio (mp4, m4v, mov, mkv, webm, avi, mp3, m4a, wav, ogg, opus, flac); archives (zip, 7z, tar, gz, rar); documents (doc, docx, xls, xlsx, ppt, pptx, odt, ods, odp, epub, rtf); text (txt, json, xml, html, log). See Dropping files.
• Other files stay in the folder, but Bref does not list them.

Changes from other programs

What other programs change in the vault (a sync tool, a script, another editor) is picked up in about half a second, without restarting. Bref asks the system to report changes (inotify, FSEvents, ReadDirectoryChangesW).

• Notes and folders added, renamed or removed elsewhere show up in the tree, the palette and the graph.
• The note on display is read again when its file changes. If you were typing in that note at that moment, your version is kept and written back.
• Bref also looks at the vault every 30 seconds, in case an event got lost. When the system cannot watch the folder, it looks every two seconds. See Troubleshooting.

Backup

Click the arrow into a tray at the bottom of the rail, or type back up in the palette, and choose a folder. Bref writes there one archive of the whole vault, trash included, named after the vault and the date: Notes 2026-10-09.tar.gz. It is numbered if that name is taken.

A folder inside the vault is refused.

Terminal

Type terminal in the palette to open the terminal of your system in the folder of the vault:

• Windows: Windows Terminal, or the console;
• macOS: Terminal;
• Linux: the one named in $TERMINAL, else the one of the desktop.

Bref has no terminal of its own.

Messages

• Status: the outcome of an operation (a backup saved, a note restored, a failure) shows at the bottom right, with a spinner while it runs. A message goes away after four seconds (a long one stays a little longer), or as soon as you click it.
• Failures stay twelve seconds, until you click them or press Esc. They name the file and say why in words (permission denied, not found, the disk is full), never the raw system error.
• Unreadable things say so: a Mermaid diagram or a $$ formula that cannot be drawn, and a picture that cannot be read (a corrupt file, one of 0 bytes), show « Unreadable figure », « Unreadable formula » or « Unreadable image » under their source. A picture opened alone says « Loading… » while a big one is read.
• A missing or unreadable vault: a vault that is no longer where the config left it is reported on the welcome page. A vault that cannot be read (no permission) says so in the panel, with the reason and the folder, instead of looking empty, and offers another vault. A folder inside it that cannot be read is marked « unreadable: » with the reason; the rest of the vault opens.
• Empty lists say so: an empty tree, tag list or recent list, a note nothing links to, a palette search with no result (or with one letter, too little for the text search), a list page with no row, and a board with no column each show one soft line instead of a blank page.

Configuration files

Bref keeps its own state in a configuration folder, outside the vault:

In the vault itself, Bref only writes .bref-icons (the icons you gave), the .trash folder, and, for a vault it connects to git, a .gitignore that leaves the trash out.

Syncing a vault

A vault is a folder of plain files. There are two ways to have the same notes on every computer, safely copied somewhere else. Pick one, never both: a git repository inside a cloud folder ends up corrupted.

With a cloud folder

Put the vault in a folder synced by iCloud, Dropbox, Google Drive or Syncthing. Bref follows what changes there. Nothing more is needed.

With git

Ctrl + Shift + S, or Sync the vault in the palette, does everything in the background while you keep typing:

1. The open notes are saved, and everything that changed is committed, with the message Bref: sync.
2. What the server has is fetched and merged.
3. The result is sent. If another computer pushed in the meantime, Bref fetches and merges again, three times at most, then asks you to try again.

A message says what was sent and received, or why it failed. The sync button of the rail turns while it runs; a red dot says the last sync failed.

Conflicts

• Two computers that changed different notes, or different parts of the same note, are merged without a question.
• When the same lines changed on both sides, both versions are kept, as Dropbox and Syncthing do. The note keeps the version of this computer. The other one is written next to it as Note (conflict 2026-10-09 laptop).md, and the sync completes.
• You never get <<<<<<< markers in a note.
• A note deleted on one side and edited on the other stays, edited.
• A note renamed on one side and edited on the other is a conflict two copies cannot settle: the sync stops, changes nothing, and asks you to merge with git yourself.
• Line endings are never converted.

A vault not in git yet

The same command asks for the address of an empty repository. Create one on GitHub, GitLab or Codeberg, or on any server you reach by SSH with git init --bare notes.git. Bref then connects the vault and sends its notes.

The trash (.trash) is left out of the repository, through a .gitignore. A repository that already has a history is not overwritten.

On another computer

Clone a vault from a git address…, in the palette or on the welcome screen, asks for the address and a folder, then opens the clone as the vault. The vault's folder is named after the last part of the address, without .git, and must not exist yet.

Requirements

• git must be installed, and able to reach the repository without asking anything: an SSH key, or a credential helper for HTTPS.
• Bref never shows a password prompt: ssh runs in batch mode, unless you set GIT_SSH_COMMAND yourself. A refused sign-in is reported.
• Without git, the sync says so.
• Without a name and an email in the git configuration, the commits are signed Bref.

What it refuses

Bref refuses to sync, says why, and touches nothing, when it finds:

• a merge or a rebase in progress;
• a detached HEAD;
• a branch that follows no branch of the server;
• a locked index;
• a vault that is only a folder of a larger repository.

Limits

• Syncing happens when you ask, not on a timer, nor when quitting.
• git syncs computers. There is no Bref on a phone, where the repository stays readable with another app.

Settings and appearance

Every choice is a command of the palette: type its name, and see the result at once.

Theme

The half-filled circle at the bottom of the rail, or theme in the palette.

• 13 themes: Bref Dark and Bref Light, Dracula, One Dark, Gruvbox (dark and light), Nord, Catppuccin (Mocha and Latte), Tokyo Night, Rosé Pine, Solarized (dark and light).
• Each theme is applied as you move through the list, so you see it before choosing. Enter keeps it, Esc goes back to the one you had.
• Default follows the light or dark setting of your system, with Bref Light or Bref Dark.
• In every theme, links, secondary text and the titles of colored panels are adjusted to a contrast of at least 4.5:1 (WCAG AA).

The look. The window is a warm ground, a little darker than the page in every theme. The note, the panel and the right dock lie on it as rounded sheets, eight pixels apart. Page titles are in a serif, while note titles follow your font.

• The active pane of a split has a thin accent ring.
• The open row of a list, a tag in the text, a commented passage and the current tab take a quiet tint of the accent.
• Tables and code blocks have a rounded band.
• Menus, the palette, help and notices float above, with a shadow.

Fonts

Bref carries IBM Plex Sans (text), IBM Plex Mono (code) and IBM Plex Serif (page titles), under the SIL Open Font License (assets/fonts/). So it looks the same everywhere, with nothing to install.

• Type font in the palette to choose another font, for the app or for the code, among those installed on your system. Type in the list to filter it.
• Ideograms and emoji, which Plex does not draw, come from a font of your system.
• A variable font cannot be emboldened. See Troubleshooting.

Text size

Ctrl + + and Ctrl + - change the size, Ctrl + 0 restores the default.

Headings, code and the width of the text column scale with it. The interface around the note (panel, rail, menus, palette, help) follows too, from 85 % to 150 %, so it stays usable at either end.

Page width

page width in the palette sets how wide the text column is: narrow, normal, wide, or the full window.

wide tables in the palette chooses what a table wider than the text does:

• center (the default): it spills out on both sides of the column, centered on the window;
• column: it stays in the column, and scrolls sideways.

A small table keeps its own size, and nothing goes past the window.

Formatting bar and animations

• formatting bar in the palette shows or hides the formatting bar under the note.
• animations in the palette turns the short fades off. When on, the panel, the formatting bar and a folder of the tree fade in over about 0.13 s as they open. Nothing moves on typing, scrolling or the caret, and no fade delays a result. Hovers and closing are instant.

Language

French if the system language is French, English otherwise. Bref asks the system (Windows, macOS), or reads LC_ALL, LC_MESSAGES and LANG (Linux, or any system when started from a terminal).

The settings file

These choices are kept in a file named settings, in the configuration folder. It holds one key=value per line:

Changing a shortcut

The help panel (F1) lists every shortcut, and lets you give any of them other keys.

• Change: click the keys of a row, or move to it with Down and press Enter. The row waits, and the next combination you press becomes its shortcut, at once. Esc cancels. Backspace leaves the action with no shortcut.
• Conflicts: a combination already used where the action applies is not taken. The row says by which action. Enter (Replace) gives it to the new one, and the other is left without a shortcut. The same keys in two views that never meet (a table and a diagram) are not a conflict.
• Refused keys: a key alone that types text, and the keys the text and the views need (Enter, Tab, the arrows…), are refused, with the reason. A combination your system usually keeps for itself is accepted with a warning.
• Reset: a changed row is highlighted and has a default button. Reset all, at the top of the panel, puts every shortcut back.
• The right-click menus and the palette show the keys in effect next to each action, so a change made here shows there too.
• Rows without a button are not key bindings (a click, a palette command, something you type). The search finds them, but they cannot be changed.

The keys file. Only what you changed is kept, one action=keys line each, in the keys file of the configuration folder, next to settings. secondary stands for Cmd on macOS and Ctrl elsewhere. A line that cannot be used (unknown action, unreadable keys, keys already taken) is ignored and reported at launch; the default stays.

Updates

Once a day, in the background, Bref asks GitHub whether a newer version exists. If so, a discreet banner at the bottom of the window says so.

Updating

Where Bref can install itself, the banner offers Update (also Update Bref to … in the palette). It downloads the new version, installs it, and restarts. Your notes are saved first.

Elsewhere (Windows zip, compiled from source, bref-git, other Linux distributions), the banner links to the download page. Follow Upgrading.

If an update fails, Bref stays as it was and says why.

Trust

Bref checks nothing but HTTPS. The files are not signed (see Install), so an update is as trustworthy as downloading the same file by hand from the repository's releases.

Privacy

The check is the only network request the app makes until you press Update. It runs curl against api.github.com/repos/alarboulletmarin/bref/releases/latest, which sees your IP address and the client name bref, and nothing else. Without curl, or offline, nothing is shown.

Controls

• Check now: type check for updates now in the palette. Bref answers that it is up to date, or shows the banner. This works even when the daily check is off.
• Stop or resume the daily check: type updates in the palette. The choice is kept as updates=off in the settings file, and the time of the last check in the update file, both in the configuration folder.

Keyboard shortcuts

Every line of the help panel (F1), with the default keys of Linux and Windows. On macOS, read Cmd for Ctrl, and Alt for Ctrl when moving by word. Moving between panes is Cmd + Alt + arrows, and back and forward are Cmd + [ and Cmd + ].

Ctrl+P › word means: open the palette and type that word. A line without keys has no default shortcut. Any line that names an action can be given keys in the help panel: see Changing a shortcut.

Notes

Navigation

Diagrams

CSV tables

Appearance

Tables in a note

Typing

Editing

Blocks

Compatibility

Linux

• Bref needs a working Vulkan driver (Mesa or the vendor one).
• Bref draws its own title bar, shadow and resize edges, because GNOME under Wayland draws none for applications. Drag the window by the pill at the top right, by the title of the panel, or by the empty part of the rail or of a table's bar. A double click maximizes it. You can also hold Alt and drag from anywhere.

On macOS and Windows, the system title bar is used.

Fonts

IBM Plex Sans, Plex Mono and Plex Serif (page titles) are built into the app. Ideograms and emoji come from a font of your system. See Fonts.

Accessibility

• Every view can be reached from the keys.
• Every color pair stays readable in the 13 themes.
• A screen reader cannot read the window yet: the toolkit Bref is drawn with exposes no accessibility tree.
• Composing text with an input method (Chinese, Japanese, Korean, dead keys) works in notes. In a table cell or a diagram shape, the text is inserted as it is typed.

Troubleshooting

The window takes two seconds to open (Linux)

Another Vulkan driver is slow to load. Bref already skips the NVIDIA one when the machine has no NVIDIA card, unless you set VK_LOADER_DRIVERS_DISABLE yourself. To see what remains, run VK_LOADER_DEBUG=driver bref in a terminal.

The window does not open, with an error about a surface or an adapter

There is no usable Vulkan driver. Install the one for your GPU: vulkan-intel, vulkan-radeon, nvidia-utils… on Arch; mesa-vulkan-drivers on Ubuntu.

macOS or Windows refuses to open Bref

The downloads are not notarized or signed. See macOS and Windows for the one-time step.

Bold text is not bold

The font you picked is a variable font, which the text engine cannot embolden. Pick another font, or none to go back to the built-in ones.

A note was not renamed after I changed its title

Either another note already has that name, or the file name did not match the first line to begin with, and that line is not a # title you just added or changed. See Names and renaming.

Changes made elsewhere show up late

Bref is told by the system when the vault changes, and also looks at it every 30 seconds in case an event got lost. When the system cannot watch the folder, it looks every two seconds: on some network drives, or when Linux has run out of inotify watches. In that case, raise fs.inotify.max_user_watches.

See Changes from other programs.

Sync fails

git must reach the repository without asking anything, and the vault must be in a plain state. See Requirements and What it refuses.

Bref crashed

The last crash is written to the file crash of the configuration folder, with the version of Bref. Attach it to a bug report: on Windows, the window has no console to show it.

Known limits

• The name field of a new folder or a rename only edits at its end: type, or erase with Backspace.
• Links written as plain text inside a code block are not followed when a note is renamed.

Performance

Measured on the author's machine (Intel Core i9-13900H, Linux, release build), on vaults of 30-line notes linked to each other.

The app

At rest, Bref uses 0.3 % of one processor core.

One gesture

The time Bref spends between a key and the frame it hands to the graphics card, measured without a display. Drawing comes on top; a screen at 120 Hz leaves 8 ms for both.

Large files

• A table of 1,400 rows with a running total in each row: about 25 ms per keystroke. See Formulas.
• A table of 300,000 rows in a note opens in about 40 ms, and typing in it takes under 10 ms. See Very large tables.
• A CSV file of a million rows is parsed in under a tenth of a second, and a million rows cost about 12 MB. See CSV and TSV files.

Where the figures come from

The first table comes from the running app (window, memory, outside change) and from the scale benchmark (index, palette). The others come from benchmarks run without a display. To measure on your machine:

cargo test --release --locked -- --ignored --nocapture bench

Each benchmark reads its parameters from environment variables named in its doc comment.