Well Written

A multi-purpose "swiss army" tool for novel writers. Transform VS Code into a powerful novel writing environment with custom draft file format (.wrt), scene markers for organization, and repetition detection to improve your writing.

Features

📝 Draft Files (`.wrt`)

Custom file format optimized for creative writing with:

Word wrap enabled by default
Line numbers for easy reference
Clean, distraction-free editing experience

🎬 Scene Markers

Organize your manuscript with hierarchical markers:

$ for scenes (smallest division)
$$ for chapters (medium division)
$$$ for parts (largest division)

Features:

✨ Folding support - collapse/expand sections like Markdown headings
📑 Outline view - hierarchical navigation in sidebar
🔍 Breadcrumbs - see your current location
🎨 Theme-aware styling - works with both light and dark themes
📝 Empty markers allowed - plan your structure first, fill in later
👁️ Toggle visibility - hide scene markers from view with Ctrl+Alt+H (Mac: Cmd+Alt+H)
🚫 Not compiled - markers are for organization only, excluded from final output

Example:

$$$ Part One - The Beginning

$$ Chapter 1 - Introduction

$ Scene 1 - The Arrival
Story content here...

$ Scene 2 - The Meeting
More content...

$
Empty scene (to be written later)

📑 Markdown Headers

Use standard markdown headers for additional organization:

# H1 - Part level
## H2 - Chapter level
### H3 - Section level
#### H4 - Subsection level

Features:

🎨 Bold and colored styling (distinct from scene markers)
✨ Folding support - collapse/expand sections
✅ Compiled into final output (unlike scene markers)
📊 Counted in word count
📘 Converted to proper headings (H1-H4) in DOCX export

💬 Comments

Leave notes to yourself without affecting your draft:

📝 Single-line comments - use // for quick notes
📄 Multi-line comments - use /* ... */ for longer notes
🎨 Visual distinction - comments appear in gray italic (customizable)
🚫 Excluded from analysis - not counted in word count or repetition mode
🔓 Escapable - use \// or \/* */ to show literal text

Tip: If comments aren't visible in your theme, customize the color in settings: wellWritten.comments.color

Example:

$$ Chapter 1

// TODO: Add more description here
The hero entered the dark forest.

/* Note to self:
This scene needs more tension
and better pacing */

Use \// to show literal slashes (not a comment)

�🔄 Repetition Mode

Highlight repeated words to improve your writing:

🎨 Color-coded - each repeated word gets unique color
⚡ Real-time updates - highlights update as you type
🔤 Case-insensitive - "Test", "test", "TEST" treated as same
📝 Apostrophe support - "don't", "can't", "won't" work correctly
🌍 International support - full Polish diacritics (ąćęłńóśźż)
🎯 Easy toggle - Ctrl+Alt+R to enable/disable

Use cases:

Identify overused words
Spot repetitive phrases
Improve word variety
Polish your prose

📊 Word Count

Track your progress with automatic word counting:

📈 Status bar display - always visible word count
� Hover tooltip - detailed statistics appear on hover
🎯 Smart counting - excludes scene markers and other markup
📚 Page estimation - based on standard book pages (250 words/page)
🔧 Configurable - works with .wrt, .md, .txt (customizable)
🌍 International support - counts Polish and English text correctly

Statistics provided (on hover):

Word count
Character count (with and without spaces)
Page count (customizable words per page)

🎯 Goal Counter

Stay motivated with session-based writing goals:

⏱️ Session timer - track your writing time
📊 Progress tracking - see words written toward your goal (0/500)
⚡ Click to start/stop - easy one-click session management
🎉 Goal celebration - notification when you reach your target
📈 Writing speed - see your words per minute
🔧 Customizable goal - set your daily word target (default: 500)

How it works:

Click the goal counter in status bar to start your session
Write your draft - progress updates in real-time
Reach your goal and get a celebration notification!
Click again to stop and see your session summary

Session summary includes:

Total words written
Time elapsed
Average writing speed (words/minute)

👤 Character Cards

Manage your novel's cast with comprehensive character database:

📋 Create and organize - dedicated sidebar for all characters
⭐ Character types - main, secondary, background, or other
📝 Rich details - comprehensive character information
🖼️ Image support - attach character portraits (stored in character folders)
🏷️ Tag system - quick reference tags for use in drafts
🔍 Tag search - find where characters appear in your drafts
🎨 Custom properties - add your own custom fields
� Folder storage - each character in .well-written/characters/name-surname-alias-hash/ folder
🔍 Quick access - click any character to view/edit
🗑️ Easy management - create, edit, and delete with simple UI

