evdboom_Bindery/vscode-ext

Bindery

Markdown book authoring tools for VS Code: typography formatting, multi-language chapter export (DOCX, EPUB, PDF), dialect conversion, translation management, and AI assistant integration via a bundled MCP server.

Features

Typography Formatting

Converts plain-text typography to professional typographic characters:

Input	Output	Description
...	…	Ellipsis
--	—	Em-dash (preserves --- for markdown HR)
"text"	“text”	Curly double quotes
'text'	‘text’	Curly single quotes
don't	don’t	Smart apostrophes

HTML comments are preserved and not modified.

How to use:

• Keybinding — Ctrl+K Ctrl+B (markdown editors only)
• Right-click a markdown file → Format Typography
• Format Document (Shift+Alt+F) — registered as a markdown formatter
• Format on Save — enable bindery.formatOnSave in settings
• Explorer — right-click a folder → Format All Markdown in Folder

Chapter Merge & Export

Merges ordered chapter files into a single document with TOC generation:

• Markdown (.md) — with table of contents and separators
• DOCX (.docx) — via Pandoc, with page breaks and optional cover image
• EPUB (.epub) — via Pandoc, with chapter splitting and optional cover
• PDF (.pdf) — via Pandoc (intermediate DOCX) + LibreOffice headless conversion, giving consistent output quality across all platforms

Dialect exports (e.g. British English from a US English source) are handled automatically: the extension copies the source language folder to a temporary dialect folder, applies all configured substitution rules, merges, and removes the temp folder after export.

How to use:

• Editor toolbar — click the $(book) Bindery Export button (visible on markdown files)
• Command Palette (Ctrl+Shift+P) → search "Bindery"

Dialect & Translation Management

Substitution rules (e.g. US→UK spelling) are applied in tiers (later tiers win):

1. Built-in — common US→UK conversions (color→colour, center→centre, etc.)
2. General — bindery.generalSubstitutions in VS Code user settings (follows you to every workspace)
3. Project — .bindery/translations.json in the workspace

Cross-language glossary entries (e.g. EN→NL world terms) are also stored in .bindery/translations.json for agent reference and consistency checking.

AI Assistant Integration (MCP)

Bindery includes a bundled MCP server that makes your book's chapters, arc files, character notes, search index, memory, status tracker, and translation data available to AI assistants directly inside VS Code.

GitHub Copilot Chat — tools are registered automatically when the extension activates. Use #bindery_search, #bindery_get_chapter, etc. in chat.

Claude for VS Code / Codex — run Bindery: Register MCP Server once per workspace. This writes .vscode/mcp.json pointing to the bundled server. Both extensions pick this up automatically on next reload.

Available MCP tools (38)

Tool	Description
bindery_health	Check workspace status: settings, search index, and embedding backend
bindery_init_workspace	Create or update .bindery/settings.json, translations.json, .bindery/README.md, and the opinionated Arc / Notes / Characters / SESSION / PREFERENCES / memory / status scaffold
bindery_setup_ai_files	Generate AI instruction files (CLAUDE.md, copilot-instructions.md, etc.), Claude skills, and refresh generated .bindery/README.md
bindery_settings_update	Merge a partial patch into .bindery/settings.json
bindery_index_build	Build or rebuild the search index (lexical + optional semantic)
bindery_index_status	Show index metadata and stale-status hints
bindery_search	Full-text search: lexical BM25, semantic rerank, or full semantic mode
bindery_get_text	Read any file by relative path, with optional line range
bindery_get_chapter	Full chapter content by number and language
bindery_get_book_until	Chapters from a start through a target chapter, concatenated in order
bindery_get_overview	Chapter structure — acts, chapters, titles
bindery_get_notes	Notes files, filterable by category or character name
bindery_note_list	List story note files under the configured notes folder
bindery_note_get	Read a single story note by path
bindery_note_create	Create a story note under the configured notes folder
bindery_note_append	Append markdown content to a story note
bindery_character_list	List structured character profiles
bindery_character_get	Read a structured character profile by name
bindery_character_create	Create a character profile and update the character index
bindery_character_update	Update a character profile and refresh the index row
bindery_arc_list	List structured arc files
bindery_arc_get	Read a structured arc file
bindery_arc_create	Create an arc file and update the arc index
bindery_arc_update	Update an arc file and refresh the arc index
bindery_format	Apply typography formatting to a file or folder
bindery_get_review_text	Git diff of uncommitted changes plus any <!-- Bindery: Review start/stop --> regions (works on committed work too)
bindery_update_workspace	Fetch and pull the current branch, with branch/default-branch reporting
bindery_git_snapshot	Commit changes in bindery workspace, with optional push
bindery_get_translation	Look up cross-language glossary entries
bindery_add_translation	Add or update a glossary entry
bindery_get_dialect	Look up dialect substitution rules
bindery_add_dialect	Add or update a dialect substitution rule
bindery_add_language	Add a language and scaffold its story folder
bindery_memory_list	List session memory files with line counts
bindery_memory_append	Append a dated entry to a memory file
bindery_memory_compact	Overwrite a memory file with a summary (backs up original)
bindery_chapter_status_get	Read per-chapter progress (draft, in-progress, done, needs-review)
bindery_chapter_status_update	Upsert chapter progress entries
bindery_session_focus_get	Read working state from SESSION.md (optionally a single section)
bindery_session_focus_update	Update neutral SESSION.md sections (replace/append); leaves PREFERENCES.md untouched
bindery_inbox_process	Enumerate Notes/Inbox.md items with stable numbers and propose destinations (read-only)
bindery_inbox_resolve	Remove already-routed inbox items by number after confirmation

