Sable / Guide

The Sable guide

Everything you need to set up Sable and keep your hands on the story. The same guide is included in the app as an editable Markdown file.

This guide is written by Claude Code.

• Screenshots
• Your writing folder
• Just open a file
• The writing desk
• Fiction Projects
• Export
• Coming from Scrivener
• A little Markdown
• Keyboard shortcuts
• A quiet writing space
• A file beside your draft
• VoiceOver, keyboard, and display settings
• How Sable protects your files
• Your writing record
• A goal with a deadline
• Updates
• Reporting a problem

Screenshots

Your writing folder

Your words live in ordinary Markdown files. They are plain text, so you can open them in other editors and keep them in a folder you control.

A writing folder is optional (see Just open a file below). If you want one, choose it during setup. iCloud Drive, Dropbox, or OneDrive work well if you want your writing on other devices; your cloud service handles synchronization, so let it finish before editing the same file elsewhere. New documents can be saved anywhere with ⌘S. The status at the bottom confirms when a save completes; that confirms the local file, not cloud syncing.

Just open a file

You don’t need a writing folder to use Sable. It opens any Markdown file (.md, .markdown, .mdown, .mkd, .mkdn, .mdwn) or plain text file from anywhere on your Mac.

• Ways to open one. Finder’s Open With → Sable, File → Open Markdown File… (⌘O), File → Open Recent, dragging a file onto Sable’s Dock icon, or dragging it onto the page.
• First launch. Setup offers Just Open a File and Explore a Sample Project beside choosing a folder. Just Open a File skips the folder, hides the writing desk (⌃⌘S brings it back), and shows the Open panel, and nothing asks you to choose a folder later. Not Now (or Escape) closes setup without deciding, and Sable asks again next time. Opening a file from Finder skips setup altogether.
• With no writing folder, the writing desk shows the folder of the file you have open. An unsaved document has nothing to show yet. Choose a writing folder, or stop using one, in Settings → General → Writing folder. Stopping only makes Sable forget the folder; none of your files are touched.
• A file outside your writing folder. The desk keeps showing your writing folder and adds one quiet line saying the file is somewhere else. Show Folder shows that folder in the desk for now, with a Back to link to return. It lasts only until you go back or quit Sable, and your saved writing folder never changes. Opening a file from your writing folder also brings the desk back by itself.
• Safe everywhere. Saving, the notice when an open file is moved to the Trash or deleted, and Put Back all work the same for a file from anywhere. Snapshots of a file outside a writing folder live in a hidden .sable-revisions folder beside the file, created only when you save a snapshot.

Make Sable the default for Markdown

Settings → General → Markdown files shows which app opens Markdown files now. Make Sable the Default for Markdown changes it, and macOS asks you to confirm. Plain text (.txt) files are a separate button, also off by default; macOS treats every plain-text file the same way, not only .txt. Sable never changes this on its own.

To switch back, select a Markdown file in Finder, choose File → Get Info, pick another app under Open with, and click Change All…. Settings notices the change when you return to Sable.

The writing desk

The desk on the left has two tabs: Files and your Outline. Click a file to open it in the same window. Sable asks you to save or discard unsaved changes first.

