|
Fractal - Markdown & Outliner Editor VS Code
| Element | Pattern Input | Toolbar | Shortcut |
|---|---|---|---|
| Heading 1 | # + Space |
Heading menu → H1 | Ctrl+1 |
| Heading 2 | ## + Space |
Heading menu → H2 | Ctrl+2 |
| Heading 3 | ### + Space |
Heading menu → H3 | Ctrl+3 |
| Heading 4 | #### + Space |
Heading menu → H4 | Ctrl+4 |
| Heading 5 | ##### + Space |
Heading menu → H5 | Ctrl+5 |
| Heading 6 | ###### + Space |
Heading menu → H6 | Ctrl+6 |
| Paragraph | (default) |
— | Ctrl+0 |
| Unordered List | - or * + Space |
List button | Ctrl+Shift+U |
| Ordered List | 1. + Space |
Numbered list button | Ctrl+Shift+O |
| Task List | - [ ] + Space |
Task list button | Ctrl+Shift+X |
| Blockquote | > + Space |
Quote button | Ctrl+Shift+Q |
| Code Block | ``` + Enter |
Code button | Ctrl+Shift+K |
| Table | | col1 | col2 | + Enter |
Table button | Ctrl+T |
| Horizontal Rule | --- + Enter |
HR button | Ctrl+Shift+- |
Inline Elements
| Element | Pattern Input | Toolbar | Shortcut |
|---|---|---|---|
| Bold | **text** + Space |
Bold button | Ctrl+B |
| Italic | *text* + Space |
Italic button | Ctrl+I |
| Strikethrough | ~~text~~ + Space |
Strikethrough button | Ctrl+Shift+S |
| Inline Code | `text` + Space |
Code button | Ctrl+` |
| Link | [text](https://github.com/raggbal/fractal/blob/HEAD/url) Space conversion not supported |
Link button | Ctrl+K |
| Image |  Space conversion not supported |
Image button | Ctrl+Shift+I |
⌨️ Special Operations
Markdown Editor Shortcuts
These shortcuts are active when the Fractal markdown editor is focused:
| Shortcut | Action |
|---|---|
Cmd+/ / Ctrl+/ |
Open Action Palette |
Cmd+N / Ctrl+N |
Add Page (create & link a new .md file) |
Cmd+. / Ctrl+. |
Toggle Source Mode |
Cmd+Shift+. / Ctrl+Shift+. |
Open in Text Editor |
Ctrl/Cmd + S |
Save |
Ctrl/Cmd + Z |
Undo |
Ctrl/Cmd + Shift + Z |
Redo |
Ctrl/Cmd + B |
Bold |
Ctrl/Cmd + I |
Italic |
Ctrl/Cmd + K |
Insert link |
Ctrl/Cmd + F |
Find |
Ctrl/Cmd + H |
Find and replace |
Ctrl/Cmd + L |
Open source file with selected lines in text editor |
Side Panel Shortcuts
These shortcuts apply to the side panel markdown editor (Notion-style peek):
| Shortcut | Action |
|---|---|
Opt+Left / Alt+Left |
Navigate back through MD links followed inside the side panel |
Opt+Right / Alt+Right |
Navigate forward |
Cmd+/ / Ctrl+/ → Add Page |
Create a new MD under <sidePanelDir>/pages/ and insert the link |
Esc |
Close the side panel (or close the image lightbox if open) |
Outliner Shortcuts
These shortcuts are active when the Fractal outliner is focused:
| Shortcut | Action |
|---|---|
Enter |
Create new sibling node |
Option+Enter / Alt+Enter |
Create child node |
Shift+Enter |
Add/focus subtext |
Tab |
Indent node |
Shift+Tab |
Outdent node |
Backspace at start |
Clear checkbox (if any) → otherwise merge with previous node |
[ ] / [x] + Space at start |
Convert node into a checkbox (preserves remaining text) |
Cmd+Shift+X / Ctrl+Shift+X |
Toggle checkbox (add if missing, then true ⇄ false) |
Cmd+Shift+Option+X / Ctrl+Shift+Alt+X |
Remove checkbox |
↑ / ↓ |
Navigate between nodes |
Ctrl+Shift+↑ / Ctrl+Shift+↓ |
Move node up / down |
Ctrl+. |
Toggle collapse/expand |
Ctrl+Shift+. |
Toggle all collapse/expand |
Cmd+] / Ctrl+] |
Scope into current node |
Cmd+[ / Ctrl+[ |
Scope out (back to document) |
Cmd+B |
Bold toggle |
Cmd+I |
Italic toggle |
Cmd+E |
Inline code toggle |
Cmd+Shift+S |
Strikethrough toggle |
Ctrl+F |
Focus search bar |
Ctrl+N |
Add new node at end |
Cmd+Z |
Undo |
Cmd+Shift+Z |
Redo |
Escaping Block Elements
| Element | Key | Action |
|---|---|---|
| Code Block | Shift+Enter |
Exit code block and create new paragraph |
| Blockquote | Shift+Enter |
Exit blockquote and create new paragraph |
| Mermaid/Math | Shift+Enter |
Exit block and create new paragraph |
| Code Block | ↑ at first line |
Exit to previous element |
| Code Block | ↓ at last line |
Exit to next element |
| Blockquote | ↑ at first line |
Exit to previous element |
| Blockquote | ↓ at last line |
Exit to next element |
| Mermaid/Math | ↑ at first line |
Exit to previous element |
| Mermaid/Math | ↓ at last line |
Exit to next element |
Escaping Inline Elements
To exit inline formatting, type the closing marker followed by Space:
| Element | Input | Action |
|---|---|---|
| Bold | ** + Space |
Close bold and move cursor outside |
| Italic | * + Space |
Close italic and move cursor outside |
| Strikethrough | ~~ + Space |
Close strikethrough and move cursor outside |
| Inline Code | ` + Space |
Close inline code and move cursor outside |
Table Operations
| Key | Action |
|---|---|
Tab |
Move to next cell |
Shift+Tab |
Move to previous cell |
Enter |
Insert new row |
Shift+Enter |
Insert line break within cell |
↑ / ↓ |
Navigate between rows |
← / → |
Navigate within/between cells |
Cmd+A |
Select all text in current cell |
Code Block Operations
| Key | Action |
|---|---|
Tab |
Insert 4 spaces |
Shift+Tab |
Remove up to 4 leading spaces |
Cmd+A |
Select all text within code block |
List Operations
| Key | Action |
|---|---|
Tab |
Indent list item (increase nesting) |
Shift+Tab |
Outdent list item (decrease nesting) |
Enter on empty item |
Convert to paragraph or decrease nesting |
Backspace at start |
Convert to paragraph |
| Pattern at line start + Space | Convert list type in-place (e.g., 1. converts - item to ordered list) |
Multi-Block Selection
| Key | Action |
|---|---|
Tab |
Insert 4 spaces at the beginning of each selected block |
Shift+Tab |
Remove up to 4 leading spaces from each selected block |
💻 Code Block Features
Supported Languages
The editor supports syntax highlighting for the following languages:
javascript, typescript, python, json, bash, shell, css, html, xml, sql, java, go, rust, yaml, markdown, c, cpp, csharp, php, ruby, swift, kotlin, dockerfile, plaintext
Language Aliases: js→javascript, ts→typescript, py→python, sh→bash, yml→yaml, md→markdown, c++→cpp, c#→csharp
Display Mode / Edit Mode
- Display Mode: Shows syntax-highlighted code with language tag and copy button
- Edit Mode: Plain text editing (click on code block to enter)
- Expand Button: Open code in a separate VS Code editor tab for larger editing
Mermaid Diagrams
Code blocks with language mermaid are rendered as diagrams:
graph TD
A[Start] --> B{Decision}
B -->|Yes| C[Action]
B -->|No| D[End]
- Click on diagram to edit source
- Diagram re-renders when exiting edit mode
KaTeX Math Equations
Code blocks with language math are rendered as mathematical equations using KaTeX:
E = mc^2
\int_0^\infty e^{-x} dx = 1
\sum_{n=1}^{\infty} \frac{1}{n^2} = \frac{\pi^2}{6}
- Each line is rendered as an independent display-mode equation
- Click on the rendered equation to edit the LaTeX source
- Equations re-render automatically (500ms debounce) while editing
- Invalid LaTeX is shown as a red error message (does not break the layout)
- Empty blocks show "Empty expression"
- Navigate in/out with arrow keys, just like code blocks and Mermaid diagrams
draw.io Diagrams
Insert and edit draw.io / diagrams.net diagrams directly inside Markdown without leaving VS Code. The diagram is stored as an .drawio.svg file (a real SVG that draw.io can re-open) and embedded in markdown as a regular  image — fully portable, viewable on GitHub, and editable from any draw.io client.
Insert a new diagram
- Slash command — Type
/in the editor to open the action panel, then choose Insert Drawio Diagram - Cmd+/ opens the action panel keyboard shortcut
- A draw.io editor tab opens; design your diagram and save (
Cmd+S) - The diagram is saved into the configured
outlinerFileDir(default./files) as<filename>.drawio.svg - An image reference
is inserted at the cursor position automatically - The thumbnail rendered inline in the markdown editor is the actual SVG — no separate preview file is generated
Edit an existing diagram
- Click the rendered thumbnail to reopen the diagram in the draw.io editor
- Save (
Cmd+S) to update the underlying.drawio.svg— the markdown thumbnail refreshes automatically (file watcher echoes the change back to the editor)
No separate .drawio source file is needed; the SVG itself contains the editable diagram data.
🖼️ Image & File Path Configuration
Images and file attachments can be saved to custom directories when pasting or drag-and-dropping. The same path resolution rules apply to both.
Configuration Levels
| Level | Setting File | Description |
|---|---|---|
| Global | ~/Library/Application Support/Code/User/settings.json (macOS)%APPDATA%\Code\User\settings.json (Windows)~/.config/Code/User/settings.json (Linux) |
VS Code user settings |
| Project | .vscode/settings.json |
Project-level override |
VS Code settings.json Setting
{
"fractal.imageDefaultDir": "./images",
"fractal.forceRelativeImagePath": true,
"fractal.fileDefaultDir": "./files",
"fractal.forceRelativeFilePath": true
}
Path Behavior Matrix
The forceRelative settings (forceRelativeImagePath / forceRelativeFilePath) allow you to separate the save location from the path written in Markdown.
Use case: When you want to save files to a specific absolute path but reference them using relative paths from the Markdown file, set this to true.
Note:
forceRelativeonly takes effect when the directory setting is an absolute path. When using relative paths, the setting is ignored as paths are always relative.
The same rules apply to both images and file attachments:
| Directory Setting | forceRelative | Save Location | Path in Markdown |
|---|---|---|---|
Absolute (e.g., /Users/shared/images) |
false (default) |
Specified absolute path | Absolute path |
Absolute (e.g., /Users/shared/images) |
true |
Specified absolute path | Relative path from Markdown file |
Relative (e.g., ./images) |
false |
Relative to Markdown file | Relative path |
Relative (e.g., ./images) |
true |
Relative to Markdown file | Relative path (setting ignored) |
🎨 Configuration
VS Code Settings
| Setting | Description | Default |
|---|---|---|
fractal.theme |
Editor theme (github, sepia, night, dark, minimal, perplexity, things) |
things |
fractal.fontSize |
Base font size (px) | 16 |
fractal.imageDefaultDir |
Default directory for saved images | "" (same as markdown file) |
fractal.forceRelativeImagePath |
Force relative paths for images | false |
fractal.imageMaxWidth |
Max width (px) for images and .drawio.svg thumbnails in the editor / side panel / outliner page side panel. Toolbar / lucide / command-palette icons are excluded. Min 100 |
400 |
fractal.language |
UI language (default, en, ja, zh-cn, zh-tw, ko, es, fr) |
default |
fractal.toolbarMode |
Toolbar display mode (full, simple) |
simple |
fractal.outlinerPageDir |
Default page directory for outliner | ./pages |
fractal.outlinerPageTitle |
Show page title input in outliner | false |
fractal.outlinerImageDefaultDir |
Default image directory for outliner nodes | ./images |
fractal.outlinerFileDir |
Default file attachment directory for outliner nodes | ./files |
fractal.fileDefaultDir |
Default directory for file attachments in markdown | "" (same as markdown file) |
fractal.forceRelativeFilePath |
Force relative paths for file attachments | false |
fractal.enableDebugLogging |
Enable debug logging in browser console | false |
fractal.showTranslateButtons |
Show translate buttons in standalone toolbar (leftmost) and side panel header. When off, translation can still be triggered via the fractal.translate command (Cmd+/) |
false |
Themes
All 7 themes apply to both the markdown editor and the outliner:
| Theme | Description |
|---|---|
github |
Clean GitHub-style rendering |
sepia |
Warm, paper-like appearance for comfortable reading |
night |
Dark theme with Tokyo Night inspired colors (blue tint) |
dark |
Pure dark theme with neutral black/gray colors |
minimal |
Distraction-free black and white design |
perplexity |
Light theme with Perplexity brand colors (Paper White background) |
things |
Clean, minimal theme inspired by Things app (SF Pro font, blue accents) (default) |
🌐 Supported Languages (i18n)
The editor UI supports the following languages:
| Language | Code |
|---|---|
| English | en (default) |
| Japanese | ja |
| Simplified Chinese | zh-cn |
| Traditional Chinese | zh-tw |
| Korean | ko |
| Spanish | es |
| French | fr |
Set via fractal.language or use default to follow VS Code's display language.
🔧 Commands
Available in Command Palette (Ctrl+Shift+P / Cmd+Shift+P):
| Command | Description |
|---|---|
Fractal: Open with Fractal |
Open markdown file in WYSIWYG editor |
Fractal: Insert Table |
Insert a new table |
Fractal: Insert TOC |
Insert table of contents |
Fractal: Open as Text |
Open in standard text editor |
Fractal: Compare as Text |
Compare with text version |
Fractal: Toggle Source Mode |
Switch between WYSIWYG and source mode |
Fractal: Undo |
Undo last edit |
Fractal: Redo |
Redo last undone edit |
Fractal: Clean Unused Files in Note |
Scan all notes for orphan images, markdown files, and file attachments. Move selected to trash |
Fractal: Clean Unused Files (Current Note) |
Same as above, limited to the currently open note |
🌐 Chrome Extension (Web Clipper)
Save any web page as a new top-level node in your Fractal Outliner — directly from Chrome, without launching VS Code.
- Located in
chrome-extension/of this repo (load as unpacked extension inchrome://extensions/). - Click the extension icon (or
Alt+Shift+F) on any web page → page is extracted with Mozilla Readability, converted to Markdown using Fractal's own HTML→MD pipeline (same logic as the MD editor'sCmd+Vpaste — supports tables, code blocks with<br>-style Medium / dev.to highlight, image-wrap link unwrap, GFM, etc.), and prepended as apageId-linked node to your selected.outfile. - Configure target Notes folder +
.outfile once via the extension's Options page (uses File System Access API — no VS Code communication needed; the file is updated directly on disk). - In-page banner shows clip progress / completion / errors (works even when OS notifications are disabled).
- Concurrent clicks across tabs are serialized in a queue to prevent
.outwrite conflicts.
See chrome-extension/README.md for installation and usage details.
🔄 External File Changes
When another tool (e.g., AI coding assistants like Claude Code, Cursor, etc.) modifies the same markdown file while you have it open in Fractal:
- Block-level DOM diff: Only changed blocks are updated — your cursor position and in-progress edits are preserved.
- Toast notification: A notification appears allowing you to review and accept or dismiss external changes.
- Unsaved changes warning: If you have unsaved edits, a confirmation dialog prevents accidental overwrites.
🛠️ Development
# Install dependencies
npm install
# Compile TypeScript
npm run compile
# Watch for changes
npm run watch
# Run tests
npm test
# Package extension
vsce package --no-dependencies
💖 Support This Project
If you find this extension useful, please consider:
- Sponsor on GitHub - Help keep this project maintained
- Star this repository on GitHub
- Report issues or suggest features on Issues
- Contribute with pull requests
Your support helps keep this project maintained and improved!
📄 License
MIT License - feel free to use this extension in your projects.
🙏 Acknowledgments
- Built with love for the VS Code community