bindery_search supports lexical, semantic_rerank, and full_semantic modes. Semantic modes require an Ollama instance and fall back to lexical results with a warning if unavailable.

For the standalone MCP server (Claude Desktop / Cowork), two additional tools are available: list_books and identify_book for multi-book discovery. See mcpb/README.md for full MCP documentation and usage examples.

These are agent-facing MCP / language-model tools. The Command Palette also exposes host commands for the same structured note, character, arc, memory, and chapter-status workflows. Host prompts cover common fields; agents can call the MCP/LM tools directly for complete structured payloads.

File Discovery

The extension automatically discovers and orders your chapter files:

Story/
  EN/                          ← language folder
    Prologue.md                ← first
    Act I/                     ← act folders (sorted by Roman numeral)
      Chapter1.md              ← chapters (sorted by number)
      Chapter2.md
    Act II/
      Chapter9.md
    Epilogue.md                ← last

Localized prologue/epilogue names are supported (e.g. Proloog.md for Dutch) via the language configuration.

Commands

All commands are available from the Command Palette (Ctrl+Shift+P) under the Bindery category.

Command	Description
Initialize Workspace	Create .bindery/settings.json, translations.json, .bindery/README.md, and the opinionated Arc / Notes / Characters / SESSION / PREFERENCES / memory / status scaffold
Setup AI Assistant Files	Generate CLAUDE.md, copilot-instructions.md, .cursor/rules, AGENTS.md, Claude skills, and refresh generated .bindery/README.md
Register MCP Server	Write .vscode/mcp.json for Claude / Codex MCP discovery
Format Typography	Apply typography formatting to the active markdown file (Ctrl+K Ctrl+B)
Format All Markdown in Folder	Apply typography to all .md files in a folder
Insert Review Start Marker (or wrap selection)	Insert <!-- Bindery: Review start -->, or wrap the current selection in matched start/stop markers (Ctrl+K Ctrl+,)
Insert Review Stop Marker	Insert <!-- Bindery: Review stop --> at the cursor (Ctrl+K Ctrl+.)
Merge Chapters → Markdown / DOCX / EPUB / PDF / All Formats	Export configured languages and dialects
Find Probable US→UK Words	Scan Story/EN for likely US spellings
Add Dialect Rule	Add a dialect substitution rule (e.g. color→colour)
Add Translation (Glossary)	Add a cross-language glossary entry
Add Language	Add a new language and scaffold its story folder
Open translations.json	Open the translations file in the editor
List Notes / Create Note / Append to Note	Work with notes under the configured notes folder
List Characters / Create Character Profile / Update Character Profile	Maintain structured character profiles and the character index
List Arcs / Create Arc File / Update Arc File	Maintain structured story-architecture files and the arc index
List Memories / Append Memory / Compact Memory	Maintain durable .bindery/memories/ files
Show Chapter Status / Update Chapter Status	Read or update .bindery/chapter-status.json
Show Session Focus / Update Session Focus / Append Handoff Note	Read or update the neutral working-state sections of SESSION.md
Process Inbox / Resolve Inbox Items	Triage Notes/Inbox.md: list items with stable numbers, then remove routed items by number

