Skip to main content
Get up and running with Opal Editor in just a few minutes. This guide will walk you through creating your first workspace, writing your first markdown document, and previewing your content.

​
Prerequisites

All you need is a modern web browser. Opal Editor runs entirely in your browser with no server required:
  • Chrome, Edge, Firefox, or Safari
  • No installation needed
  • No account required
  • 100% local-first and private

​
Create Your First Workspace

1

Visit Opal Editor

Go to opaledx.com in your browser.
2

Open the New Workspace dialog

Click the New Workspace button or press Cmd/Ctrl + N.
3

Configure your workspace

Choose your workspace settings:
  • Name: Give your workspace a descriptive name (e.g., “My Blog”, “Documentation”)
  • Template: Select from:
    • Hello World - Includes sample content and examples
    • Blank - Empty workspace for starting fresh
    • Basic - Simple starter template
  • File System: Choose your storage option:
    • OPFS (Origin Private File System) - Browser-managed storage, works everywhere
    • Native File System - Mount a local directory (Chrome/Edge only)
4

Create and initialize

Click Create Workspace and wait for initialization to complete. Opal Editor will:
  • Create the virtual filesystem
  • Initialize a Git repository
  • Set up the workspace structure
  • Load template files (if selected)
The first workspace creation may take a few seconds as Opal Editor initializes its service workers and storage systems.

​
Write Your First Document

Once your workspace is created, you’ll see the Opal Editor interface:

​
Interface Overview

  • Sidebar (left): File tree showing all your markdown files and folders
  • Editor (center): Rich text editor for writing content
  • Button bar (top): Editor controls and tools
  • Search (Cmd/Ctrl + K): Quick file navigation and workspace search

​
Create a New File

  1. Click the + button in the sidebar or press Cmd/Ctrl + Shift + N
  2. Enter a filename (e.g., my-first-post.md)
  3. Start writing in the rich text editor

​
Rich Text Editing

Opal Editor provides a WYSIWYG markdown editor powered by MDX-Editor:
  • Bold: Cmd/Ctrl + B
  • Italic: Cmd/Ctrl + I
  • Headings: Type # followed by space
  • Lists: Type - or 1. followed by space
  • Links: Cmd/Ctrl + K
  • Code blocks: Type ``` and select language

​
Toggle to Source Mode

Press Cmd/Ctrl + ; to switch between rich text and raw markdown editing. In source mode, you get:
  • Full CodeMirror editor with syntax highlighting
  • Vim keybindings (optional)
  • Direct markdown control
  • Line numbers and code folding

​
Supported File Types

Opal Editor supports editing multiple file types:
  • .md / .mdx - Markdown documents
  • .html - HTML files
  • .css - Stylesheets
  • .js / .ts - JavaScript/TypeScript
  • .json - JSON data
  • .yaml / .yml - YAML configuration
  • .ejs - EJS templates
  • And more…

​
Preview Your Content

1

Open Live Preview

Click the Live Preview button in the top-right corner or press Cmd/Ctrl + Shift + P.
2

View your rendered content

The preview pane shows your markdown rendered as HTML with:
  • GitHub-flavored markdown rendering
  • Syntax-highlighted code blocks
  • Rendered images
  • Live updates as you type
3

Navigate and interact

  • Click links to navigate between pages
  • Scroll independently from the editor
  • Refresh to see latest changes
The live preview updates automatically as you edit, showing your content exactly as it will appear when published.

​
Upload Images

Add images to your workspace in two ways:

​
Drag and Drop

  1. Drag an image file from your computer
  2. Drop it onto the editor or sidebar
  3. Opal Editor will:
    • Store the image in your workspace
    • Automatically convert to WebP for smaller file size
    • Insert markdown reference: ![alt text](/image.webp)

​
Upload via Sidebar

  1. Click the Upload button in the sidebar
  2. Select image files
  3. Images are optimized and added to your workspace
Opal Editor automatically converts images to WebP format for optimal file size while maintaining quality.

​
Keyboard Shortcuts

Common shortcuts to speed up your workflow:
ActionShortcut
New workspaceCmd/Ctrl + N
New fileCmd/Ctrl + Shift + N
Quick searchCmd/Ctrl + K
Save fileCmd/Ctrl + S
Toggle source modeCmd/Ctrl + ;
Live previewCmd/Ctrl + Shift + P
Bold textCmd/Ctrl + B
Italic textCmd/Ctrl + I
Insert linkCmd/Ctrl + K

​
Next Steps

Now that you’ve created your first workspace and written some content, explore more features:

Publish Your Site

Deploy to Netlify, Vercel, Cloudflare Pages, GitHub Pages, or S3

Git Integration

Commit changes, create branches, and push to GitHub

Templates

Use template engines to build static sites

Advanced Features

Learn about storage, service workers, and optimization

​
Troubleshooting

​
Workspace won’t create

  • Check browser compatibility: Use Chrome, Edge, Firefox, or Safari
  • Clear browser cache: Sometimes helps with service worker issues
  • Try a different storage option: Switch between OPFS and Native File System

​
Files not saving

  • Check storage quota: Browser may have limited available space
  • Service worker issues: Refresh the page to reload service workers
  • Network errors: Ensure you’re not blocking service workers in browser settings

​
Preview not updating

  • Refresh preview: Click refresh button in preview pane
  • Check file syntax: Invalid markdown may prevent rendering
  • Service worker cache: Hard refresh with Cmd/Ctrl + Shift + R
If you encounter persistent issues, try opening Opal Editor in an incognito/private window to rule out extension conflicts.

Build docs developers (and LLMs) love

Get started for freeTalk to us