# Pages

Oak Pages publishes a folder of a repo as a static website:

```text
https://<name>.oak.page/
```

You pick the name, and it's yours across all of oak.page. A repo can have as many sites as you like, each from its own folder: `docs/` at one name, `examples/demo/` at another. Every merge to `main` redeploys them. There's no build step on Oak's side: the site serves the files that are on `main`.

Pages is in early access. If you don't see **Settings → Pages** on your repo, please let us know and we'll turn it on.

## Create a site

From a checkout of the repo:

```bash
oak site create acme-docs --dir docs     # https://acme-docs.oak.page/ ← docs/ on main
oak site create acme-demo --dir examples/demo --spa
oak site list
```

Or open the repo's **Settings → Pages** and use **Add site**. Leave the folder empty to publish the whole repo.

Creating, renaming and deleting sites, changing their folder and setting a password take an owner or admin of the repo's organization, because a site claims a name for the organization. Anyone with write access can redeploy or roll back.

## Names

A name is one DNS label: lowercase letters, digits and hyphens, up to 63 characters, starting and ending with a letter or digit.

Some names aren't available:

- Names Oak uses or might use, and names that could be used to impersonate a service: `www`, `api`, `mail`, `docs`, `login`, `support` and many more. Names starting with `oak-` are reserved too.
- A name that matches an organization's slug belongs to that organization. Only `acme` can claim `acme.oak.page`.
- When a site is deleted or renamed, its old name stays with its organization for 30 days, so nobody else can pick it up and receive its traffic. During that time a renamed site's old address redirects to the new one.

`oak site check NAME` tells you whether a name is free.

## How files are served

For a request to `/path`, Oak serves, in order:

1. `path/index.html` when the path ends in `/` (the root is `index.html`).
2. The exact file, then `path.html`, so `/about` finds `about.html`.
3. A redirect to `/path/` when `path` is a folder, so relative links work.
4. With the **SPA fallback** on, `index.html` for any path without a file extension. Use this for single-page apps with client-side routing.
5. Your `404.html`, with status 404, if the site has one.

Each site is its own origin, so root-relative links like `/assets/app.js` work without setting a base path in your build. Sites can't read each other's cookies or storage, or oak.space's.

Responses are cached for up to a minute, so a new deploy can take that long to show everywhere.

## Deploys

Every merge to `main` redeploys each of the repo's sites from the new `main`. A merge that doesn't change a site's files doesn't create a deployment for it. A deploy that fails (the folder is empty, or a limit is exceeded) is recorded with its reason, and the site keeps serving the last good deployment.

```bash
oak site deploys acme-docs           # history, newest first
oak site redeploy acme-docs          # deploy main again now
oak site rollback acme-docs          # back to the previous good deployment
oak site rollback acme-docs --to 42  # or a specific one
```

A rollback lasts until the next merge to `main` that changes the site.

If your site needs a build step, commit the build output to a folder and point the site at it. Uploading a build from CI is on our list.

## Private repos and path permissions

You can publish a site from a private repo. The site itself is public, so only publish folders you mean to share. Files that [path permissions](/docs/path-permissions) hide from a repo's readers are never published, whatever folder the site points at.

To keep a site private, set a password in **Settings → Pages** or with `oak site set NAME --password-user USER --password-file FILE`. Visitors then get a browser sign-in prompt (HTTP Basic Auth).

## Limits

| | Limit |
|---|---|
| Sites per organization | 10 |
| Files per site | 10,000 |
| Largest file | 25 MiB |
| Total size of a site | 1 GiB |

Sites serve static files with `GET` and `HEAD` only. Paths under `/_oak/` are reserved for Oak (`/_oak/health` reports the live deployment).

## Moving and deleting

Transferring a repo to another organization deletes its sites, and their names stay with the old organization for 30 days. Deleting a repo deletes its sites the same way.

## Reporting abuse

To report a site for phishing, malware or other abuse, email [abuse@oak.space](mailto:abuse@oak.space) with its address. We can disable a site immediately.