modified	Saturday 9 May 2026

Edited: Saturday 9 May 2026

XLog Workflow Guide ¶

This guide explains how XLog works and how to integrate it into your daily workflow.

Understanding the XLog Workflow ¶

XLog follows a desktop-first editing workflow that integrates with your existing text editor. Here’s what makes it unique:

┌─────────────────────────────────────────────────────────┐
│  Your Text Editor (Vim, VS Code, Emacs, etc)          │
│  ↓ Edit & Save                                          │
│  Markdown Files (Filesystem)                            │
│  ↓ XLog watches for changes                             │
│  XLog Server (Live Preview)                             │
│  ↓ Hot-reload                                            │
│  Browser (Instant Preview)                              │
└─────────────────────────────────────────────────────────┘

Key Insight: XLog doesn’t replace your editor—it enhances it with live preview and knowledge-base features.

How Editing Works ¶

The “Edit” Button ¶

When you click the “Edit” button in your browser:

XLog sends a command to open the file
Your configured editor launches with the file open
You edit in your editor (not in the browser)
You save the file (Ctrl+S or :w)
XLog detects the change and reloads the browser

Important: There is NO in-browser editing. This is intentional—your editor is more powerful than any web-based solution.

Configuring Your Editor ¶

XLog uses the -editor flag or $EDITOR environment variable to know which editor to open.

Default behavior:

1xlog  # Uses $EDITOR if set, otherwise tries common editors

Specify editor explicitly:

1xlog -editor "code"           # VS Code
2xlog -editor "vim"            # Vim
3xlog -editor "emacs"          # Emacs
4xlog -editor "subl -w"        # Sublime Text (wait for close)
5xlog -editor "code --wait"    # VS Code (wait for close)

Set permanently in shell:

1# Add to ~/.bashrc or ~/.zshrc
2export EDITOR="code --wait"

Editor-Specific Setup ¶

VS Code ¶

1# Option 1: Set globally
2export EDITOR="code --wait"
3
4# Option 2: Pass flag
5xlog -editor "code --wait"

Recommended VS Code extensions:

Markdown All in One
Markdown Preview Enhanced
markdownlint

Vim ¶

1# Already works if $EDITOR is set
2export EDITOR="vim"
3
4# Or use Neovim
5export EDITOR="nvim"

Recommended Vim plugins:

vim-markdown
goyo.vim (distraction-free)
vimwiki (if you want Vim-based wiki too)

Emacs ¶

1# Use emacsclient for faster startup
2export EDITOR="emacsclient -n -a emacs"
3
4# This is XLog's default if no $EDITOR is set

Recommended Emacs packages:

markdown-mode
org-mode (for mixed workflows)

Sublime Text ¶

1export EDITOR="subl -w"  # -w waits for file close

Other Editors ¶

Atom:

1export EDITOR="atom --wait"

Nano:

1export EDITOR="nano"

Custom GUI editor:

1# Replace with your editor's command
2export EDITOR="/path/to/editor"

Daily Workflow Examples ¶

Workflow 1: Quick Note Taking ¶

 1# Terminal 1: Start XLog
 2cd ~/notes
 3xlog
 4
 5# Terminal 2: Create new note
 6echo "# Meeting Notes - 2026-05-07" > meetings/daily-standup.md
 7
 8# Browser: Navigate to http://localhost:3000/meetings/daily-standup
 9# Click "Edit" → Editor opens → Add content → Save
10# Browser auto-refreshes with changes

Workflow 2: Research Journal ¶

 1# Organize by topic with hashtags
 2# In your editor, create: research/quantum-computing.md
 3
 4---
 5# Quantum Computing Basics
 6
 7#physics #computing #research
 8
 9Quantum computers use qubits instead of bits...
10
11Related: [classical-computing](/classical-computing) [quantum-entanglement](/quantum-entanglement)
12---
13
14# XLog automatically:
15# - Creates backlinks from referenced pages
16# - Indexes hashtags for browsing
17# - Adds to search index

Workflow 3: Documentation Site ¶

 1# Project structure
 2my-docs/
 3  index.md           # Homepage
 4  getting-started.md
 5  api/
 6    authentication.md
 7    endpoints.md
 8  public/
 9    logo.png
10    diagrams/
11
12# Develop with live preview
13xlog
14
15# Deploy as static site
16xlog -build output/
17# Upload output/ to GitHub Pages, Netlify, etc

Hot-Reload Explained ¶

XLog watches your filesystem for changes and automatically refreshes your browser. Here’s what triggers a reload:

Triggers hot-reload:

Saving a markdown file
Creating a new file
Deleting a file
Renaming a file (via file operations extension)
Uploading an image

Does NOT trigger reload:

Cursor movement in editor
Unsaved changes
Changes to non-markdown files (unless configured)

How it works:

XLog uses filesystem watchers (inotify on Linux)
When a file changes, XLog invalidates caches
XLog sends reload signal to browser via WebSocket
Browser requests fresh page content
You see updated content instantly

