Text Formatting with Markdown

Kosshi uses Markdown for text formatting — symbols like **bold** and *italic* that add formatting to plain text.

Not every outliner uses Markdown. Some use rich text, and some have no formatting at all. This article explains Markdown's role in an outliner and how Kosshi handles it.

Outliners and formatting

The core of an outliner is structural manipulation. You organize your thinking by changing parent-child relationships and order. Text formatting — bold, italic, links — is a secondary concern, separate from structure.

Because of this, outliners take different approaches to formatting.

Bike focuses on text editing and does not use Markdown. OmniOutliner uses rich text. WorkFlowy and Kosshi use Markdown.

The choice depends on what you want from text formatting.

Structure and formatting: division of roles

In a typical Markdown document, # headings serve as both structure and formatting. They define the document's hierarchy and display as visual headings at the same time. Changing the hierarchy means rewriting # symbols by hand.

In an outliner, the tree handles structure. Parent-child relationships and indentation are the hierarchy itself. There is no need for # to create it. Changing the hierarchy means moving a row.

This means Markdown's role in an outliner is not about structuring the whole document. It focuses on inline formatting within individual rows. **bold** to emphasize part of a line, [link](URL) to create a link, `code` to mark code — Markdown handles these in-line expressions.

For this reason, Kosshi does not support # heading syntax. When the tree already represents hierarchy, layering # headings on top creates two competing structures. If a row's depth and its heading level disagree, which one is the real structure becomes ambiguous.

# appears on export.

When you export an outline as Markdown, you can enable heading conversion. Rows that have children become # headings, and leaf rows become body text. Tree depth maps directly to heading level.

• Project plan → # Project plan
  • Design phase → ## Design phase
    • Requirements finalized → body text
    • Tech selection in progress → body text

You never type # inside the outliner. Heading levels are derived from the tree structure, generated only at the point of export. You manipulate structure as a tree while editing, and convert it to # headings when you need a document.

Plain text and compatibility

Markdown adds formatting with symbols, so text remains readable even in its raw form.

When you write **bold**, the text itself is still the string "bold." The formatting information is embedded as symbols, so you can open it in any text editor and still read the content.

With rich text, formatting lives in a separate layer from the text. When you copy and paste between apps, styles sometimes break or carry over unintentionally. With Markdown, the text itself carries its formatting, so these problems do not arise.

Markdown is also supported by blogs, GitHub, wikis, documentation tools, and many other platforms. When you export a Kosshi outline as Markdown, it works directly in other tools. With a proprietary format, moving text to another tool requires conversion. With Markdown, your writing works in other environments as-is.

Displaying Markdown symbols

There are several approaches to displaying Markdown symbols on screen: split-pane preview with source and result side by side, always-visible source with syntax highlighting, and cursor-aware switching where symbols appear only at the cursor.

Kosshi uses the third approach. When the cursor is on a row, Markdown symbols appear and you can edit them directly. When the cursor moves away, the symbols disappear and formatting takes effect.

Typora, Bear, Obsidian, and many other Markdown editors use this same approach.

A setting to "Always show Markdown symbols" switches to always-visible source for those who prefer it.

Trade-offs

Markdown cannot express every kind of formatting. Font colors, font sizes, and complex layouts are not supported.

Kosshi supports bold, italic, strikethrough, inline code, links, checkboxes, block quotes, and code blocks. This covers the basic formatting needed for writing.

Rich text is more expressive, but also means more decisions about fonts, sizes, and styles. Markdown limits its expressiveness in exchange for keeping text readable and portable.

For someone unfamiliar with Markdown syntax, a rich text toolbar is more intuitive. With live preview, however, the result of your input appears as formatted text immediately, so the syntax becomes familiar quickly. Kosshi also supports keyboard shortcuts (Cmd+B for bold, Cmd+I for italic), so formatting works without knowing the syntax.

For details on Markdown usage, see the Markdown guide.