Skip to main content
Start a local development server to preview generated HTML entries over http://localhost.

​
Usage

dex view [--open|--no-open] [--port <number>] [--root <path>]

​
Flags

​
—open / —no-open

Control whether to automatically open the viewer in your default browser. 
dex view --open       # Auto-open browser (default)
dex view --no-open    # Start server without opening browser
Default: --open (browser opens automatically)

​
—port

Specify the HTTP server port. 
dex view --port 8080
Default: 4173 If the default port is unavailable, the viewer automatically tries the next 30 ports.

​
—root

Specify a custom root directory for HTML files. 
dex view --root ./entries
Default: Auto-discovers entries/ directory in the current workspace.

​
Features

​
File picker interface

The viewer landing page displays:
  • Recent files - Previously opened HTML files (with “Clear recents” button)
  • Output files - All HTML files discovered in allowed output directories

​
URL rewriting

The viewer rewrites production URLs in HTML to local paths:
  • https://dexdsl.github.io/assets/ → /assets/
  • https://dexdsl.org/css/ → /css/
  • https://dexdsl.com/static/ → /static/
This ensures local preview works without external dependencies.

​
Static asset serving

The viewer serves local assets from:
  • /assets/ → public/assets/, assets/, or docs/assets/
  • /css/ → public/css/, css/, or docs/css/
  • /static/ → public/static/, static/, or docs/static/
  • /data/ → public/data/, data/, or docs/data/

​
Recent files tracking

Recent files are stored in ~/.config/dexdsl/recents.json and automatically pruned to the 250 most recent entries.

​
API endpoints

The viewer exposes internal JSON endpoints:
  • GET /api/recent - List recent HTML files
  • POST /api/recent/clear - Clear recent files history
  • GET /api/list - List all HTML files in allowed roots

​
View routes

​
Landing page

GET /
Displays the file picker interface with recent and root files.

​
View file

GET /view/<base64-file-id>/
Opens the specified HTML file in the viewer. The file ID is base64url-encoded from the absolute file path.

​
Relative assets

GET /view/<base64-file-id>/<relative-path>
Serves relative assets (images, CSS, JS) referenced by the HTML file.

​
Security model

The viewer enforces path safety:
  • Only serves files within allowed roots or recent files list
  • Blocks path traversal attempts (../)
  • Rejects absolute paths in relative asset requests
  • HTML files must have .html extension

​
Examples

​
Start viewer with default settings

dex view
Server starts on port 4173 and opens http://localhost:4173/ in your browser.

​
Start viewer without opening browser

dex view --no-open
Server starts but browser is not launched. Manually visit http://localhost:4173/.

​
Use custom port

dex view --port 8080
Server runs on port 8080.

​
Specify custom root directory

dex view --root ./entries
Viewer discovers HTML files only in ./entries/.

​
Allowed output directories

By default, the viewer auto-discovers HTML files in:
  • entries/ (site repo)
  • Any directory specified with --root
Files outside these roots are not accessible unless they appear in recent files.

​
Troubleshooting

​
Port already in use

The viewer automatically tries the next 30 ports starting from the requested port. If all ports are occupied: 
dex view --port 5000

​
Assets not loading

Verify local asset directories exist: 
ls public/assets
ls public/css
The viewer searches multiple fallback paths for each asset type.

​
File not appearing in picker

Ensure the file:
  • Has .html extension
  • Is inside an allowed output directory (entries/ or --root)
  • Is not in a hidden directory (starts with .)

​
Viewer chrome template

The viewer injects a hint into served HTML: 
<script>window.__dxChromeTemplateCandidates=["/__dx/chrome-template"];</script>
This allows entry pages to load shared site chrome templates from:
  • docs/index.html
  • index.html
  • docs/entry/settings/index.html
  • entry-template/index.html
The first available template is served at /__dx/chrome-template.

​
Platform support

Browser auto-open uses:
  • macOS: open <url>
  • Windows: cmd /c start "" <url>
  • Linux: xdg-open <url>

dex init

Generate new entry HTML files

dex doctor

Scan and repair entry HTML

Build docs developers (and LLMs) love

Get started for freeTalk to us