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. → Live preview
- Vim grammar, plus writer verbs. Operators, motions, text objects, counts,
registers and
.— andgbfor bold,gtto tick a task,g1–g6for headings. → Editing · Writing - Notes that compose.
[[links]]you walk withgf,![[embeds]]that pull one note into another, and export to Markdown, text, HTML or PDF. → Notes · Export - 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
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.
A tour — writer verbs, Insert mode, focus mode and the file tree.
Install
Run --init-config once: the leader keys, such as Space fe for the file
tree, are defined in that config and do nothing without it. You need Rust 1.88
or newer, a truecolor terminal and a Nerd Font
(or glyphs.nerd_fonts = false). Getting started
covers installing from a clone and the optional PDF tools.
First five minutes
| 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, 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 - 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.