ASTRODOCK documentation Home GitHub

Pages

Host documents & mini-sites

Pages are for things that are less than an app: a one-off HTML report, a small static mini-site, a shared PDF, a quick prototype. No repo, no build, no deploy — you upload files (or paste content) and they're live immediately at pages.<your-domain>/<id>/. You can leave a page wide open, lock it with a passkey, or put your platform login in front of it.

Pages vs apps

Reach for a Page when you just need to put static content (or a tiny interactive widget) on the web. Reach for an app when you need a real backend, a database with many records, or per-user accounts and server-side logic.

The dividing line

A Page can hold a little saved state (see Saved data), but the moment you need growing, queryable, or relational data, that's an app — which gets its own full Postgres database.

Create a page

Two ways:

  • Dashboard — open Pages → New Page, then upload files or create a text file right in the browser.
  • CLI — point it at a folder and publish in one command. See Publishing a page.

Files & folders

A page is a set of files. One of them is the entry file (default index.html) — that's what the page link opens. Everything else is reachable by its path, and relative links just work:

index.html        →  https://pages.example.com/abc123def456/
style.css         →  …/abc123def456/style.css
img/logo.svg      →  …/abc123def456/img/logo.svg   (nested folders are fine)

The entry file doesn't have to be HTML. Make a PDF the entry and the page link becomes a clean, shareable file-share link.

Ship the built output

Pages serve static files as-is — there's no build step on the server. If you use Vite/webpack/etc., build locally and publish the output folder (e.g. dist/).

Access control

Each page has an access mode:

ModeWho can see it
PublicAnyone with the link.
PasskeyAnyone who knows a shared passkey. They're prompted for it, or you share a frictionless link with the key embedded.
Platform loginOnly people with an Astrodock user account — optionally restricted to a specific list of emails.

Passkey

Generate one or set your own. Visitors get a small prompt; or share the page with the key in the URL (…/<id>/?key=YOURKEY) and it unlocks silently. Rotating the passkey instantly invalidates every previously shared link.

A passkey is a latch, not a lock

It keeps a page out of casual reach, but it isn't real authentication — treat every passkey page as potentially public, and never put secrets in page content. For real per-person access, use Platform login.

Platform login

Put your platform's own user accounts in front of a page. Unauthenticated visitors get a sign-in form; after logging in they see the page. Leave the allowlist empty to allow any active user, or list specific emails to restrict it. Page authors write zero auth code — the platform gates the bytes.

Saved data

A page can have one small JSON data blob that its own JavaScript reads and writes — enough to make a document editable (e.g. a shared checklist people tick off). Turn it on per page and pick a scope:

  • Shared — one blob for the whole page (everyone edits the same thing).
  • Per-user — each logged-in user gets their own blob (requires platform login).

Your page talks to two endpoints at its own URL:

GET  …/<id>/_data   →  { "data": { … }, "version": 3 }
PUT  …/<id>/_data   ←  { "data": { … }, "version": 3 }   // version is optional

A checklist becomes a few lines of vanilla JS — GET on load, PUT on every change:

// load
const { data } = await (await fetch('_data')).json();
// save
await fetch('_data', {
  method: 'PUT',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ data: { items } })
});

Reads vs writes

Writes are always gated — a page with saved data must use passkey or platform access (never anonymous writes). Pass the passkey on the request (?key=…) or rely on the visitor's login session.

Limits

  • Data blob: up to 1 MB per blob (configurable). Bigger than that means you want an app, not a page.
  • Files: up to 200 MB each; the in-browser text editor handles files up to 2 MB.
  • Blob is for state, files are for bytes. Don't base64-embed images into the data blob — upload them as files and reference them by URL.

Managing a page

  • Active / inactive — flip a page to inactive and it 404s for everyone until you turn it back on (a soft, reversible alternative to deleting).
  • Views — each page tracks how many times it's been opened.
  • Update, don't duplicate — re-upload to the same page to publish a new revision; the link stays the same.
  • Delete — removes the page and all its files permanently.

Next steps