shoin 0.2.1

A no-clutter terminal Markdown editor with modal editing
shoin-0.2.1 is not a library.

Shoin (書院) is the study alcove of a traditional Japanese house: a writing desk built into a bay by the window, and nothing else in the room.

Why Shoin

  • No permanent interface. Text in a centered column and nothing else. The file tree, finder and splits open on a key and close on the same key. → Panels
  • Live preview that never lies. The line under the cursor shows raw Markdown; every other line shows the finished text: headings, bold and italic, quotes, task lists, tables and highlighted code. Tables line up their columns in the file as you type. → Live preview
  • Vim grammar, plus writer verbs. Operators, motions, text objects, counts, registers and . — and gb for bold, gt to tick a task, g1–g6 for headings, >al and Alt-j to nest and move a list item with everything under it. → Editing · Writing
  • Notes that compose. [[links]] you walk with gf, ![[embeds]] that pull one note into another, and export to Markdown, text, HTML or PDF. → Notes · Export
  • Reads like a pager, too. shoin -p notes.md prints a note as the editor shows it — concealed, embeds expanded, pictures drawn — and --pager pages it. Pipe text in (curl -s …/README.md | shoin -p), or open a note with shoin -R to read it without changing it. → Reading
  • Careful with your files. Atomic saves, no autosave unless you ask, and a merge view when something else edits a file you're working on. → Files
  • Plain config, hot-reloaded. A folder of TOML files; save one and the running editor updates. → Configuration

.md and .txt only. It is not a code editor, though fenced code blocks are highlighted in seventeen languages.

See it work

Formatting — the finished page with the cursor's line raw, gb, gi and g2 in place, and a table that lines itself up on Esc.

Editing prose with Vim's grammar — ciw and ., moving a paragraph with dap and p, ci(, list items that continue themselves, undo and redo.

Composing a text from notes — two notes embedded in an essay, :embed full to read it without seams, gf to follow a link, and a new note created from a link that didn't resolve yet.

Pictures in the text — ![[picture.png]] drawn as real pixels in the column, giving way to its raw link on the cursor's line, and moving with the text around it. Needs kitty, Ghostty, WezTerm or iTerm2.

Reading without editing — shoin -p printing a note into the shell, piped chapters paged through less, and shoin -R scrolling a note that can't be changed.

A tour — writer verbs, Insert mode, focus mode and the file tree.

Install

Shoin runs on macOS and Linux, on x86_64 and ARM. Windows isn't supported yet: it isn't built or tested there.

macOS, with Homebrew:

brew install nol00p/tap/shoin

macOS or Linux, with Cargo (Rust 1.88 or newer):

cargo install shoin

macOS or Linux, with the installer, which fetches a prebuilt binary:

curl --proto '=https' --tlsv1.2 -LsSf https://github.com/nol00p/shoin/releases/latest/download/shoin-installer.sh | sh

It works with no config: the leader keys, such as Space fe for the file tree, are built in. shoin --init-config writes an annotated copy of the config to ~/.config/shoin/ when you want to change it. You need a truecolor terminal and a Nerd Font (or glyphs.nerd_fonts = false). Getting started covers the other ways to install and the optional PDF tools.

First five minutes

shoin notes.md            # open a file; it's created on the first :w
shoin                     # a blank page with a few ways in drawn on it
shoin -p notes.md         # print it as the editor shows it (--pager to page it)
shoin -R notes.md         # read it: j/k scroll, q quits, i edits
cat README.md | shoin -p  # anything piped in
Do this Press
Type, then stop typing i … Esc (or jk)
Save, quit :w, :q
Bold the word under the cursor gb
Open the file tree Space fe
Follow a [[link]], then come back gf, then Ctrl-^
Dim everything but this paragraph :focus paragraph
See every key on one page Space hl

:help inside the editor explains the rest: :help bindings, :help commands, :help writer and :help config.

Documentation

  • Getting started — install, requirements, first run
  • Live preview — how concealment works
  • Editing — motions, operators, text objects, lists, registers
  • Clipboard — system clipboard, SSH, pasting
  • Writing — writer verbs, focus, typewriter and zen modes
  • Panels — file tree, finder, buffers, splits
  • Notes — links, embeds, gf, pictures
  • Reading — print or page a note, read one piped in, open it read-only
  • Export — Markdown, text, HTML, PDF, from the editor or the shell
  • Files — saving, autosave, outside edits and :diff
  • Configuration — the config folder, themes, key bindings
  • Design notes — why Shoin works the way it does
  • Reference: keys · commands · command line
  • Changelog

License

Licensed under the Apache License, Version 2.0. See LICENSE, or https://www.apache.org/licenses/LICENSE-2.0.

Unless you state otherwise, any contribution you intentionally submit for inclusion in this work is licensed as above, per section 5 of the License, with no additional terms.

Every dependency is permissively licensed — MIT, Apache-2.0, ISC, Zlib, Unlicense or CC0 — so nothing in the tree conflicts with distributing Shoin under Apache-2.0.