Inside live preview

Quarkdown's webserver allows direct communication between the compiler's CLI and the browser, making live previewing possible.

In particular, it exposes the following endpoints:

• /:file: Serves static files, relative to the target file (-f option of quarkdown start).

• /live/:file: Similar to the previous one, but wraps HTML files in a wrapper, suitable for live reloading.

• /reload: WebSocket endpoint for live reloading.

  • Browsers connected to the /live endpoint start listening, and reload the page when it receives a reload message.
  • The CLI connects to this endpoint and sends a message every time a compilation is performed. When it does so, the server broadcasts a reload message to all connected browsers.

Live preview wrapper

When serving a file through the /live/:file endpoint, the server wraps HTML files in a simple HTML wrapper that displays the content of /:file in an iframe.

Additionally, a small script establishes a persistent WebSocket connection to the /reload endpoint. This script listens for reload messages and triggers a reload of the iframe content when a message is received.

sequenceDiagram
    participant Browser
    participant Server
    participant CLI

    Browser->>Server: GET /live/:file
    Server-->>Browser: Live preview HTML wrapper
    Browser->>Server: WebSocket connect /reload
    CLI->>Server: WebSocket message /reload
    Server->>Browser: WebSocket broadcast /reload
    Browser->>Browser: Reload iframe content

Loading

Double buffering

When an iframe is reloaded, an unpleasant flickering effect can occur. In order to grant a smooth user experience, Quarkdown employs a technique called double buffering.

For context, you are constantly exposed to double buffering: your GPU renders the next frame to an off-screen buffer while displaying the current frame. Once the next frame is ready, the buffers are swapped, resulting in a smooth transition without flickering.

The same way, Quarkdown holds two iframes, A and B.
Let's say A is currently being displayed. When a change is detected, Quarkdown renders the updated content into B while A is still visible. Once the rendering is complete, the displayed iframe is switched from A to B, providing a seamless update.

Also, before swapping the buffers, the scroll position from the previous frame is preserved and restored in the new frame, so the user doesn't lose their place.