Pages CMS

https://pagescms.org/docs
Admin
Pages CMS is an open-source Content Management System for static websites, enabling users to edit...
Tokens:26,479
Snippets:307
Trust Score:8.5
Update:6 days ago
Show doc for...
Tokens:
Raw
### Run the GitHub App setup helper with all options

Source: https://pagescms.org/docs/guides/installing/github-app.md

Example of using the helper with all options: sets the base URL, writes environment variables to `.env`, creates the app under an organization, sets the org slug, sets the app name, and disables auto-opening the browser. After running, manually disable `User-to-server token expiration` if GitHub shows that option.

```bash
npm run setup:github-app -- \
  --base-url https://cms.example.com \
  --env .env \
  --owner-type org \
  --org my-company \
  --app-name "Pages CMS" \
  --no-open
```

--------------------------------

### Build and start the app

Source: https://pagescms.org/docs/guides/installing/self-host.md

Builds the project and starts the production server.

```bash
npm run build
npm run start
```

--------------------------------

### Start the app

Source: https://pagescms.org/docs/guides/installing.md

Starts the development server. For GitHub webhooks to reach your local app, use a public tunnel URL as the helper --base-url.

```bash
npm run dev
```

--------------------------------

### Install dependencies

Source: https://pagescms.org/docs/guides/installing.md

Installs the project dependencies using npm.

```bash
npm install
```

--------------------------------

### Create GitHub App with helper

Source: https://pagescms.org/docs/guides/installing.md

Runs the GitHub App setup helper with the local base URL and the .env.local file.

```bash
npm run setup:github-app -- --base-url http://localhost:3000 --env .env.local
```

--------------------------------

### Frontmatter with body content example

Source: https://pagescms.org/docs/configuration/content/fields.md

Example fields configuration with a boolean `published` field and a `body` rich-text field.

```yaml
fields:
  - name: title
    type: string
  - name: published
    type: boolean
  - name: body
    type: rich-text
```

--------------------------------

### Example with a collection and a single file

Source: https://pagescms.org/docs/configuration.md

Shows media with input/output paths, a collection for posts, a single file for site settings, and an action for deployment.

```yaml
media:
  input: src/media
  output: /media
content:
  - name: posts
    label: Posts
    type: collection
    path: src/posts
    fields:
      - name: title
        type: string
      - name: body
        type: rich-text
  - name: site
    label: Site settings
    type: file
    path: src/_data/site.json
    fields:
      - name: title
        type: string
      - name: description
        type: text
      - name: url
        type: string
actions:
  - name: deploy-site
    label: Deploy site
    workflow: pages-cms-action.yml

```

--------------------------------

### Date-based post filenames

Source: https://pagescms.org/docs/configuration/content/filename.md

Example of using date tokens to create filenames like `2025-03-15-title.md`.

```yaml
filename: "{year}-{month}-{day}-{title}.md"
```

--------------------------------

### Run the GitHub App setup helper with base URL

Source: https://pagescms.org/docs/guides/installing/github-app.md

Runs the built-in helper to create the GitHub App from a manifest. Prints the GitHub App environment variables. Use `--env <path>` to write them to a file.

```bash
npm run setup:github-app -- --base-url http://localhost:3000
```

--------------------------------

### Minimal .pages.yml example

Source: https://pagescms.org/docs/configuration.md

Defines media and a content collection for posts. Place at repository root; Pages CMS reads it per repository and branch.

```yaml
media: media
content:
  - name: posts
    label: Posts
    type: collection
    path: content/posts
    fields:
      - name: title
        type: string
      - name: body
        type: rich-text

```

--------------------------------

### Start PostgreSQL container

Source: https://pagescms.org/docs/guides/installing.md

Runs a PostgreSQL 16 container named pagescms-db with user, password, and database all set to 'pagescms', exposing port 5432.

```bash
docker run --name pagescms-db -e POSTGRES_USER=pagescms -e POSTGRES_PASSWORD=pagescms -e POSTGRES_DB=pagescms -p 5432:5432 -d postgres:16
```

--------------------------------

### Code editor configuration

Source: https://pagescms.org/docs/configuration/content/editors.md

Use `format: code` to enable a code-oriented editor for a single file. This example configures a redirects file.

```yaml
content:
  - name: redirects
    type: file
    path: public/_redirects
    format: code
```

--------------------------------

### String field with pattern example

Source: https://pagescms.org/docs/configuration/content/fields.md

A required string field with a regex pattern and min/max length options.

```yaml
fields:
  - name: slug
    type: string
    required: true
    pattern: "^[a-z0-9-]+$"
    options:
      minlength: 3
      maxlength: 80
```

