Buzl HTML Editor

A local visual editor and static-site server for ordinary multi-page HTML, CSS, and JavaScript websites. It includes on-page Live Edit, image uploads, AVIF image optimization, AI-assisted text, and AI image generation.

The server is local-only by default. It edits the website folder from which it is started; the editor's own files stay inside the npm package.

Documentation

• Full setup handbook: HANDBOOK.md
• Printable handbook: docs/Buzl-HTML-Editor-Handbook-Advanced.pdf

Requirements

• Node.js 18 or newer
• Node.js 20 LTS or newer is recommended
• A static website containing one or more .html files

Install

Run this inside the website root:

npm install --save-dev @mahe_pkm/buzl-html-editor

Start the website and editor

npx buzl-editor

Default addresses:

• Website with a floating Edit Text toolbar: http://localhost:4000/
• Advanced editor: http://localhost:4000/admin/

buzl-editor opens the website preview by default. Select the small floating pencil button to open the Buzl menu, then select Edit Text to edit visible text directly on any page. Use Save, Undo, or Cancel from the compact menu. The toolbar is injected only while the local editor server is running and is never added to the saved website.

Open the advanced editor by default when needed:

npx buzl-editor --open-admin

Use another port or website folder when needed:

npx buzl-editor --port 4500
npx buzl-editor --root "C:\Websites\client-site" --port 4500

Prevent automatic browser opening:

npx buzl-editor --no-open

Website-only mode

npx buzl-site
npx buzl-site --port 3500

Website-only mode does not inject the editing toolbar and blocks the editor, APIs, dependencies, configuration, development files, and local secrets.

Setup and diagnostics

Initialize optional configuration in the current website:

npx buzl-editor init

This creates .buzl/config.json, .env.example, and safe .gitignore rules without replacing existing files.

Inspect a website before editing:

npx buzl-editor doctor

Optional configuration

.buzl/config.json:

{
  "editorPort": 4000,
  "websitePort": 3000,
  "host": "127.0.0.1",
  "open": true
}

Command-line options take priority over environment variables, configuration, and defaults.

AI configuration

Create .env in the client website root. Never commit this file.

ANTHROPIC_API_KEY=
OPENROUTER_API_KEY=

The editor and image uploads work without the AI keys. Only the related AI actions require them.

Safety

• The default bind address is 127.0.0.1.
• Non-local binding requires both --host and --allow-network.
• The editor can only load and save HTML files inside the selected website.
• Each save creates a recoverable copy under .buzl/backups/.
• Preview Live Edit uses short-lived page tokens, rejects stale-page saves, and is disabled when the editor binds to a non-local network address.
• Uploaded raster images are optimized to AVIF under assets/images/.
• .env, .git, .buzl, node_modules, tests, package metadata, and server source are not publicly served.

Press Ctrl+C to stop either server.