Workspace Setup

A workspace in Lokus is a folder on your computer that contains all your notes, attachments, and configuration. Understanding workspaces is key to organizing your knowledge effectively.

What is a Workspace?

A workspace is simply a directory on your filesystem that Lokus uses to store your notes. Each workspace is completely independent, allowing you to:

Separate contexts: Keep work notes separate from personal notes
Maintain privacy: Store sensitive notes in encrypted volumes
Organize projects: Create dedicated workspaces for different projects
Sync selectively: Sync only specific workspaces to cloud storage

All notes are stored as plain Markdown (.md) files, making them portable and future-proof. You can open and edit them with any text editor.

Workspace Structure

A typical workspace looks like this:

my-workspace/
├── .lokus/                 # Lokus configuration and metadata
│   ├── config.json        # Workspace settings
│   ├── graph.json         # Graph data cache
│   └── index.db           # Search index
├── .templates/            # Note templates
├── assets/                # Images and attachments
├── daily/                 # Daily notes
├── projects/              # Project notes
├── areas/                 # Areas of responsibility
└── resources/             # Reference materials

The .lokus folder contains workspace-specific settings and cached data. You can safely add it to .gitignore if versioning your notes.

Creating a New Workspace

Choose Your Location

Decide where to store your workspace:

Local storage: ~/Documents/Lokus/ for general notes
Cloud sync: ~/Dropbox/Notes/ or ~/iCloud/Notes/ for automatic backup
Encrypted volume: For sensitive information
Git repository: For version-controlled notes

Create the Workspace

Click the workspace selector in the top bar
Select New Workspace
Choose a location and name
Click Create

Lokus will initialize the workspace with default folders and configuration.

Initial Configuration

After creating a workspace, configure these essential settings:

Workspace Name: Give it a descriptive name in Settings → Workspace
Default Folder: Set where new notes are created by default
Templates Location: Specify where templates are stored (default: .templates/)
Assets Location: Choose where attachments are saved (default: assets/)

Managing Multiple Workspaces

Switching Workspaces

Lokus makes it easy to work with multiple workspaces:

Click the workspace selector in the top bar
Select from your recent workspaces
Or choose Open Workspace to browse for a different one

Use keyboard shortcut Cmd+Shift+O (Mac) or Ctrl+Shift+O (Windows/Linux) to quickly switch workspaces.

Recent Workspaces

Lokus remembers your recently used workspaces:

Access them from the workspace selector dropdown
Pin frequently used workspaces to keep them at the top
Remove workspaces from the list via right-click → Remove from Recent

Removing a workspace from recent workspaces does not delete any files. It only removes it from the quick access list.

Workspace Session State

Lokus automatically saves your session state for each workspace:

Open files: Your open tabs are restored when you return
Cursor position: Resume exactly where you left off
Sidebar state: Expanded folders and scroll position are preserved
Graph view state: Your graph view position and zoom level

This makes it seamless to switch between different projects and contexts.

Workspace Settings

General Settings

Configure workspace-wide preferences in Settings → Workspace:

{
  "name": "My Workspace",
  "defaultLocation": "inbox",
  "templatesFolder": ".templates",
  "attachmentsFolder": "assets",
  "autoSave": true,
  "autoSaveInterval": 2000
}

Name: Display name for the workspace
Default Location: Where new notes are created
Templates Folder: Location of note templates
Attachments Folder: Where pasted images and files are stored
Auto Save: Enable automatic saving (recommended)
Auto Save Interval: Delay in milliseconds before saving

Editor Preferences

Each workspace can have unique editor preferences:

Font Family: Different fonts for different contexts (e.g., monospace for code notes)
Font Size: Adjust for different displays
Line Width: Narrower for reading, wider for editing
Spell Check: Enable for writing-focused workspaces

File Handling

Configure how Lokus handles files in your workspace:

File Naming: Choose between kebab-case, snake_case, or Title Case
New Note Template: Default content for new notes
Confirm Delete: Require confirmation before deleting notes
Trash Location: Use system trash or workspace .trash folder

Sync and Backup

Lokus works seamlessly with various sync solutions:

Dropbox Sync

Create your workspace inside your Dropbox folder
Dropbox automatically syncs changes across devices
Access version history through Dropbox’s web interface

Recommended location: ~/Dropbox/Lokus/workspace-name/

iCloud Drive

Create workspace in ~/Library/Mobile Documents/com~apple~CloudDocs/
iCloud syncs automatically on macOS and iOS
Access notes on mobile devices with compatible apps

Note: iCloud sync can be slower than Dropbox or Git

Git Version Control

Initialize a Git repository in your workspace:

cd /path/to/workspace
git init
 
# Add .gitignore
echo ".lokus/" >> .gitignore
echo ".DS_Store" >> .gitignore
 
git add .
git commit -m "Initial commit"

Benefits:

Full version history
Branch different versions of notes
Collaborate with others
Push to GitHub/GitLab for backup

Syncthing

Set up Syncthing on your devices
Add your workspace folder to Syncthing
Configure sync settings:
- Enable ignore patterns for .lokus/ if needed
- Use versioning for backup

Syncthing provides local, peer-to-peer sync without cloud services.

⚠️

