The preview server watches Stog files and recomputes the documents when there is a change. This is useful to have a preview as you modify your web site or article.

Have a look at stog server in action on a video here.

When launched, the server computes the documents a first time. It then handles HTTP connections. All documents are accessed under the path /preview/. For example, the /foo/bar.html document will be browsed, by default, at address http://localhost:8080/preview/foo/bar.html.

When a browser queries a document preview, the server returns a simple page with some javascript code to load. This javascript code opens a websocket connection, by default to http://localhost:8081, and queries the document. The server sends the whole document preview and the javascript code fills the DOM with the document.

When a source file is modified, the server recomputes the corresponding documents and sends a patch to the browser, through the websocket connection. The javascript code applies the patch to the DOM.

Applying patches rather than reloading the whole document is better when some parts of the document are changed by some other code (I'm looking at you, Mathjax). By now, this case is not fully handled yet, but this is work in progress. The javascript part of the Xmldiff library allows to specify some nodes to ignore when applying a patch.

By now, only documents which exist when the server is launched are watched for changes. This means that if you add a new document source file, you have to click on the ↺ button at the top of the preview page.

To run the server, simply run stog-server[.byte] instead of stog[.byte], with the same parameters.

The --http and --ws command line options can be used to specify a url defining the host and port to listen on, for the HTTP and websocket servers respectively. Defaults are http://localhost:8080 and ws://localhost:8081.

If the server must be run behind a proxy, you must also give the --pub-http and --pub-ws options to indicate the "public" base urls, i.e. the ones that the proxy will handle to send queries to the server.