• Create. The + above the list makes a new Markdown file or folder. Hover a folder and a small + appears beside it: click it and choose New Markdown File or New Folder to create inside that folder. Control-click a folder offers the same. A new folder opens its parent and waits with its name ready to type. Press Return to keep the name or Esc to keep “Untitled Folder”. If the name is already taken, Sable says so and leaves the folder as it was. Folders can go inside folders as deep as you like, in plain writing folders and in Fiction Projects.
• Rearrange. Drag files and folders onto folders to nest them. Drop on the path above the list to move things back up.
• Rename and trash. Control-click for Rename and Move to Trash. An Undo appears right after trashing. You can rename or move a file while it’s open, on the page, beside your draft, or as a card. It stays open under its new name, and the next save goes there. The same happens when you rename or move it in Finder.
• Colors and pins. Give any file or folder a color or pin it to the top. Name your colors (Draft, Revised, Final) in the list options. Chips above the list filter by color or pin.
• Categories and headings. In your writing folder, the + above the list has New Category… for groups like School, Work, or Hobbies. A category is a real folder at the top of your writing folder, so Finder, iCloud, and your other Macs see it too. Drag folders or files onto a category’s heading to move them into it, and drag them onto Folders or Files to move them back out. Hover a category’s heading and a small + appears: New Markdown File or New Folder makes one inside the category. Control-click the heading for the same, plus rename, color, order, Reveal in Finder, and Turn into Regular Folder, which keeps the folder and everything in it and only stops it being a category. If you made categories in a 1.0 beta, they lived only in Sable’s settings; a note above the list offers to turn them into folders, and saves a snapshot of every file that moves first. Click any heading (a category, Fiction Projects, Folders, or Files) to fold it away; a folded heading shows how many items it holds, and stays folded until you open it again. Making something new opens the heading it lands under.
• Focus. Control-click a folder and choose Focus on This Folder to see only that folder. The path above the list takes you back out.
• Search. The search box looks through every folder beneath the one you’re viewing, not only the ones that are open. It matches names, not the text inside files.
• Keyboard. Arrow keys move through the list, → and ← open and close folders, Return opens, ⇧Return renames, ⌘Delete moves to the Trash.
• Recent tab (optional). Off until you want it. Turn on Recent tab in Settings → General → Writing desk, or in the desk’s sliders menu, and a Recent tab appears beside Files and Outline. It lists the files you have open, newest first, from any folder; click one to switch to it. Turning it off forgets the list, and Clear Recent Files empties it any time. The list is kept only on your Mac and is recorded only while the tab is on.
• Make it yours. The sliders button sets sorting, icons, file extensions, last-modified dates, word counts, and compact rows. Drag the desk’s right edge to resize it.
• It steps back while you write. After a few seconds of steady typing, the desk fades almost away where it is, so it stops pulling at your eye and your page never shifts. Move the mouse or click and it comes straight back; a pause in typing leaves it faded, so it stays out of the way while you think. Turn this off in Settings → General → Writing desk, or with View → Fade Writing Desk While Typing. With Increase Contrast it fades less, and with VoiceOver or Keyboard navigation on it doesn’t fade at all.

The Outline tab turns your # headings into a list you can name Chapters, Scenes, Episodes, or anything else, and filter to one heading level. This changes the sidebar only, never your headings.

Fiction Projects

A Fiction Project gives one story a clear home while keeping every part portable. Choose New Fiction Project from the + menu and Sable creates folders for Manuscript, Characters, Locations, World, Notes, and Images. You can also turn a folder you already have into a project without moving or renaming anything in it.

Projects sit above ordinary folders in the desk. Character, location, and world-note files can open as small cards beside the page, so the detail you need stays close without becoming another writing tab. Add a portrait, pin a card open, or let it collapse to a quiet tab.

Scene tags connect a chapter to its characters, locations, and world notes. The small strip fades while you type and opens the relevant card with a click. The Manuscript tab shows total words, an optional goal, and chapter lengths; drag a chapter to reorder the reading sequence without changing its filename.

A sample project to look around in. First launch offers Explore a Sample Project, and Help → Open Sample Project opens it any time. It is Northwatch: three short chapters with scene tags, four character cards (Mara has aliases and a portrait), two locations, a world note, a Concept note, an Outline tagged for the Story Timeline, a note to yourself, and a snapshot to compare. Sable copies it into your Documents folder as Sable Sample Project (with a number added if that name is taken) and opens its first chapter. Your writing folder isn’t changed (so setup still comes back next launch until you choose a folder or Just Open a File), and the copy inside Sable is never edited. Asking again opens your copy as you left it; to start fresh, move your copy to the Trash first.

Open a project from anywhere. File → Open Fiction Project… (⇧⌘O) opens a Fiction Project that lives outside your writing folder, or brings you to one inside it. The desk shows it for now and your writing folder stays as it was; Back to your writing folder is one click away. Choose a folder that isn’t a project yet and Sable offers to make it one, without moving or changing anything in it.

Recent projects. Under the file list, Recent Projects keeps the last few Fiction Projects you opened, wherever they live. It stays closed until you click it, and isn’t shown while you’re inside a project. File → Open Recent Project has the same list. Right-click a project there to remove it; nothing on disk is touched.

Export a manuscript

