How do I serve the site locally?
Table of Contents
Run compass site serve to compile (optionally) and preview the org-mode site locally before pushing.
The equivalent CMake target is in How do I deploy the site?.
Question
How do I preview the ORE Studio documentation site on my local machine?
Answer
Compile and serve in one step (most common):
./compass.sh site serve --compile
Then open http://localhost:<ORES_SITE_PORT>/OreStudio/ in a browser (ORES_SITE_PORT comes from .env; fallback default is 51004 when ORES_SITE_PORT is not set).
Serve a previously compiled build without recompiling:
./compass.sh site serve
Use a different port:
./compass.sh site serve --compile --port 9000
How it works
--compile runs emacs -Q --script projects/ores.lisp/src/ores-build-site.el
from the repo root, which publishes every .org file to HTML under
build/output/site/.
After compiling (or if the build directory already exists), compass site serve
starts Python's built-in HTTP server rooted at build/output/site/. Pages are
served directly under /OreStudio/ to match the GitHub Pages URL structure
(orestudio.github.io/OreStudio/).
The port is resolved in this order: --port flag → ORES_SITE_PORT from .env →
51004 (last-resort default when ORES_SITE_PORT is not set).
Prerequisites
Emacs must be on PATH (for --compile). No CMake configure step
required — compass runs independently of the build system.
Tested by
Manual preview before pushing documentation changes. The
build-site.yml GitHub Action publishes the site on every push to
main and is the integration test for the full pipeline.
See also
- How do I deploy the site? —
compass build --direct site(same Emacs step, no HTTP server). - How do I deploy the skills? — publish Claude Code skills alongside the site.
- How do I create a new doc? — add org files that will appear in the compiled site.