How do I deploy the site?

Table of Contents

For the build script that does the work (projects/ores.lisp/src/ores-build-site.el) and the output location, see CMake setup.

1. Question

How do I build the ORE Studio website locally?

2. Answer

There are two commands. Use compass site page for every check, including the one before a commit. Use the full build only once per checkout, to write the caches that site page reuses.

2.1. Every check: publish what you changed

compass site page publishes every page whose source is newer than its published HTML, in about a second each. It stops on a broken link in any page it publishes, so it is also the check to run before a commit: 

./compass.sh site page

Name files to rebuild them whether or not they have changed, which is what you want when the rendering rather than the source has moved: 

./compass.sh site page doc/llm/skills/skill_architecture.org

This reuses the publish cache the last full build wrote, which is where the speed comes from. It rebuilds the identifier map first, so a page linking to a document added since the last full build still resolves. That scan takes about three seconds; skip it with --no-index when nothing has been added, renamed or deleted: 

./compass.sh site page --no-index

2.2. First build in a checkout: publish everything

./compass.sh build --direct site

--direct mode calls Emacs directly, with no cmake and no vcpkg, so it works in a light environment. It invokes projects/ores.lisp/src/ores-build-site.el, which rebuilds the identifier map, syncs the org-roam database, and publishes every .org file in the repository (excluding .packages, vcpkg, build) to HTML. Output lands at build/output/site/.

It reads every file and takes minutes rather than seconds. Run it once in a new checkout, or when the publish cache is gone, so that compass site page has caches to reuse. It is not the routine check: compass site page checks the pages a change touches, and the build-site.yml workflow publishes the whole site on every push to main.

In a full environment the equivalent deploy_site CMake target runs the same script; for the raw CMake build (presets, targets, cmake --build directly) see How do I build the system?.

2.3. Previewing locally

The site uses absolute /OreStudio/ paths (matching GitHub Pages). Use compass to preview with the correct URL structure: 

./compass.sh site serve

Then open http://localhost:<ORES_SITE_PORT>/OreStudio/ in a browser (port from .env; default 51004 for local1).

To rebuild and serve in one step: 

./compass.sh site serve --compile

Use --port N to override the port.

2.4. Prerequisites

  • Emacs on PATH. The script uses org-publish, org-id, and oc-bibtex from a default Emacs install with org-mode shipped.
  • --direct needs no preset or build directory. (The full-environment compass build site / deploy_site cmake path does: a .env with ORES_PRESET set, configured automatically on first build.)

2.5. When to run which

compass site page is the default, including after adding, renaming or deleting a document. It rebuilds the identifier map itself, so a new :ID: resolves without a full pass.

The full build does two things the page build does not. It regenerates graph/graphdata.json, which backs the graph view, and it walks every document, which is how a link that no longer resolves is found. Run it when you need either.

A full build on a tree with three changed pages publishes three pages and re-stats five thousand files to do it. That takes upward of ten minutes against about five seconds, so reach for it because you want the graph or the sweep, not as a precaution before committing.

2.5.1. Rebuilding the identifier map on its own

.org-id-locations-file maps each :ID: to the file holding it, and is what turns an [[id:UUID]] link into a path at publish time. Both site commands rebuild it, as do the manual, help, skills and plan builds. To rebuild it alone: 

./compass.sh index --org-ids

It is distinct from compass index, which builds the search index, and from compass index --org-roam-db-sync, which syncs .org-roam.db.

2.5.2. Deleted pages are not removed

Neither command deletes a published page whose source has gone. A renamed or retired document keeps serving its old content from the previous build until the file is removed by hand, as in: 

rm build/output/site/OreStudio/doc/llm/skills/skill_planes.html

This matters more than an ordinary stale file, because a reader following an old link reaches a page describing a state that no longer exists. A sweep that removes built output with no source is tracked as a backlog capture.

3. Script

projects/ores.lisp/src/ores-build-site.el is the Emacs script that compass build --direct site runs. projects/ores.lisp/src/ores-build-page.el is the script behind compass site page: it loads the site script's configuration, stops before its work, and publishes only the files it is given. projects/ores.lisp/src/ores-org-ids.el holds the identifier scan and the directories it excludes, shared by every build that resolves an id: link. The equivalent deploy_site CMake target definition lives in CMakeLists.txt near add_custom_target(deploy_site ...) and invokes the same script.

4. Tested by

The build-site.yml GitHub Action publishes the site on every push to main. The action's success is the integration test for this recipe.

5. See also

Emacs 29.3 (Org mode 9.6.15)