⚠️ Version 2.0.0 Migration Notice: If upgrading from v1.x, use the "Well Written: Migrate Characters to v2.0.0" command from the Command Palette to convert your characters to the new folder-based structure. Make sure to backup your .well-written/characters/ folder before migrating!

Character card includes:

Basic Information:

Name and Surname: Character's full name
Alias: Short identifier for folder naming (letters, digits, underscore; uppercase)
Nicknames: Multiple nickname support
Age: Character's age (numeric)
Gender: Select from Male/Female/Other dropdown
Occupation: Character's job or role
Type: Main, Secondary, Background, or Other

Physical & Personality:

Appearance: Physical description (hair, eyes, build, etc.)
Personality Traits: Character's personality and behavior
Description: General character notes and background

Media & Tags:

Image: Attach character portrait (stored in character folder as portrait.ext)
Tags: Quick reference tags (e.g., #watson, #detective)
- Use tags in your .wrt files for quick character reference
- Search for tag occurrences across all drafts

Custom Properties:

Add any custom fields you need
Perfect for story-specific details (e.g., "Magic Ability", "Military Rank")

How to use:

Open the "Well Written" sidebar (book icon in activity bar)
Click "+" to create a new character card
Fill in character details in the comprehensive webview form
Browse for image: Use the Browse button to attach a character portrait
Add tags: Create tags like #watson or #detective for quick reference
Use tags in drafts: Reference characters in your .wrt files using their tags
Find tag occurrences: Right-click character → "Find Character Tags in Drafts"
Click character in the list to edit
Right-click to delete

Tag search example:

$$ Chapter 1

The butler opened the door. #watson looked terrified, 
his clothes soaked through.

#doctor Watson had seen many things in his military career.

After creating a character with tags #watson and #doctor, use "Find Character Tags in Drafts" to instantly locate all mentions!

Character Form Features:

🎨 Label Color - Assign a custom color to each character with built-in color picker
- Located next to Character Type field in Basic Information section
- Useful for color-coding character types or groups in your notes
📏 Auto-Resize Textareas - All textareas automatically adjust to fit content
- No more scrolling in small text boxes!
- Textareas expand as you type and show all content on load
- Universal feature across all webviews (Character, Events, Outline)
📂 Section Collapsing - Physical & Additional Info sections collapsed by default
- Cleaner initial view with only Basic Information expanded
- Expand sections as needed while editing
🏷️ Smart Tags Input - Improved tag management interface
- Input field with autocomplete appears above chips display
- Keyboard navigation with arrow keys to select suggestions
- Press Enter to add tag or create new one
- Click × on any chip to remove tag

Data Storage:

Characters stored in .well-written/characters/name-surname-alias-hash/ folders (v2.0.0+)
Each character has its own folder with character.json and portrait image
Images stored as portrait.jpg, portrait.png, etc. within character folder
Easy to version control and backup
Clean workspace structure with isolated character data

Custom Field Definitions: Save time by creating reusable custom field templates for your characters:

💾 Save as Project Defaults - share field definitions with your project team
🌍 Save as Global Defaults - use same fields across all your writing projects
🗑️ Remove from Defaults - delete unused fields from both project and global defaults (with confirmation)
🔄 Auto-merge - local project definitions override global ones
📝 Quick setup - add custom fields to any character, then click "Save as Defaults"

How it works:

Create a character and add custom properties (e.g., "Eye Color", "Weapon of Choice")
Click "💾 Save as Project Defaults" to save for this project
Or click "🌍 Save as Global Defaults" to use in all projects
Click "🗑️ Remove from Defaults" to delete unused field definitions (confirmation required)
New characters will have these fields pre-populated
Project defaults stored in .well-written/field-definitions.json
Global defaults stored in VS Code settings

📦 Compilation System

Combine multiple draft files into publishable manuscripts:

📚 Manage compilations - dedicated sidebar section below characters
🔍 Auto-detect files - automatically find all .wrt files in workspace (works immediately!)
📋 File ordering - manually arrange draft files in desired order
🎨 Compilation options:
- Strip scene markers from output
- Remove comments from output
📖 Metadata - add book title and author
💾 Export formats - Markdown and DOCX (Microsoft Word)
🚀 Quick compile - right-click compilation for instant export
💼 Configuration storage - saved in .well-written/compilations/ folder

How to use:

Open the "Well Written" sidebar
In the "Compilations" section, click "+" to create a new compilation
Enter a compilation name (e.g., "My Novel - Final Draft")
Book title auto-fills from compilation name (you can change it)
Fill in author name
Click "Detect Draft Files" to auto-add all .wrt files
- Works immediately! No need to save first
- Auto-creates compilation if it doesn't exist yet
Use up/down buttons to reorder files as needed
Configure compilation options:
- Strip markers: Remove scene markers ($, $$, $$$) from output
- Title page: Include/exclude title page with automatic page break (enabled by default)
- Automatically removes comments too
Click export button to choose format
Save the compiled manuscript to your desired location

Export formats:

📄 Markdown (.md): Plain text format, perfect for version control and further processing
📘 DOCX (.docx): Native Microsoft Word document with:
- Optional title page with automatic page break
- Proper heading hierarchy
- Title and author metadata (internationalization-friendly)
- Horizontal rule support (---, ***, ___)
- Professional manuscript formatting
- Ready to submit or edit in Word

Pro tip: Need PDF? Export as DOCX, then "Save As PDF" in Microsoft Word. You can also use free tools like LibreOffice or online converters.

Compilation config example:

{
	"id": "my-novel",
	"name": "My Novel - Final Draft",
	"sourcePaths": [
		"chapter-01.wrt",
		"chapter-02.wrt",
		"chapter-03.wrt"
	],
	"stripMarkers": true,
	"titlePage": true,
	"metadata": {
		"title": "The Great Adventure",
		"author": "John Smith"
	}
}

Quick compile:

Right-click any compilation in the tree view
Select "Compile Now" (play icon)
Choose export format
Save your compiled manuscript!

🏷️ Tags Database

Centralized management for all your story tags:

🗄️ Central Storage - All tags stored in .well-written/tags.json
🔄 Auto-Sync - Tags automatically synced from Characters, Events, and Outline
💡 Autocomplete - Smart suggestions when adding tags in any view
🔍 Tag Manager - View and manage all tags in one place
🧹 Cleanup - Easily remove unused tags or fix typos

Commands:

Well Written: Open Tag Manager - View and manage all tags
Well Written: Scan Workspace for Tags - Populate database from existing files

📝 Outline System

Organize your story structure with Parts, Chapters, and Fragments:

📋 Hierarchical Organization - Parts contain Chapters, Chapters contain Fragments
🔗 Event Linking - Link fragments to timeline events for perfect synchronization
🏷️ Tags & Characters - Tag fragments and assign characters for easy filtering
🔍 Smart Filtering - Filter by tags or characters to focus on specific story elements
⌨️ Keyboard Shortcuts - Full keyboard navigation for efficient workflow
📅 Date Tracking - Track when story events occur in your timeline
↔️ Event Sync - Sync title, description, date, tags, and characters from linked events
✨ Title Tag Extraction - Type #tagname in fragment titles to automatically add tags (v2.3.0)
👤 Title Alias Extraction - Type @ALIAS in fragment titles to attach characters (v2.4.1)

Title Tag & Alias Extraction (v2.3.0+):

Type tags directly in fragment titles using #tagname syntax
Type character aliases using @ALIAS syntax (v2.4.1)
Tags and characters automatically extracted when pressing Enter or on blur (losing focus)
Example: "Confrontation at #tavern with @GANDALF" → Adds TAVERN tag and GANDALF character
Tags are validated (letters, digits, underscore only) and converted to uppercase
Duplicate tags/characters prevented with case-insensitive checking
Works seamlessly with manual tag and character input

Keyboard Shortcuts:

Shortcut	Action	Details
`Alt+Delete`	Delete focused element	Deletes Part/Chapter/Fragment with confirmation (skips confirmation if empty)
`Alt+Up`	Focus previous element	Moves focus to previous Part/Chapter/Fragment or same button type
`Alt+Down`	Focus next element	Moves focus to next Part/Chapter/Fragment or same button type
`Enter`	Create new element	When focused on label input, creates new element below and focuses it
`Enter`	Unfold and focus description	When focused on fold button, opens fragment details and focuses description
`Escape`	Fold and focus fold button	When inside fragment details, closes fragment and focuses fold button

Tips:

Press Alt+Delete on empty elements to delete instantly without confirmation
Use Alt+Up/Down to quickly navigate between chapters or fragments
Press Enter on a fragment's fold button to expand and start writing description
Press Escape when editing to close the fragment and return to fold button
Alt+Up/Down is context-aware: navigates between same type (labels, buttons, datetime fields)

Fragment Features:

Numbered Display - Fragments show index numbers (1., 2., 3.) for easy reference
Expandable Details - Click fold button or press Enter to expand fragment
Event Attachment - Link fragments to events in your timeline
Event Sync Modal - Selectively sync title, description, date, tags, and characters from linked event
Expansion Preservation - Fragments stay open when attaching events or syncing
Auto-resize Textareas - Description textareas grow to fit content when expanded (v2.5.0)
Auto-scroll - View scrolls to show newly created fragments (v2.5.0)

View Options:

Skip delete confirmation - Delete without confirmation modal
Hide tags - Hide tag chips for cleaner view
Add new items unfolded - New fragments created expanded (v2.5.0)

⏰ Events System

Timeline management for your story events:

📅 Chronological Sorting - Events automatically sorted by date
📆 Month Grouping - Events grouped by month with collapsible headers (YYYY-MM)
🏷️ Tags & Characters - Tag events and assign characters for organization
🔍 Smart Filtering - Filter by tags or characters to find specific events
⌨️ Keyboard Shortcuts - Full keyboard navigation for efficient workflow
📝 Rich Details - Add descriptions and metadata to each event
🔗 Outline Integration - Link events to outline fragments for synchronization
✨ Title Tag Extraction - Type #tagname in event titles to automatically add tags (v2.3.0)
👤 Title Alias Extraction - Type @ALIAS in event titles to attach characters (v2.4.1)

Title Tag & Alias Extraction (v2.3.0+):

Type tags directly in event titles using #tagname syntax
Type character aliases using @ALIAS syntax (v2.4.1)
Tags and characters automatically extracted when pressing Enter or on blur (losing focus)
Example: "Battle of #winterfell with @STARK" → Adds WINTERFELL tag and STARK character
Tags are validated (letters, digits, underscore only) and converted to uppercase
Duplicate tags/characters prevented with case-insensitive checking
Works seamlessly with manual tag and character input

Keyboard Shortcuts:

Shortcut	Action	Details
`Alt+Delete`	Delete focused event	Deletes event with confirmation (skips confirmation if empty)
`Alt+Up`	Focus previous event	Moves focus to previous event in timeline or same button type
`Alt+Down`	Focus next event	Moves focus to next event in timeline or same button type
`Enter`	Create new event	When focused on label input, creates new event below and focuses it
`Enter`	Unfold and focus description	When focused on fold button, opens event details and focuses description
`Escape`	Fold and focus fold button	When inside event details, closes event and focuses fold button

Tips:

Press Alt+Delete on empty events to delete instantly without confirmation
Use Alt+Up/Down to navigate chronologically through your timeline
Press Enter on an event's fold button to expand and start editing
Press Escape when editing to close the event and return to fold button
Events with no label, description, tags, or characters can be deleted without confirmation

Event Features:

Month Headers - Events grouped by YYYY-MM for better organization (collapsible)
Expandable Details - Click fold button or press Enter to expand event
Auto-Focus - New events automatically focus on label input for quick entry
Smart Empty Detection - Empty events delete without interrupting workflow
Auto-resize Textareas - Description textareas grow to fit content when expanded (v2.5.0)
Auto-scroll - View scrolls to show newly created events (v2.5.0)

View Options:

Skip delete confirmation - Delete without confirmation modal
Hide tags - Hide tag chips for cleaner view
Add new items unfolded - New events created expanded (v2.5.0)

Quick Start

Create a draft file with .wrt extension

Add scene markers to organize your story:

$$ Chapter 1
$ Scene 1
Your story text here...

Add comments with // for notes that won't appear in your final draft
Click goal counter in status bar to start your writing session
Check your word count to see detailed statistics (hover over it)
Toggle repetition mode with Ctrl+Alt+R to check for repeated words
Hide scene markers with Ctrl+Alt+H for a cleaner writing view
Use outline view (View > Outline) to navigate through scenes
Fold sections to focus on specific parts of your manuscript

Commands

Draft Files (.wrt):

Command	Shortcut	Description
Well Written: Toggle Repetition Mode	`Ctrl+Alt+R` (Mac: `Cmd+Alt+R`)	Enable/disable repeated word highlighting
Well Written: Toggle Scene Marker Visibility	`Ctrl+Alt+H` (Mac: `Cmd+Alt+H`)	Show/hide scene markers (`$`, `$$`, `$$$`) from view

Note: All keyboard shortcuts can be customized via File → Preferences → Keyboard Shortcuts (or Code → Settings → Keyboard Shortcuts on Mac). Search for "Well Written" to see all available commands.

See Outline System and Events System sections for panel-specific shortcuts.

Settings

Customize the extension to match your preferences:

Setting	Default	Description
`wellWritten.sceneMarkers.color`	(theme color)	Color for scene markers. Leave empty to use theme color. Examples: `#6495ED`, `rgb(100, 149, 237)`, `rgba(100, 149, 237, 0.8)`
`wellWritten.repetitionMode.colors`	8 colors	Array of colors for repetition highlighting. Each repeated word gets the next color in rotation. Use semi-transparent colors (rgba) for best results.
`wellWritten.comments.color`	(theme color)	Color for comments (`//` and `/* */`). Leave empty to use theme color. Examples: `#808080`, `rgb(128, 128, 128)`, `rgba(128, 128, 128, 0.8)`
`wellWritten.wordCount.enabledFileTypes`	`[".wrt", ".md", ".txt"]`	File extensions that display word count in status bar.
`wellWritten.wordCount.wordsPerPage`	`250`	Words per page for page count calculation. Standard book page is 250-300 words.
`wellWritten.wordCount.countSingleLetters`	`false`	Include single-letter words (like "I", "a") in word count.
`wellWritten.goalCounter.dailyGoal`	`500`	Daily writing goal in words. Click the goal counter in status bar to start/stop tracking.

To customize:

Open Settings (Ctrl+,)
Search for "Well Written"
Modify settings to your preference

Configuring Word Wrap for .wrt Files

By default, .wrt files don't have word wrap configured. To enable word wrap at a specific column (like Markdown files), add this to your VS Code settings.json:

"[wrt]": {
  "editor.wordWrap": "wordWrapColumn",
  "editor.wordWrapColumn": 80
}

Or to wrap at the viewport edge:

"[wrt]": {
  "editor.wordWrap": "on"
}

Why this is needed: Markdown files have built-in language-specific defaults for word wrapping. Custom file extensions like .wrt use global settings unless you configure them explicitly. This gives you full control over how your draft files wrap.

Folding

Click arrow icon next to scene marker to fold/unfold
Ctrl+Shift+[ - Fold current section
Ctrl+Shift+] - Unfold current section
Ctrl+K Ctrl+0 - Fold all sections
Ctrl+K Ctrl+J - Unfold all sections

Outline View

The extension provides document symbols that appear in VS Code's built-in outline view:

Open the Outline panel in the Explorer sidebar (or View > Outline)
See hierarchical structure: Parts > Chapters > Scenes
Click any item to jump to that section
Automatically updates as you edit

Breadcrumbs

VS Code's breadcrumbs feature works with scene markers:

Enable breadcrumbs: View > Show Breadcrumbs
Shows current location in document structure
Click any level to see and navigate to other sections

Theme Compatibility

All features use theme-aware colors and work beautifully with:

✅ Light themes (Solarized Light, Light+, etc.)
✅ Dark themes (Dark+, Monokai, Dracula, etc.)
✅ High contrast themes

Requirements

VS Code version 1.105.0 or higher

Known Limitations

Repetition mode: Currently doesn't group word forms (e.g., "run", "running", "ran" are separate)
Scene markers: For organization only - not included in exports or compilation

Enjoy writing your novel! 📚✨

For detailed version history and release notes, see CHANGELOG.md.

Well Written

ZakladWebdeweloperski

Well Written

Features

📝 Draft Files (`.wrt`)

🎬 Scene Markers

📑 Markdown Headers

💬 Comments

�🔄 Repetition Mode

📊 Word Count

🎯 Goal Counter

👤 Character Cards

📦 Compilation System

🏷️ Tags Database

📝 Outline System

⏰ Events System

Quick Start

Commands

Settings

Configuring Word Wrap for .wrt Files

Scene Marker Navigation

Folding

Outline View

Theme Compatibility

Requirements

Known Limitations

Well Written

ZakladWebdeweloperski

Well Written

Features

📝 Draft Files (.wrt)

🎬 Scene Markers

📑 Markdown Headers

💬 Comments

�🔄 Repetition Mode

📊 Word Count

🎯 Goal Counter

👤 Character Cards

📦 Compilation System

🏷️ Tags Database

📝 Outline System

⏰ Events System

Quick Start

Commands

Settings

Configuring Word Wrap for .wrt Files

Scene Marker Navigation

Folding

Outline View

Breadcrumbs

Theme Compatibility

Requirements

Known Limitations

📝 Draft Files (`.wrt`)