Writing a book in VS Code

The idea sounds wrong for about a day. Then you notice that a book is a folder of text files, that you want to know what changed since Tuesday, that you want to search 90,000 words in 40 milliseconds, and that you would rather not find out in 2031 that your writing app's format is no longer readable.

Novelists have been quietly doing this for years. Here is the setup that works, and — more usefully — the point at which the editor hands off.

Why a code editor suits a manuscript

• The files are yours. Markdown on your disk. No account, no export step, no format to be locked out of.
• Real version history. Git gives you every draft, a diff of what changed in a scene, and the ability to write a risky rewrite on a branch and throw it away without ceremony.
• Search that scales. Find every use of a character's name across the whole book, with a regex if you need one, instantly.
• One file per chapter. The file tree is your outline, and reordering chapters is renaming files.
• It is fast and it is quiet. No sync spinner, no toolbar, and it works on a plane.

Making it feel like a writing app

Out of the box it is set up for code, which is the wrong shape for prose — full-width lines, no wrapping, a cursor that jumps by word boundaries you did not intend. Four settings fix most of it. Put them in a workspace .vscode/settings.json so they apply to the book and not to your other work:

{
  "[markdown]": {
    "editor.wordWrap": "bounded",
    "editor.wordWrapColumn": 80,
    "editor.lineNumbers": "off",
    "editor.quickSuggestions": false,
    "editor.renderWhitespace": "none",
    "editor.fontFamily": "Georgia, serif",
    "editor.fontSize": 16,
    "editor.lineHeight": 1.7
  },
  "files.autoSave": "afterDelay",
  "editor.minimap.enabled": false
}

Then Zen Mode (Ctrl/Cmd+K Z) for the actual writing, which hides everything but the text. Two more worth knowing: the built-in Markdown preview is Ctrl/Cmd+K V, and Ctrl/Cmd+Shift+F searches the whole folder.

Extensions, kept to the four that earn their place: a spell checker (Code Spell Checker, with a project dictionary for your invented names), a prose linter if you want one (write-good or Vale — Vale is the serious option and takes an afternoon to configure), Markdown All in One for list continuation and table formatting, and a word-count extension for the status bar.

Structuring the folder

Number the chapter files. It is the whole trick, and it is what makes the folder sort into reading order and concatenate correctly:

book/
  manuscript/
    00-front-matter.md
    01-the-problem-with-mornings.md
    02-subtraction.md
    03-what-to-keep.md
    99-back-matter.md
  images/
  notes/
    characters.md
    timeline.md
  .gitignore

Leave gaps in the numbering if you like inserting chapters, or use 010, 020, 030 so you never have to renumber. The notes/ folder stays out of the book but inside the repository, which is one of the quieter benefits of this setup: research and manuscript are versioned together.

One convention worth adopting from the start: one sentence per line. It looks strange for about an hour and then it is obviously right — Git diffs become sentence-level instead of paragraph-level, and moving a sentence is moving a line. Markdown joins consecutive lines into a paragraph, so the output is unaffected. (Unless you are writing verse, where you want the opposite; line breaks in Markdown covers that case.)

Git, without the ceremony

You need about five commands, and none of the branching model arguments apply to a book with one author:

git init
git add -A && git commit -m "Chapter 3 draft"
git log --oneline              # every draft, in order
git diff                       # what changed since the last commit
git checkout -- chapter-03.md  # undo today entirely

Commit at the end of each writing session with a message describing the session. A year in, git log is a writing diary you did not have to keep. Push to a private repository and you have an offsite backup with full history, which is more than any word processor's autosave gives you.

Where the editor stops

At the point where you need a book rather than a manuscript. VS Code's Markdown preview is a web page in a panel — it is styled for reading code documentation, it has no page size, no margins, no page numbers, and printing it gives you exactly what printing a web page gives you. That is not a shortcoming; it was never trying to typeset anything.

So the last step happens elsewhere, and there are two routes. If you enjoy toolchains, Pandoc plus a LaTeX engine will typeset the folder from the command line and you can wire it to a VS Code task. If you would rather choose typefaces by looking at them, combine the chapters into one file and design it in something built for pages:

# Numbered files concatenate in reading order
cat manuscript/*.md > book.md

That single file is the handoff. Combining Markdown files goes into the details worth getting right — heading levels, image paths, the blank line between files. From there bukpress takes it: typefaces, margins, paper and covers set once, a hard page break on a line of ---, and the same file exporting both a PDF and an EPUB.

The division holds up well in practice. The editor is where the words happen and where the history lives; the production step is a separate thing you do at the end, and neither tool has to pretend to be the other. The sample book is what the second half looks like — eight pages from one Markdown file, exported once.