Local preview and build workflow

When writing or editing site content, you want to see changes before pushing them to a live instance. Everlock is building local site tooling under everlock site specifically to close this loop. This page describes the intended workflow, the current state of the commands, and how to work effectively in the meantime.

The goal

The problem with most static site tooling is that local preview and deployed serving use different engines. You preview in Hugo or Zola locally, then push to a different serving infrastructure. Rendering differences accumulate silently.

Everlock's approach is to use the same backend-site-http rendering engine for both local preview and deployed serving. That means:

• Mermaid diagrams, shortcodes, templates, and routing rules are identical locally and in production
• Local preview output is not an approximation — it is the same code path
• A page that looks right locally will look right when pushed

Planned commands

everlock site preview

everlock site preview --path ./website

Starts a local HTTP server that serves the site at http://localhost:3000. Changes to files in the directory are reflected immediately on the next request — no rebuild step, no watch daemon. This uses the same rendering logic as a deployed Everlock instance.

everlock site build

everlock site build --path ./website --out ./dist

Renders the entire site into static HTML files in the ./dist directory. Useful when you need to deploy to infrastructure that serves static files rather than running Everlock itself, or when you want a snapshot of the rendered output for review.

Working locally today

Until everlock site preview is available, the most direct local workflow is to run a full Everlock instance against your site directory.

Option 1 — run Everlock locally with a local vhost

Start Everlock and create a local site:

everlock serve
# in another terminal:
ssh -p 2222 admin@localhost
/backends enable site-http git-ssh
/site create dev-site vhost=localhost mode=markdown

Clone the site repository to your working directory:

git clone ssh://admin@localhost:2222/dev-site ./my-site
cd my-site

As you edit content, commit and push:

git add .
git commit -m "wip"
git push

Reload http://localhost to see the result. Everlock serves the new content immediately after the push.

This is more ceremony than a preview command, but it uses the exact same rendering engine as a deployed instance.

Option 2 — use a git alias for fast iteration

Reduce the push cycle to a single command with a git alias:

git config alias.preview '!git add -A && git commit -m "preview" && git push'

Then iterate with:

git preview

What to check locally

When previewing locally, the key things to verify before pushing to a production instance are:

• Mermaid diagrams render — diagrams are rendered in the browser, so they work the same locally and on the server
• Shortcodes expand — a broken shortcode renders as an HTML comment, so it fails visibly
• Section listings are correct — visit section directories to verify _index.md titles, custom layouts, and child ordering
• Search works — visit /search and run a query; the search index is regenerated on each push
• RSS is valid — visit /index.xml and check the feed structure

Keeping local and production aligned

Because Everlock serves content directly from the git store without a separate build step, a git push to production has the same effect as a git push to your local instance. There is no build pipeline that could diverge.

The main risk is template variables or shortcode behavior that differ between Everlock versions. To guard against this:

• run the same Everlock version locally as you do in production
• use cargo install from the same commit to install both environments

Read next

• Getting started with a Markdown site
• Markdown site directory structure
• Writing and customizing templates