--------------------------------

### Body special key example

Source: https://pagescms.org/docs/configuration/content/fields.md

For frontmatter formats, `body` maps to the file content below the frontmatter. All other fields stay in frontmatter.

```yaml
fields:
  - name: title
    type: string
  - name: body
    type: rich-text
```

--------------------------------

### Nested object field example

Source: https://pagescms.org/docs/configuration/content/fields.md

Shows how to define an object field with nested subfields for `name` and `email`.

```yaml
fields:
  - name: author
    type: object
    fields:
      - name: name
        type: string
      - name: email
        type: string
```

--------------------------------

### Text field with custom pattern message example

Source: https://pagescms.org/docs/configuration/content/fields.md

A required text field with a custom pattern message and min/max length options.

```yaml
fields:
  - name: summary
    type: text
    required: true
    pattern:
      regex: "^(?s).{20,500}$"
      message: "Summary must be between 20 and 500 characters"
    options:
      minlength: 20
      maxlength: 500
```

--------------------------------

### Datagrid editor configuration (inferred)

Source: https://pagescms.org/docs/configuration/content/editors.md

For `.csv` files, Pages CMS can infer the datagrid editor automatically. This example configures a pricing CSV file.

```yaml
content:
  - name: pricing
    type: file
    path: data/pricing.csv
```

--------------------------------

### Reusable field component example

Source: https://pagescms.org/docs/configuration/content/fields.md

Shows how to define a reusable `seo` component and reference it with `component` in a collection's fields. A field must use exactly one of `type` or `component`.

```yaml
components:
  seo:
    type: object
    label: SEO
    fields:
      - name: title
        type: string
      - name: description
        type: text

content:
  - name: pages
    type: collection
    path: content/pages
    fields:
      - name: seo
        component: seo
        label: Meta
```

--------------------------------

### Structured fields editor configuration

Source: https://pagescms.org/docs/configuration/content/editors.md

Use `fields` to model a file or collection as structured content. This example defines a posts collection with title and body fields.

```yaml
content:
  - name: posts
    type: collection
    path: content/posts
    fields:
      - name: title
        type: string
      - name: body
        type: rich-text
```

--------------------------------

### Datagrid editor configuration (explicit)

Source: https://pagescms.org/docs/configuration/content/editors.md

Set `format: datagrid` explicitly to use the datagrid editor for non-CSV files or when inference is not desired. This example configures a pricing file without extension.

```yaml
content:
  - name: pricing
    type: file
    path: data/pricing
    format: datagrid
```

--------------------------------

### Object list with `min`, `max`, and `collapsible` object form

Source: https://pagescms.org/docs/configuration/content/list.md

Configures an object list with minimum and maximum items, and collapsible items that start collapsed with a custom summary using `{title}` and `{index}` tokens.

```yaml
- name: sections
  type: object
  list:
    min: 1
    max: 6
    collapsible:
      collapsed: true
      summary: "{title} ({index})"
  fields:
    - name: title
      type: string
    - name: body
      type: rich-text

```

--------------------------------

### Pattern as an object with custom message

Source: https://pagescms.org/docs/configuration/content/fields.md

Use an object with `regex` and `message` keys to provide a custom validation error message. The example expects a format like ABC-1234.

```yaml
pattern:
  regex: "^[A-Z]{3}-\\d{4}$"
  message: "Use format ABC-1234"
```

--------------------------------

### Top-level array in a file with `list: true`

Source: https://pagescms.org/docs/configuration/content/list.md

For `type: file` content entries, set `list: true` when the file content itself is an array. This example configures a JSON file with a list of authors.

```yaml
content:
  - name: authors
    label: Authors
    type: file
    path: data/authors.json
    format: json
    list: true
    fields:
      - name: name
        type: string
      - name: email
        type: string
      - name: avatar
        type: image

```

--------------------------------

### Run GitHub App helper

Source: https://pagescms.org/docs/guides/installing/vercel.md

Use the helper to create a GitHub App and write its environment variables to .env. Replace the base URL with your chosen public URL.

```bash
npm run setup:github-app -- --base-url https://cms.example.com --env .env
```

--------------------------------

### Create .env with required environment variables

Source: https://pagescms.org/docs/guides/installing/self-host.md

Add at least DATABASE_URL, BETTER_AUTH_SECRET, CRYPTO_KEY, BASE_URL, and optionally ADMIN_EMAILS to control admin panel access.

