Skip to main content
Workspaces are self-contained environments where you create, edit, and manage your markdown content. Each workspace has its own file tree, git repository, and configuration.

​
What is a Workspace?

A workspace in Opal is a complete project environment that includes:
  • File system: Directory structure with markdown files, images, and assets
  • Git repository: Integrated version control (optional)
  • Build configuration: Settings for static site generation
  • Storage: Local browser storage or native file system access
  • Edit history: Automatic tracking of content changes
  • Thumbnails: Cached image previews

​
Creating a Workspace

You can create a workspace in multiple ways:
Create an empty workspace with default files:
1

Choose Create New

From the home screen, click Create New Workspace
2

Name your workspace

Enter a unique name (automatically slugified)
3

Select storage type

Choose between browser storage or native file system
4

Start editing

Your workspace is created with a default index.md file

​
Storage Options

Opal supports two storage backends:
Origin Private File System storage runs entirely in your browser:
  • No installation required
  • Works offline
  • Isolated per browser/origin
  • Fast read/write performance
  • Data persists across sessions
  • Cannot access from other applications
Browser storage can be cleared if you clear site data. Export important work regularly.
File System Access API connects to a folder on your computer:
  • Files stored on your local disk
  • Access from other applications
  • Survives browser cache clearing
  • Requires permission grant on each session
  • Works with existing git repositories
  • Changes sync to disk immediately
Native file system access requires a modern browser with File System Access API support (Chrome, Edge)

​
Managing Files

​
File Tree Operations

The file tree sidebar provides full file management:
  • Create: Right-click to add new files or folders
  • Rename: Right-click and select Rename or press F2
  • Move: Drag and drop files between folders
  • Delete: Move files to trash with right-click or Delete key
  • Duplicate: Right-click and select Duplicate
  • Copy/Paste: Copy files and paste in different locations

​
Trash System

Deleted files are moved to a .trash folder:
1

Delete a file

Right-click a file and select Move to Trash
2

Review trash

Find deleted items in the .trash folder in your file tree
3

Restore or delete

Right-click trashed items to Restore or Delete Permanently
Files in trash are excluded from builds and git operations until permanently deleted

​
Workspace Settings

Each workspace can be configured independently:

​
Build Strategy

Choose how your workspace content is built:
  • Freeform: No build step, files are published as-is
  • Static Site: Generate a static site from markdown and templates

​
File Uploads

Opal supports multiple upload formats:
  • Markdown: .md, .mdx files
  • Images: JPEG, PNG, GIF, WebP, SVG (auto-optimized)
  • Documents: .docx files (converted to markdown)
  • Assets: CSS, JavaScript, JSON, HTML files
When you upload .docx files, Opal automatically:
  1. Extracts text content and formatting
  2. Converts to markdown syntax
  3. Preserves headings, lists, and basic formatting
  4. Extracts embedded images
  5. Creates a .md file in your workspace
Complex formatting may not convert perfectly. Review converted files for accuracy.

​
Multi-Workspace Management

You can create and manage multiple workspaces:
  • Switch between workspaces from the home screen
  • Each workspace is completely isolated
  • Workspaces can have different storage backends
  • Git repositories are per-workspace
  • Import/export workspaces independently

​
Workspace Metadata

Each workspace stores:
  • Name: Unique identifier (slugified)
  • GUID: Internal unique ID
  • Created timestamp: When the workspace was created
  • Build configuration: Build strategy and settings
  • Remote connections: Git remotes and deploy destinations

​
Performance Considerations

For best performance with large workspaces (1000+ files):
  • Use native file system storage when possible
  • Optimize images before uploading
  • Keep trash folder empty
  • Limit the number of active workspaces

​
Exporting and Backup

Protect your work by exporting workspaces:
  1. Git sync: Push to GitHub regularly (recommended)
  2. Manual download: Download workspace as ZIP
  3. Native storage: Files are already on disk if using native file system
Browser storage is not automatically backed up. Use git integration for reliable backups.

​
Deleting Workspaces

To remove a workspace:
1

Navigate to workspace list

Go to the home screen showing all workspaces
2

Delete workspace

Right-click the workspace and select Delete
3

Confirm deletion

Confirm that you want to permanently delete the workspace
Deleting a workspace is permanent and cannot be undone. Export or push to git before deleting.

Build docs developers (and LLMs) love

Get started for freeTalk to us