Desktop Editing Workflow - XLog doesn’t provide browser-based editing. Instead, clicking “Edit” opens the file in your configured text editor (Vim, VS Code, Emacs, etc.). You edit locally, save the file, and see changes instantly in your browser.
docs
Usage| modified | Saturday 9 May 2026 |
|---|
XLog provides a live preview server for writing and a static site generator for deployment. This guide covers common usage patterns and command-line options.
The most common way to use XLog is with the live preview server:
1cd my-notes
2xlog
3# => Server running at http://localhost:3000
This starts a web server that:
Desktop Editing Workflow - XLog doesn’t provide browser-based editing. Instead, clicking “Edit” opens the file in your configured text editor (Vim, VS Code, Emacs, etc.). You edit locally, save the file, and see changes instantly in your browser.
To deploy your knowledge base as static HTML:
1xlog -build ./output
2# => Static site generated in ./output directory
This creates a complete static website you can deploy to:
-editor - Set Your Text Editor ¶Specify which editor opens when you click “Edit”:
1# Use VS Code
2xlog -editor "code"
3
4# Use Vim
5xlog -editor "vim"
6
7# Use Emacs
8xlog -editor "emacs"
9
10# Use Sublime Text
11xlog -editor "subl -w"
If not specified, XLog uses the $EDITOR environment variable. Set it in your shell config:
1export EDITOR="vim" # Add to ~/.bashrc or ~/.zshrc
Examples for different editors:
| Editor | Command |
|---|---|
| VS Code | code or code --wait |
| Vim | vim |
| Emacs | emacs or emacsclient -n -a emacs |
| Sublime Text | subl -w |
| Nano | nano |
| Notepad++ (Windows) | notepad++ |
-bind - Change Server Address ¶By default, XLog binds to 127.0.0.1:3000. Change it with:
1# Use port 8080
2xlog -bind :8080
3
4# Bind to all interfaces (accessible from network)
5xlog -bind 0.0.0.0:3000
Security Note - Binding to 0.0.0.0 makes XLog accessible from your network. Only use this on trusted networks or with proper authentication.
-source - Specify Content Directory ¶By default, XLog uses the current directory. Change it with:
1xlog -source ~/my-knowledge-base
-build - Generate Static Site ¶Create a static HTML version for deployment:
1# Build to ./public directory
2xlog -build ./public
3
4# Build to custom location
5xlog -build ~/sites/my-wiki
-sitename - Set Site Name ¶Appears in the header and title tags:
1xlog -sitename "My Knowledge Base"
-theme - Choose Color Theme ¶1# Light theme
2xlog -theme light
3
4# Dark theme
5xlog -theme dark
6
7# System preference (default)
8xlog -theme ""
-index - Set Homepage File ¶Default is index.md. Change it with:
1xlog -index "home" # Uses home.md as homepage
-notfoundpage - Custom 404 Page ¶1xlog -notfoundpage "custom-404" # Uses custom-404.md for 404 errors
-html - Include HTML Files ¶By default, XLog only processes markdown (.md) files. Enable HTML:
1xlog -html
-pandoc - Use Pandoc for Additional Formats ¶Render .org, .rst, .rtf, .odt files using Pandoc:
1xlog -pandoc
Requires Pandoc to be installed.
-codestyle - Syntax Highlighting Theme ¶Change code block syntax highlighting:
1xlog -codestyle monokai
2xlog -codestyle github
3xlog -codestyle dracula # default
See Chroma styles for available themes.
-disabled-extensions - Disable Extensions ¶Disable specific extensions by name (comma-separated):
1xlog -disabled-extensions "photos,videos,backlinks"
See Extensions for available extension names.
-readonly - Read-Only Mode ¶Disable all write operations (editing, deleting, creating):
1xlog -readonly
Useful for public deployments where you only want to display content.
-serve-insecure - Accept HTTP Connections ¶By default, XLog expects HTTPS for CSRF protection. Allow HTTP:
1xlog -serve-insecure
Only use this for local development. Production deployments should use HTTPS.
-gpg - Encrypt Pages with GPG ¶Encrypt/decrypt .md.pgp files using GPG:
1xlog -gpg "YOUR_KEY_ID"
-custom.head - Inject Custom HTML ¶Include custom HTML in the <head> tag of every page:
1xlog -custom.head ./custom-head.html
-custom.before_view - Content Before Page ¶Include custom HTML before page content:
1xlog -custom.before_view ./header.html
-custom.after_view - Content After Page ¶Include custom HTML after page content:
1xlog -custom.after_view ./footer.html
Enable “Edit on GitHub” buttons:
1xlog -github.url "https://github.com/username/repo/edit/master/docs"
1# Set RSS domain (without https://)
2xlog -rss.domain "example.com"
3
4# Set RSS description
5xlog -rss.description "My knowledge base feed"
6
7# Limit feed items
8xlog -rss.limit 50 # default: 30
1# Set domain for og:* and twitter:* meta tags
2xlog -og.domain "example.com"
For Fediverse/Mastodon integration:
1xlog -activitypub.username "yourusername" \
2 -activitypub.domain "example.com" \
3 -activitypub.summary "My knowledge base" \
4 -activitypub.icon "/public/avatar.png" \
5 -activitypub.image "/public/cover.png"
1xlog -disqus "your-disqus-domain.disqus.com"
Enable GitHub Discussions-powered comments:
1xlog -giscus-repo "owner/repo" \
2 -giscus-repo-id "R_kgDOG1234" \
3 -giscus-category "Announcements" \
4 -giscus-category-id "DIC_kwDOG5678"
Get configuration values from giscus.app. Optional flags:
-giscus-mapping - Mapping method (default: pathname)-giscus-theme - Visual theme (default: preferred_color_scheme)-giscus-lang - Interface language (default: en)1xlog -twitter.username "@yourhandle"
-sitemap.domain - Sitemap Generation ¶1xlog -sitemap.domain "example.com"
-csrf-cookie - CSRF Cookie Name ¶1xlog -csrf-cookie "custom_csrf" # default: "xlog_csrf"
-sql-table.threshold - SQL Query Threshold ¶Enable SQL queries on tables with more than N rows:
1xlog -sql-table.threshold 100 # default
Start XLog server:
1xlog
Open browser to http://localhost:3000
Click “Edit” on any page (opens in your configured editor)
Edit the markdown file and save
Browser automatically reloads with changes
See Workflow Guide for detailed explanation.
Write and preview locally:
1xlog
Generate static site:
1xlog -build ./public
Deploy ./public directory to your hosting service
Run multiple XLog instances on different ports:
1# Personal wiki on port 3000
2xlog -source ~/wiki -bind :3000 &
3
4# Work notes on port 3001
5xlog -source ~/work-notes -bind :3001 &
6
7# Learning journal on port 3002
8xlog -source ~/learning -bind :3002 &
XLog watches your markdown files for changes. When you save a file in your editor:
This happens in milliseconds, creating a seamless writing experience.
XLog doesn’t use configuration files. All settings are command-line flags. For convenience, create shell aliases or scripts:
1# Add to ~/.bashrc or ~/.zshrc
2alias my-wiki='xlog -source ~/wiki -editor "code" -sitename "My Wiki"'
3alias work-notes='xlog -source ~/work -editor "vim" -sitename "Work Notes"'
XLog respects these environment variables:
EDITOR - Default editor (used if -editor not specified)PORT - Server port (overridden by -bind)Check your editor configuration:
1# Test if editor command works
2code test.md # or vim test.md, emacs test.md, etc.
3
4# Set editor explicitly
5xlog -editor "code"
Change the port:
1xlog -bind :3001
For the complete list of flags, run:
1xlog -help