```bash
DATABASE_URL=postgresql://...
BETTER_AUTH_SECRET=your-random-secret
CRYPTO_KEY=your-random-secret
BASE_URL=https://cms.example.com
ADMIN_EMAILS=admin@example.com
```

--------------------------------

### Create .env.local

Source: https://pagescms.org/docs/guides/installing.md

Defines the required environment variables: DATABASE_URL, BETTER_AUTH_SECRET, and CRYPTO_KEY. Replace the secret values with your own.

```bash
DATABASE_URL=postgresql://pagescms:pagescms@localhost:5432/pagescms
BETTER_AUTH_SECRET=your-random-secret
CRYPTO_KEY=your-random-secret
```

--------------------------------

### Run migrations

Source: https://pagescms.org/docs/guides/installing.md

Applies database migrations.

```bash
npm run db:migrate
```

--------------------------------

### Editable filename on create

Source: https://pagescms.org/docs/configuration/content/filename.md

Example of using the object form with `field: create` to allow editing the filename only when creating a new entry.

```yaml
filename:
  template: "{primary}.md"
  field: create
```

--------------------------------

### Single media object configuration

Source: https://pagescms.org/docs/configuration/media.md

Configures a single media source with input, output, rename, and categories.

```yaml
media:
  input: src/media
  output: /media
  rename: random
  categories: [image]
```

--------------------------------

### Export collaborators from legacy SQLite or libSQL using flags

Source: https://pagescms.org/docs/guides/migrating-collaborators.md

Alternative command to export collaborators from a legacy database, passing credentials as flags --url, --token, and --out instead of environment variables.

```bash
npx -y -p @libsql/client node db/scripts/export-collaborators-legacy-libsql.mjs \
  --url="libsql://..." \
  --token="..." \
  --out=collaborators.csv
```

--------------------------------

### Export collaborators from legacy SQLite or libSQL using environment variables

Source: https://pagescms.org/docs/guides/migrating-collaborators.md

Use this command to export collaborators from a legacy SQLite or libSQL/Turso database. Credentials are provided via environment variables SQLITE_URL and SQLITE_AUTH_TOKEN. Run from the Pages CMS repository root.

```bash
SQLITE_URL="libsql://..." SQLITE_AUTH_TOKEN="..." \
npx -y -p @libsql/client node db/scripts/export-collaborators-legacy-libsql.mjs --out=collaborators.csv
```

--------------------------------

### Equivalent object form for media string

Source: https://pagescms.org/docs/configuration/media.md

Shows the object equivalent of the string form, setting input to 'media' and output to '/media'.

```yaml
media:
  input: media
  output: /media
```

--------------------------------

### Define and reference a component in content

Source: https://pagescms.org/docs/configuration/components.md

Shows how to define a `seo` component with fields and reference it from a collection's fields. The component label is `SEO`, but the field label overrides it to `Meta`.

```yaml
components:
  seo:
    type: object
    label: SEO
    fields:
      - name: title
        type: string
      - name: description
        type: text

content:
  - name: pages
    type: collection
    path: content/pages
    fields:
      - name: heading
        type: string
      - name: seo
        component: seo
        label: Meta
```

--------------------------------

### Named media config and default folder

Source: https://pagescms.org/docs/configuration/fields/file.md

Configures a file field to use the 'docs' media config and default browsing folder 'public/files/brochures'.

```yaml
- name: brochure
  label: Brochure
  type: file
  options:
    media: docs
    path: public/files/brochures
```

--------------------------------

### Raw file editor configuration

Source: https://pagescms.org/docs/configuration/content/editors.md

When `fields` is omitted or empty, Pages CMS uses a raw file editor. This example configures a single file editor for robots.txt.

```yaml
content:
  - name: robots
    label: robots.txt
    type: file
    path: public/robots.txt
```

--------------------------------

### Multiple media sources configuration

Source: https://pagescms.org/docs/configuration/media.md

Defines an array of media sources for different field types, each with its own input, output, rename, extensions, and actions.

```yaml
media:
  - name: images
    label: Images
    input: media/images
    output: /media/images
    rename: safe
    extensions: [png, jpg, webp]
    actions:
      - name: optimize-images
        label: Optimize images
        workflow: pages-cms-media-action.yml
  - name: docs
    label: Documents
    input: media/docs
    output: /media/docs
    categories: [document]
```

--------------------------------

### Minimal custom field example

Source: https://pagescms.org/docs/guides/creating-custom-field.md

A minimal custom field implementation exporting label, schema, EditComponent, and ViewComponent. Uses a Zod schema for validation and an Input component for editing.

