Files, paths and templates

A small site directory #

The root is /lantern-data/sites/<name>. Page JSON filenames keep their .json extension in links. Only / maps automatically to /index.json. A Lua handler can implement routes such as /greet without a file extension.

my-first-site/
  index.json       # Home page
  about.json       # /about.json
  guides/
    start.json     # /guides/start.json
  app.lua          # Optional server handler
  data/            # Local ctx.write storage; never upload

How a request is resolved #

1. If app.lua exists, load it and call the returned function with ctx.
2. If the handler returns a response, use it.
3. If it returns nil, try the static JSON file for a GET request.
4. If no matching page exists, return a not-found error. Static files do not handle POST.

Pick the right starting point #

Hub package format #

A package is a JSON object with format: 1 and a files map. Map keys are relative paths; values are file contents as strings. The downloadable templates are ready-made packages. The computer’s Upload Hub draft action builds this package for you.

{
  "format": 1,
  "files": {
    "index.json": "{\"version\":1,\"title\":\"Hello\",\"children\":[{\"type\":\"paragraph\",\"text\":\"Hello!\"}]}"
  }
}

Keep paths inside the site #

Use paths such as /about.json or /guides/start.json. Traversal segments (.. and .), percent escapes, backslashes, query strings, fragments and colon-bearing paths are rejected. Form actions and redirects stay within the current site.