Keybindings only fire while editing a markdown file (editorTextFocus && resourceLangId == markdown); rebind via File → Preferences → Keyboard Shortcuts if they conflict with another extension.

Configuration

Settings can be defined in .bindery/settings.json (preferred) or VS Code settings (fallback).

Setting	Default	Description
bindery.storyFolder	"Story"	Folder containing language subfolders
notesFolder in .bindery/settings.json	"Notes"	Story notes root used by generated AI guidance and MCP tools
arcFolder in .bindery/settings.json	"Arc"	Story architecture folder for overall, act, chapter, thread, or custom arcs
charactersFolder in .bindery/settings.json	"Notes/Characters"	Character index and one-profile-per-character folder
sessionFile in .bindery/settings.json	"SESSION.md"	Ephemeral working-state file (current focus, next actions, open questions, handoff) maintained by session_focus_*
preferencesFile in .bindery/settings.json	"PREFERENCES.md"	Durable working preferences; user-owned, scaffolded once and never tool-written
arcGranularity in .bindery/settings.json	"act"	Preferred planning granularity: overall, act, chapter, thread, or custom
bindery.languages	EN	Language configurations (see below)
bindery.mergedOutputDir	"Merged"	Output directory for merged files
bindery.author	""	Author name for EPUB/DOCX metadata
bindery.bookTitle	""	Book title (string or per-language map)
bindery.pandocPath	"pandoc"	Path to Pandoc executable (auto-detected if left as default)
bindery.libreOfficePath	"libreoffice"	Path to LibreOffice executable (auto-detected if left as default)
bindery.formatOnSave	false	Auto-format typography on save (only files inside the story folder)
bindery.mergeFilePrefix	"Book"	Prefix for output filenames
bindery.generalSubstitutions	[]	Dialect substitution rules applied across all projects

Language Configuration

Each language entry supports:

{
  "code": "EN",
  "folderName": "EN",
  "chapterWord": "Chapter",
  "actPrefix": "Act",
  "prologueLabel": "Prologue",
  "epilogueLabel": "Epilogue",
  "isDefault": true,
  "bookTitle": "The Hollow Road",
  "dialects": [
    { "code": "en-gb", "label": "British English" }
  ]
}

• isDefault marks the primary language (used as fallback for title resolution)
• bookTitle provides a per-language title override for export metadata
• dialects lists dialect codes that derive from this language; during export the extension copies the source folder, applies substitution rules from .bindery/translations.json, and merges the converted content

Adding a New Language

Add to .bindery/settings.json (or bindery.languages in VS Code settings):

{
  "languages": [
    { "code": "EN", "folderName": "EN", "chapterWord": "Chapter", "actPrefix": "Act", "prologueLabel": "Prologue", "epilogueLabel": "Epilogue", "isDefault": true },
    { "code": "FR", "folderName": "FR", "chapterWord": "Chapitre", "actPrefix": "Acte", "prologueLabel": "Prologue", "epilogueLabel": "Épilogue" }
  ]
}

Or use the Bindery: Add Language command, which scaffolds the story folder with stub files mirroring the default language structure.

Requirements

• VS Code 1.85+
• Git (recommended) — needed for version tracking and review features. Auto-initialized during workspace setup. Install
• Pandoc (optional) — needed for DOCX/EPUB/PDF export. Install
• LibreOffice (optional) — needed for PDF export only. Install

Pandoc / LibreOffice Auto-Detection

On all platforms the extension resolves tool paths automatically:

1. Explicit bindery.pandocPath / bindery.libreOfficePath user setting (if set and the file exists)
2. Command on PATH (where.exe on Windows, which elsewhere)
3. Well-known install locations:
   • Windows: %LOCALAPPDATA%\Pandoc\pandoc.exe, %ProgramFiles%\Pandoc\pandoc.exe, %ProgramFiles%\LibreOffice\program\soffice.exe
   • macOS: /opt/homebrew/bin/pandoc, /Applications/LibreOffice.app/Contents/MacOS/soffice
   • Linux: /usr/bin/pandoc, /usr/bin/libreoffice

You usually do not need to configure anything — install Pandoc/LibreOffice normally and exports will work.

Building from Source

cd vscode-ext
npm install
npm run compile

To install locally:

npm install -g @vscode/vsce
vsce package
code --install-extension bindery-*.vsix