Pages and sections

How the page tree is built#

Kirbon shows your folder as a tree of sections and pages:

• Every .md file is a page. Its title is its first # heading; without one, the file name.
• Every folder is a section. Its README.md (or index.md when there is no README) is the section’s own page, and the section is shown as a page with child pages.
• The README.md at the top of the folder is Home, and its title is the name of the documentation. Without one, the documentation is named after its folder.
• Hidden files, the assets/ folder and folders without any Markdown inside are left out.

Pages are sorted by title. To choose the order yourself, drag pages in the sidebar: Kirbon then writes a small .pages file in that folder with one name per line. You can also edit it by hand.

Empty folders and sections#

A folder without any Markdown opens with “No pages found.” and the buttons New Page and Choose Another Folder…. Selecting a section that has no page of its own shows its title and an index of its pages and subsections as links — or, when it is empty, a note such as “No pages in Marketing yet” — with a Turn into Page button that gives it a page.

When you open a documentation for the first time, Kirbon expands the top-level sections; after that, the tree keeps the rows you expanded and collapsed, even when files change on disk.

Create pages and sections#

When a page without children gets its first child page, Kirbon asks first and explains what changes: roadmap.md becomes roadmap/README.md, and links to it are updated.

The sidebar menu#

Right-click a page in the sidebar, or press the ⋯ on its row, for everything you can do with it.

Rename a page#

Choose Rename… — or select the row and press Return. The sheet shows the new title, the file name change (old.md → new.md) and how many links in other pages will be updated. One Undo reverses the title, the file name and the links together.

Typing a new title on the page never renames the file. When they no longer match, Kirbon shows Rename File and Update Links… under the title.

Move and reorder#

• Drag a page onto a section to move it there, or between rows to put it at that place. Hold ⌥ to copy instead. Places a page can’t go show ⊘.
• Move To… does the same from the keyboard: filter the sections, pick one, press Return.
• If the section already has a page with that file name, choose Keep Both, Replace… or Stop.

Links to the page from other pages, and the page’s own relative links and image paths, are rewritten as part of the move. A message at the bottom of the sidebar says how many links were updated, with Undo.

Duplicate, convert and delete#

• Duplicate Page (⌘D) makes “Title copy” next to the original, with its links adjusted.
• Turn into Folder… turns a page with child pages back into a plain folder; Turn into Page gives a folder its own README.md page.
• Add Home Page gives a documentation without Home its own README.md, titled with the documentation’s name — from File, or from the ⋯ on Pages at the top of the tree. Remove Home Page… (in File and on the Home row) moves Home to the Trash; the other pages stay where they are, and Kirbon asks first when Home has text or other pages link to it.
• Move to Trash (⌘⌫ in the sidebar) moves the file to the system Trash after telling you how many pages link to it. Its attachments are kept.

Copy a link, show the file#

• Copy Link to Page (Edit menu or the sidebar menu) copies a Markdown link such as [Roadmap 2027](product/roadmap-2027.md). Pasted into a page in Visual, it becomes a link relative to that page.
• Hold ⌥ for Copy File Path: the file’s full path, for Terminal or another app.
• Show in Finder reveals the page’s file.

The sidebar from the keyboard#

The sidebar can be resized from 200 to 400 points and hidden with ⌃⌘S; it never covers the page on its own.

Starred pages and getting around#

Star the pages you use often with Add to Starred; they appear under Starred at the top of the sidebar and in Navigate ▸ Starred, in every window of that documentation. Remove from Starred takes a page off the list. Starred pages follow pages you rename or move in Kirbon. Starred pages are kept on your Mac, not in the folder. To fold the list away, click the chevron that appears when you point at Starred; each window remembers it.

Breadcrumbs above the title show where a page lives; each part is a link, and the last one opens a menu of the neighbouring pages and of this page’s headings. Back and Forward (⌘[ ⌘]) work like in a browser, and Reveal in Sidebar (⇧⌘J) shows the current page in the tree.