On a Fiction Project’s Manuscript tab, choose Export… or press ⇧⌘E to turn the chapters in your chosen order into one PDF, EPUB, Word, or Markdown file. Pick the chapters and choose a Manuscript look for submissions or a Book look for reading, then adjust it under Layout: headings left or centered, a title page (on or off, left or centered), the font and size, single, 1.5, or double line spacing, margins, and page numbers and a running header. PDF and Word follow every choice; EPUB takes the heading and title page alignment. Picking a look again, or Reset, starts over from it. A project remembers its layout. File → Export This Document… exports only the page you have open, and remembers its own layout for the next document. If the project holds more than one book, the menu beside Chapters chooses the folder they come from: Manuscript, or any other folder with writing in it. Another folder’s files, subfolders included, come in name order.

Coming from Scrivener

File → Import Scrivener Project… turns a Scrivener project into a new Fiction Project. Choose the project (its name ends in .scriv) and Sable shows what it found before writing anything: how many scenes, chapters, characters, locations, and notes, and anything that can’t become Markdown.

• You choose where each part goes. Every top-level item in the binder has a menu: Manuscript, Characters, Locations, World, Notes, or Don’t Import. Sable suggests the manuscript folder for Manuscript, character and location sheets for cards, Research for Notes, and leaves out the Trash and Scrivener’s blank template sheets. If your project holds more than one book, send each extra book’s folder wherever suits you.
• A folder of scenes becomes one chapter file. Scenes are divided by a scene break, in binder order. Each scene’s title, synopsis, status, label, keywords, and document notes sit above it as a note to yourself (<!-- like this -->), which Reading Mode, exports, and word counts all leave out.
• Footnotes, comments, and annotations come too. A Scrivener footnote (inline or in the inspector) becomes a Markdown footnote: a mark like [^1] where it was, and its words at the end of the chapter, numbered from 1 in each chapter. A comment or an inline annotation becomes a note to yourself at the same spot. Reading Mode and exports don’t lay footnotes out yet; they show the marks as typed.
• Italics, bold, and scene breaks carry over. Fonts, colors, and spacing are left behind. A chapter’s own synopsis, status, label, and keywords go at the top of its file, between the --- lines.
• Pictures, PDFs, and saved web pages are copied as they are, pictures into Images and the rest into Notes. Pictures pasted into the middle of a document’s text can’t come along. Import Report.md, in the new project, lists every one.
• Your Scrivener project is never changed. Sable only reads it, and writes a new folder where you choose. The save panel starts in your writing folder: saved there, the new project stays on your desk with the others. Saved anywhere else, the desk shows it only for now; File → Open Fiction Project… brings it back.

Projects from Scrivener 3 and Scrivener 2 can both be read. Scrivener 2’s older format is less tested, and Sable says so in the preview; look the result over against your project.

A little Markdown

Use **two asterisks** for bold and *one* for italics. Start a line with # for a heading, or ## for a smaller one. A dash starts a list item, a blank line starts a new paragraph, and a greater-than sign starts a quotation. Use backticks for inline code and two tildes for ~~strikethrough~~.

Keyboard shortcuts

Pinch the trackpad to zoom; you can turn that off in Writing Style. With a mouse, hold ⌘ and turn the scroll wheel: away from you zooms in, toward you zooms out. A two-finger horizontal swipe shows or hides the writing desk. Zoom changes the display, never your Markdown.

A quiet writing space