```tsx
import { z } from "zod";
import { Input } from "@/components/ui/input";

const schema = () => z.string().min(1, "Required");

const EditComponent = ({ value, onChange }: any) => (
  <Input value={value || ""} onChange={(event) => onChange(event.target.value)} />
);

const ViewComponent = ({ value }: { value: unknown }) => {
  if (!value) return null;
  return <span>{String(value)}</span>;
};

const label = "My field";

export { label, schema, EditComponent, ViewComponent };
```

--------------------------------

### Generate a migration with npm run db:generate

Source: https://pagescms.org/docs/development/database.md

Run this command when the schema changes to generate a new migration.

```bash
npm run db:generate
```

--------------------------------

### Minimal config for testing

Source: https://pagescms.org/docs/guides/creating-custom-field.md

A minimal YAML config that uses the custom field type 'my-field' for a field named 'promo'.

```yaml
fields:
  - name: promo
    type: my-field
```

--------------------------------

### Named media config and default folder

Source: https://pagescms.org/docs/configuration/fields/image.md

Configures an image field with a named media config and a default browsing folder.

```yaml
- name: cover
  label: Cover image
  type: image
  options:
    media: images
    path: public/images/posts
```

--------------------------------

### Example JSON payload sent by Pages CMS

Source: https://pagescms.org/docs/configuration/actions.md

This JSON object is sent by Pages CMS inside `inputs.payload`. It includes action metadata, repository metadata, triggering user, context, and extra field values in `payload.inputs`.

```json
{
  "source": "pages-cms",
  "action": {
    "name": "deploy-site",
    "label": "Deploy site"
  },
  "repository": {
    "owner": "pagescms",
    "repo": "website",
    "ref": "main",
    "workflowRef": "main",
    "sha": "abc123..."
  },
  "triggeredAt": "2026-03-30T12:00:00.000Z",
  "triggerType": "rerun",
  "rerunOfActionRunId": 42,
  "triggeredBy": {
    "userId": "...",
    "name": "Ronan Berder",
    "email": "...",
    "githubUsername": "hunvreus",
    "image": "..."
  },
  "context": {
    "type": "entry",
    "name": "posts",
    "path": "content/posts/hello.md",
    "data": {}
  },
  "inputs": {
    "environment": "staging",
    "force": false
  }
}
```

--------------------------------

### Basic list view configuration

Source: https://pagescms.org/docs/configuration/content/view.md

Configures a collection list view with fields, primary field, sort options, and default sort order.

```yaml
view:
  fields: [title, published, date]
  primary: title
  sort: [date, title]
  default:
    sort: date
    order: desc
```

--------------------------------

### Registration path and type

Source: https://pagescms.org/docs/guides/creating-custom-field.md

Shows the file path that registers a custom field and the resulting YAML type.

```text
fields/custom/my-field/index.tsx
```

```yaml
type: my-field
```

--------------------------------

### String form for media

Source: https://pagescms.org/docs/configuration/media.md

Defines media as a string, equivalent to setting input to 'media' and output to '/media'.

```yaml
media: media
```

--------------------------------

### Define file and media actions in Pages CMS

Source: https://pagescms.org/docs/configuration/actions.md

Configure actions for file and media types. File actions operate on a single file, while media actions apply to media items.

```yaml
content:
  - name: site
    label: Site settings
    type: file
    path: data/site.yml
    fields:
      - name: title
        type: string
    actions:
      - name: validate-config
        label: Validate config
        workflow: pages-cms-file-action.yml

media:
  - name: images
    label: Images
    input: media/images
    output: /media/images
    actions:
      - name: optimize-images
        label: Optimize images
        workflow: pages-cms-media-action.yml
```

--------------------------------

### Clear cache after upgrading

Source: https://pagescms.org/docs/guides/upgrading-to-2.md

Recommended once after upgrading to 2.x to remove old cache data and rebuild with 2.x cache logic.

```bash
npm run db:clear-cache
```

--------------------------------

### Markdown with media

Source: https://pagescms.org/docs/configuration/fields/rich-text.md

Configures a rich-text field with Markdown format and media support, setting the media source to 'content_images', the default image folder to 'public/images/blog', enabling renaming, and showing the mode switch.

```yaml
- name: body
  label: Body
  type: rich-text
  options:
    media: content_images
    path: public/images/blog
    rename: true
    switcher: true
```

--------------------------------

### Set environment variables for Vercel

Source: https://pagescms.org/docs/guides/installing/vercel.md

Environment variables required for the Vercel project. Use the GitHub App variables from the helper and set POSTGRES_MAX_CONNECTIONS=1 when using a pooled Supabase connection.

