Skip to content
Documentation

Get started

Open a folder of Markdown or create new documentation, find your way around the window and write your first page.

Open your documentation

Kirbon works on an ordinary folder of Markdown files — a docs folder, a Git repository, or a folder of notes. Nothing needs to be imported or converted.

  1. Open Kirbon. The Welcome window offers Open Folder… (⌘O), New Documentation… and your recent folders.
  2. Choose the folder that holds your .md files. You can also drop a folder on the Welcome window or on the Kirbon icon in the Dock.
  3. The window opens as soon as the page list is ready. Search indexing continues in the background — you can read and edit while it runs.
A documentation window: the page tree in the sidebar and a launch plan page in Visual.
A documentation window: the page tree on the left, the page on the right.

Kirbon asks macOS for access to the folders you choose, and only to them. It remembers them, so next time they open from Recent or reopen by themselves when Kirbon starts. A folder that was moved or deleted is marked in the Recent list. The same folders are in File ▸ Open Recent, where Clear Menu forgets all of them except the ones that are open, and in the documentation switcher at the top of the sidebar, which also brings forward a documentation that is already open. Untick Show this window when Kirbon opens in the Welcome window if you don’t want to see it.

Start from scratch

File ▸ New Documentation… asks for a name and a place, then creates a folder with a Home page (README.md with the name as its title) and opens it.

Find your way around

Part of the windowWhat it’s for
SidebarHome, sections and pages of the documentation, Starred pages and Filter Pages.
ToolbarBack and Forward, the page title and its status, formatting controls, the three views, search and Page Info.
PageThe page itself. Click anywhere and type — there is no Edit button.
InspectorThe page’s Outline and Info, shown with ⌥⌘O and ⌥⌘I.

The status under the page title tells you what is going on with the file: the section name while nothing has changed, then Unsaved Changes, Saving… and Saved. See Saving and changes on disk.

Write your first page

  1. Choose File ▸ New Page (⌘N). The page appears as “Untitled” in the current section, with the caret in its title.
  2. Type a title and press Return. Kirbon names the file after the title — “Release Notes” becomes release-notes.md.
  3. Write. Type / at the start of a line to insert a table, a callout, a code block or an image.
A task, a heading and a callout, typed in Visual.

If you leave a new page without typing anything, no file is created. Once the file exists, changing the title never renames it on its own: Kirbon offers Rename File and Update Links… under the title instead.

What happens to your files

Kirbon reads and writes plain Markdown. Opening a page changes nothing; editing a page rewrites only the blocks you changed. Kirbon doesn’t add metadata to your pages — the only file it may add is a small .pages file when you reorder pages by hand. See Files Kirbon creates.