Conflict Resolution: When syncing, be careful about editing the same note on multiple devices simultaneously. Most sync services create conflict files that you’ll need to merge manually.

File Organization Best Practices

Folder Structure

Design a folder structure that matches how you think:

Option 1: PARA Method

workspace/
├── projects/        # Active projects with deadlines
├── areas/           # Ongoing responsibilities
├── resources/       # Reference materials
└── archives/        # Completed items

Option 2: Zettelkasten

workspace/
├── fleeting/        # Quick captures
├── literature/      # Notes from reading
├── permanent/       # Refined, atomic notes
└── index/           # Structure notes and maps

Option 3: Simple Categories

workspace/
├── work/
├── personal/
├── learning/
└── projects/

Choose a structure that feels natural to you. You can always reorganize later, and wiki links will remain intact even if you move files.

Naming Conventions

Consistent naming makes notes easier to find:

Date-based: 2025-09-29-meeting-notes.md

Good for: Daily notes, meeting notes, journal entries
Sorts chronologically
Easy to find by date

Descriptive titles: getting-started-with-react-hooks.md

Good for: Evergreen notes, tutorials, reference materials
Searchable by content
Easy to link with wiki links

ID-based: 202509291430-meeting-notes.md (Zettelkasten style)

Good for: Large collections of interconnected notes
Unique identifiers prevent naming conflicts
Timestamp preserves creation context

Tags and Metadata

Use frontmatter to add metadata to your notes:

---
title: Getting Started with Lokus
tags: [documentation, tutorial, beginner]
created: 2025-09-29
modified: 2025-09-29
author: Your Name
status: draft
---
 
# Note content starts here

Benefits of metadata:

Filter searches: Find all notes with specific tags
Track status: Know which notes are drafts, published, or archived
Sort by date: See your most recent work
Add context: Remember when and why you created a note

Advanced Workspace Configuration

Custom Configuration File

Advanced users can directly edit .lokus/config.json:

{
  "workspace": {
    "name": "My Workspace",
    "version": "1.0.0",
    "settings": {
      "defaultLocation": "inbox",
      "templatesFolder": ".templates",
      "attachmentsFolder": "assets",
      "dailyNotesFolder": "daily",
      "dailyNoteFormat": "YYYY-MM-DD"
    },
    "editor": {
      "fontFamily": "iA Writer Quattro",
      "fontSize": 16,
      "lineHeight": 1.6,
      "maxLineWidth": 750,
      "spellCheck": true,
      "typewriterMode": false,
      "focusMode": false
    },
    "behavior": {
      "autoSave": true,
      "autoSaveInterval": 2000,
      "confirmDelete": true,
      "openLinksInNewTab": false,
      "createNonExistentLinks": true
    }
  }
}

Workspace Templates

Create a template workspace to quickly set up new projects:

Create a workspace with your ideal structure
Add template notes and folders
Configure settings
Save it as a template location
Copy this workspace whenever starting a new project

Shared Workspaces

Collaborate with others using shared workspaces:

Via Git:

# Clone a shared repository
git clone https://github.com/team/shared-notes.git
 
# Open in Lokus
# Edit notes as usual
# Commit and push changes
 
git add .
git commit -m "Add meeting notes"
git push

Via Network Drive:

Place workspace on a shared network drive
Multiple users can access (avoid simultaneous edits)
Use file locking if available

⚠️

Concurrent Editing: Lokus is designed for single-user operation. Simultaneous editing by multiple users can cause conflicts. Use Git for version-controlled collaboration.

Encrypted Workspaces

Protect sensitive notes with encryption:

Option 1: System Encryption

macOS: Create an encrypted disk image with Disk Utility
Windows: Use BitLocker or VeraCrypt
Linux: Use LUKS encryption

Option 2: Encrypted Container

Use VeraCrypt to create an encrypted container
Mount the container when needed
Open workspace inside mounted volume

Option 3: Encrypted Cloud Storage

Use Cryptomator with Dropbox/iCloud
Create workspace inside encrypted vault
Automatic encryption on sync

Troubleshooting

Workspace Won’t Open

If a workspace fails to open:

Check folder permissions (must be readable/writable)
Verify .lokus folder exists and isn’t corrupted
Try opening from File menu instead of recent list
Check available disk space

Missing Notes or Files

If notes are missing:

Verify you’re in the correct workspace
Check the folder structure in Finder/Explorer
Use full-text search to locate the note
Check sync service for conflict files
Restore from backup if necessary

Sync Conflicts

When sync services create conflicts:

Look for files named file.md (conflicted copy)
Open both versions side by side
Manually merge changes
Delete the conflict file after merging

Performance Issues

If Lokus is slow with large workspaces:

Rebuild search index: Settings → Advanced → Rebuild Index
Exclude large folders from indexing
Archive old notes to a separate workspace
Check for very large individual files (>10MB)

Next Steps

Now that you understand workspaces, explore these topics:

Markdown Reference - Master Markdown syntax
Templates & Automation - Streamline your workflow
Graph View - Visualize your knowledge network
Keyboard Shortcuts - Work more efficiently

Start with one workspace: Don’t over-complicate things initially. Most users find that one well-organized workspace is sufficient. Add more workspaces only when you have a clear need for separation.

Quick Start Overview