```bash
DATABASE_URL=postgresql://...
POSTGRES_MAX_CONNECTIONS=1
BETTER_AUTH_SECRET=your-random-secret
CRYPTO_KEY=your-random-secret
BASE_URL=https://cms.example.com
```

--------------------------------

### Simple block list configuration and saved output

Source: https://pagescms.org/docs/configuration/fields/block.md

Defines a block field with two block types (hero and text) using `blockKey: type`. The saved output shows how the selected block type is stored.

```yaml
- name: sections
  label: Sections
  type: block
  list: true
  blockKey: type
  blocks:
    - name: hero
      component: hero
    - name: text
      fields:
        - name: body
          type: rich-text

```

```yaml
sections:
  - type: hero
    heading: Welcome
    image: /images/hero.jpg
  - type: text
    body: Hello world

```

--------------------------------

### Multiple downloadable resources

Source: https://pagescms.org/docs/configuration/fields/file.md

Allows up to 5 document files, disallows duplicate paths, and renames uploads to slugified names.

```yaml
- name: resources
  label: Resources
  type: file
  options:
    categories: [document]
    multiple:
      max: 5
    unique: true
    rename: true
```

--------------------------------

### Collection content configuration

Source: https://pagescms.org/docs/configuration/content.md

Defines a collection named 'posts' with fields and actions. Actions include 'rebuild-posts' with scope 'collection' and 'preview-post' with scope 'entry'.

```yaml
content:
  - name: posts
    label: Posts
    type: collection
    path: content/posts
    fields:
      - name: title
        type: string
      - name: body
        type: rich-text
    actions:
      - name: rebuild-posts
        label: Rebuild posts
        scope: collection
        workflow: pages-cms-collection-action.yml

      - name: preview-post
        label: Preview
        scope: entry
        workflow: pages-cms-entry-action.yml
```

--------------------------------

### Date field with time and format

Source: https://pagescms.org/docs/configuration/fields/date.md

Configures a date field named publish_at with time picker enabled and a custom output format using date-fns tokens. Set default to "" to keep the field empty initially.

```yaml
- name: publish_at
  type: date
  default: ""
  options:
    time: true
    format: yyyy-MM-dd'T'HH:mm
```

--------------------------------

### Specific file extensions

Source: https://pagescms.org/docs/configuration/fields/file.md

Restricts allowed file extensions to zip, tar, and gz.

```yaml
- name: archive
  label: Archive
  type: file
  options:
    extensions: [zip, tar, gz]
```

--------------------------------

### Multiple images

Source: https://pagescms.org/docs/configuration/fields/image.md

Allows multiple images with a maximum of 6, enforces unique paths, restricts extensions to jpg, png, and webp, and enables renaming.

```yaml
- name: gallery
  label: Gallery
  type: image
  options:
    multiple:
      max: 6
    unique: true
    extensions: [jpg, png, webp]
    rename: true
```

--------------------------------

### Global default with a media override

Source: https://pagescms.org/docs/configuration/settings.md

Sets global commit identity to 'app' and overrides commit identity and update template for a media entry named 'assets'.

```yaml
settings:
  commit:
    identity: app

media:
  - name: assets
    input: public/uploads
    output: /uploads
    commit:
      identity: user
      templates:
        update: "media(update): {path} by {userEmail}"
```

--------------------------------

### String form of filename

Source: https://pagescms.org/docs/configuration/content/filename.md

Use a string template to set the filename pattern. The `{primary}` token is replaced by the primary field value.

```yaml
filename: "{primary}.md"
```

--------------------------------

### List summary with tokens YAML

Source: https://pagescms.org/docs/configuration/fields/object.md

Configures a collapsible list summary using tokens. The summary uses {title} and {index} tokens; {index} is always available, and missing values resolve to an empty string.

```yaml
- name: sections
  type: object
  list:
    collapsible:
      collapsed: true
      summary: "{title} ({index})"
  fields:
    - name: title
      type: string

```

--------------------------------

### Multiple references with min and max

Source: https://pagescms.org/docs/configuration/fields/reference.md

Allows selecting 1 to 5 references from the 'categories' collection. Requires the 'multiple' option to be true.

```yaml
- name: categories
  type: reference
  options:
    collection: categories
    multiple: true
    min: 1
    max: 5
```

--------------------------------

### Configure MDX snippet with format: mdx

Source: https://pagescms.org/docs/configuration/fields/code.md

Use this YAML configuration to create a code field for MDX snippets. The format option is set to 'mdx'.

```yaml
- name: article
  type: code
  options:
    format: mdx

```
Tokens:
Raw