Try Graphite, Midnight, Chalk, Forest, Obsidian, Arcane, Starfall, Cosmic, Parchment, Paper, or Mist in Writing Style. Chalk is a dark slate with a softer edge that draws the eye toward the page. Starfall is a deep blue with faint particles falling slowly behind the text (Arcane's rise). Cosmic, made for the run-up to 1.0, is deep indigo space seen out of focus: slow clouds of blue and plum haze drift behind the page, with a few soft lights in teal, amber, and dusty rose, while the words stay pale and steady. Each has its own switch. Under Reduce Motion the particles stop and Cosmic's haze holds still. They also hold still while you're in another app or Sable's windows are minimized, and pick up where they left off when you come back, so a Sable left open in the background uses next to no power. Mist is a cool grey-blue light theme. Pick one of five writing fonts or choose your own. The toolbar slides in when you move the pointer near its edge and never shifts your page. Put it on the top, left, or right, keep it visible, or turn it off entirely with ⌥⌘T.

Paragraph focus dims surrounding paragraphs. Reading mode hides Markdown marks, and switching to it and back keeps the paragraph at the top of the window where it is; your cursor stays where you left it unless you click somewhere on the reading page. Prose suggestions cross out possible cuts only on screen, and you control the word list in Settings. Name highlights can softly mark character, location, and world-note names; each kind can be enabled separately in Settings. Sentence structure colors nouns, verbs, and other word classes on your Mac. None of these display features changes your saved text.

A file beside your draft

Control-click any Markdown file in the writing desk and choose Open Beside Current Document, or click the small split-pane icon that appears when you hover a file. It opens as a formatted reading view next to your draft. Choose Edit to work on it in place, then Read to return to the clean view. It’s handy for a character sheet or a map of the world while you write a chapter.

VoiceOver, the keyboard, and your display settings

Sable works with VoiceOver, with the keyboard alone, and with the display options in System Settings → Accessibility.

• VoiceOver. Every button, field, and sheet has a name, and VoiceOver reads a short hint for what it does. Toolbar tools you switch on and off (Writing desk, Paragraph focus, Prose suggestions, Spelling & grammar, Highlight names) say whether they are On or Off; the rest just act. In the writing desk each file, chapter, and heading is one item that says what it is and its state, such as “folder, collapsed” or “open for writing”. The buttons that otherwise appear only when the pointer hovers (Show as card, Open beside current document, adding to a folder, Rename, Pin, Move to Trash) are VoiceOver actions on the item: open the Actions rotor and choose one. Cards are named groups with actions to pin, close, move to another corner, and resize; a collapsed card opens and stays open when you activate it. On the Story Timeline each point is a button read as its heading and beat, like “Chapter 3, Midpoint”, and the writing record in Settings has a spoken summary and an audio graph.
• The keyboard. Every toolbar action is also in the menus. To Tab between buttons and fields, turn on Keyboard navigation in System Settings → Keyboard. Escape closes every sheet and popover. In Customize Tools, select a tool and press ⌥↑ or ⌥↓ to move it, and ⌘Return to add the selected tool; the Move Up and Move Down buttons do the same. In the Manuscript tab, ↑ and ↓ move between chapters, Return opens one, and ⌥↑ or ⌥↓ moves it. In a card’s picture frame, the arrow keys reposition the picture. In the writing desk’s file list, use the arrow keys to move, Return to open, and ⇧Return to rename.
• Staying reachable. When VoiceOver or Keyboard navigation is on, the toolbar stays in view instead of hiding until the pointer comes near, and the page makes room for it.
• Display settings. Increase Contrast brightens the dimmed text (Markdown symbols, quotes, notes, and paragraph focus), uses stronger name and sentence colors, firms up the outlines of cards and the toolbar, and gives you a flat page with no edge shading or drifting particles. Reduce Transparency makes the toolbar, cards, and scene tags solid instead of frosted, with the same flat page. Reduce Motion turns off the sliding and fading animations, the drifting particles, and the shimmer on names. Without any of them, every theme’s text, dimmed symbols, and highlight colors are kept at or above the WCAG contrast ratios, and the check that guards this runs with every change to Sable.

How Sable protects your files

• Files from anywhere. These protections follow the open file itself, not a folder. A file opened from Finder is saved, noticed in the Trash, and put back the same way as one in your writing folder.
• All or nothing. When Sable rewrites a file, it writes the new version beside the old one and swaps them in a single step. If the disk fills up or your Mac stops halfway, the old file is still whole.
• A snapshot before big changes. Find & Replace in Project and every restore from Revision History save a safety snapshot first. If that snapshot can’t be saved, nothing is changed.
• Undo that won’t erase newer words. Undo Replace puts back only files that still read exactly as the replacement left them. Anything you changed afterwards is left alone, and Sable tells you which files those were.
• Files open beside your draft. When Find & Replace or a restore touches a file that’s open beside your draft, that file saves your latest words first and then shows the new text. If the file changes somewhere else (another app, or another Mac through iCloud or Dropbox) while you have edits beside your draft, Sable doesn’t save over it. Choose Keep Mine or Use Saved File; the version you don’t keep goes to the Trash as a copy.
• Exports never replace your writing. An export can’t be saved over the files it was made from, over a file that’s open in Sable, or inside the Manuscript folder. If it replaces some other file, that file goes to the Trash as a copy first.
• If an open file is trashed or deleted. Renaming or moving an open file, in Sable or in Finder, just carries it along. When a file you have open is moved to the Trash or deleted outside Sable, a note appears under the page or in the side pane. For a trashed file, Put Back returns it to its folder. For a deleted one, Save Again writes it back where it was. Save As… keeps it somewhere else. Without one of these, Sable keeps saving a trashed file into the Trash, where emptying the Trash would delete it. The writing desk won’t move a file to the Trash while it’s open in another window.
• Nothing is deleted outright. Move to Trash sends files to the macOS Trash, with Undo right afterward. Import always makes a new file. The only things Sable deletes are snapshots: when you delete one, and daily snapshots older than the latest 20.
• Files that aren’t downloaded yet. If iCloud is set to Optimize Mac Storage and a file hasn’t been downloaded, Sable downloads it when it’s opened, searched, or saved in a snapshot. While you’re offline it can’t be read: Sable shows an error and leaves the file alone, and Revision History may list it as deleted. Restores stop until it can be read.

Your writing record

Settings → General charts the words you’ve added each day for the last 30 days, with your best day and a lifetime total. It only counts progress you keep — deleting words never counts against you — and it isn’t a streak, so a quiet day changes nothing. It’s kept only on this Mac, and you can clear it any time.

A goal with a deadline

This is optional, and it’s off until you want it. For a challenge like 50,000 words in November, turn on Track a goal with a deadline in Settings → General, just above your writing record. Until you do, nothing about goals appears in Settings or while you write; turn it off again any time, and a goal you set earlier is kept for next time. Then choose November: 50,000 words, or Custom… to pick your own word count, start date, and end date (up to a year). Only one goal is active at a time.

Once it’s set, Settings shows:

• So far: the words you’ve written on the goal’s days.
• Pace today: where an even pace, the same number of words every day, would have you at the end of today. The chart draws it as a dashed line beside your own.
• Today’s target: what today needs to be for the goal to finish on time, spreading what’s left evenly over the days left. If you’ve written less than an even pace, the sentence above the chart simply says what finishes on time, such as “1,900 a day finishes on time.” If you’re ahead, it says you’re on pace. Today’s target is worked out from the words you wrote before today, so it holds steady while you write.
• Days left, counting today and the goal’s last day.

Like the writing record, it only counts words you add. Deleting words never subtracts from it, and there are no streaks, badges, or notifications. Words you write on the start date all count, even the ones you wrote before you set the goal that day. Goals are measured in calendar days, so a clock change or a trip to another time zone doesn’t shift them.

Turn on Show today’s share in the footer to see a small “1,204 / 1,667 today” beside the session goal while you write. It’s off by default, and it only appears while the goal is running.

Clear Goal removes the goal and keeps your writing record. Clearing the record keeps your goal. Both are kept only on this Mac.

Updates

Sable checks for updates while it’s open: every day, every 3 days, or every week, as you choose in Settings → General, where you can also turn automatic checks off. Check for Updates… in the Sable Markdown Writer menu checks right away. Either way, you choose when to install and restart. Get beta updates, off by default, also offers early builds published ahead of a stable release; they may be rougher. If you turn it off again, you keep the build you have until a newer stable release arrives.

Reporting a problem, or sharing an idea

Help → Report a Bug… opens a small window with two boxes, What happened? and Steps to reproduce. A checkbox, on by default, adds your Sable version, macOS version, and Mac model to the report; the exact values are shown beneath it, so you can see what would be included. Open in GitHub then opens your browser to a bug report with your words already filled in. Nothing is sent from Sable: you read the report on GitHub and decide whether to submit it, which needs a free GitHub account. If your text is too long to fit in a link, the end is cut with a note, and you can paste the rest on GitHub.

If Sable has closed unexpectedly in the last seven days, the window also offers Show Latest Crash Report. Sable doesn’t open that report until you click. Then it shows it in the window, where you can read it and copy it into the GitHub report yourself. It can include file paths on your Mac, and nothing is attached for you.

Help → Send Feedback or Ideas opens the Ideas category of Sable’s GitHub Discussions in your browser.

Missing something? Tell us on GitHub, or download Sable.