Performance tip: XLog only watches markdown files by default. If you have thousands of files, this stays fast.

Git Integration ¶

XLog is Git-native, meaning it works perfectly with version control.

Basic Git Workflow ¶

 1# Initialize Git in your notes directory
 2cd ~/notes
 3git init
 4
 5# XLog ignores .git automatically
 6xlog
 7
 8# Add and commit as you write
 9git add .
10git commit -m "Add quantum computing notes"
11
12# Push to remote backup
13git remote add origin git@github.com:yourname/notes.git
14git push -u origin main

Advanced: Auto-Commit on Save ¶

You can create a script that auto-commits after edits:

1#!/bin/bash
2# save-and-commit.sh
3
4# Watch for changes and auto-commit
5while inotifywait -r -e modify,create,delete ~/notes; do
6    cd ~/notes
7    git add .
8    git commit -m "Auto-commit: $(date)"
9done

Note: Auto-commit is optional. Many users prefer manual commits for meaningful messages.

Branch-Based Drafts ¶

1# Create draft branch
2git checkout -b drafts
3
4# XLog shows same content, just different Git branch
5xlog
6
7# Publish by merging to main
8git checkout main
9git merge drafts

Multi-Device Sync ¶

Option 1: Git + Remote Repo ¶

 1# Device 1: Push changes
 2cd ~/notes
 3git add .
 4git commit -m "Update notes"
 5git push
 6
 7# Device 2: Pull changes
 8cd ~/notes
 9git pull
10# XLog automatically detects changes and reloads

Option 2: Obsidian + XLog ¶

Many users use Obsidian for mobile editing and XLog for publishing:

1# Point XLog to Obsidian vault
2xlog -source ~/Obsidian/MyVault
3
4# Edit in Obsidian on phone/tablet
5# XLog picks up changes automatically
6# Publish static site from XLog

Option 3: Syncthing / Dropbox ¶

1# Sync folder across devices
2# XLog watches for filesystem changes
3# Works with any sync solution

Troubleshooting ¶

Editor Doesn’t Open ¶

Problem: Clicking “Edit” does nothing

Solutions:

Check if editor is in PATH: which code or which vim
Set editor explicitly: xlog -editor "vim"
Check XLog logs for errors
Verify file permissions

Changes Don’t Reload ¶

Problem: Saved file but browser doesn’t update

Solutions:

Check browser console for WebSocket errors
Refresh browser manually (Ctrl+R)
Restart XLog server
Check file was actually saved (some editors delay writes)

Permission Errors ¶

Problem: Can’t edit files

Solutions:

Check file ownership: ls -la
Fix permissions: chmod 644 *.md
Ensure XLog has write access to directory

Best Practices ¶

Organization ¶

Use clear folder structure:

notes/
  index.md              # Homepage
  daily/                # Daily notes
  projects/             # Project-specific notes
  reference/            # Reference material
  public/               # Images, assets

Use frontmatter for metadata:

1---
2title: My Research Paper
3tags: [research, physics]
4date: 2026-05-07
5---

Linking ¶

Use descriptive page names:

✅ [quantum-computing-basics](/quantum-computing-basics)
❌ [qc1](/qc1)

Create hub pages:

Topic overview pages that link to related notes
XLog shows backlinks automatically

Performance ¶

For large knowledge bases (1000+ pages):

Split into subdirectories by topic
Use .gitignore for files you don’t need in Git
Run xlog -readonly if you don’t need editing

Summary ¶

XLog workflow = Your Editor + Live Preview + Git

✅ Edit in your powerful desktop editor
✅ See changes instantly in browser
✅ Version control with Git
✅ No lock-in (just markdown files)
✅ Works offline

Not:

❌ Browser-based editing
❌ Cloud storage required
❌ Proprietary format
❌ Database required

This workflow gives you the best of both worlds: powerful editing tools and modern preview experience.

Next Steps ¶

Installation Guide
Extensions
[Creating a Static Site](/tutorials/Creating a site)
GitHub Discussions

XLog Workflow Guide ¶

Understanding the XLog Workflow ¶

How Editing Works ¶

The “Edit” Button ¶

Configuring Your Editor ¶

Editor-Specific Setup ¶

VS Code ¶

Vim ¶

Emacs ¶

Sublime Text ¶

Other Editors ¶

Daily Workflow Examples ¶

Workflow 1: Quick Note Taking ¶

Workflow 2: Research Journal ¶

Workflow 3: Documentation Site ¶

Hot-Reload Explained ¶

Git Integration ¶

Basic Git Workflow ¶

Advanced: Auto-Commit on Save ¶

Branch-Based Drafts ¶

Multi-Device Sync ¶

Option 1: Git + Remote Repo ¶

Option 2: Obsidian + XLog ¶

Option 3: Syncthing / Dropbox ¶

Troubleshooting ¶

Editor Doesn’t Open ¶

Changes Don’t Reload ¶

Permission Errors ¶

Best Practices ¶

Organization ¶

Linking ¶

Performance ¶

Summary ¶

Next Steps ¶

Backlinks