Payload Website

By default, the site pulls documentation from the main branch of the Payload repository. To preview documentation from a different branch without performing a full CMS sync, use the /docs/dynamic/ route with a branch query parameter.

Example usage:

• Main branch: https://payloadcms.com/docs/getting-started/concepts
• Specific branch: https://payloadcms.com/docs/dynamic/getting-started/concepts?branch=feat/myfeature

In the CMS, you can use the branch selector to choose which branch to work on. When you save changes to a document, the Lexical docs are converted back to MDX and pushed to the selected branch on GitHub.

To set up the development environment for the Payload Website repository, follow these steps:

1. Clone the repository.
2. Install dependencies using pnpm i.
3. Create an environment file by running cp .env.example .env.
4. Populate the .env file with the appropriate values for your environment.
5. Start the development server with pnpm dev.

Important: Hosts File Configuration Because of http-only cookie policies and GitHub App redirect requirements, the application must run on local.payloadcms.com:3000. You must add the following entry to your system's hosts file:

• Mac: /etc/hosts
• Windows: C:\Windows\System32\drivers\etc\hosts

127.0.0.1 local.payloadcms.com

You can preview local Markdown files in the website without modifying the database by using the /docs/local/ route.

1. Set the DOCS_DIR_V3 environment variable to the absolute path of your local docs directory.
2. Access the documentation via the /docs/local/ path prefix.

Example: If DOCS_DIR_V3=/documents/github/payload/docs, you can view a concept page at http://localhost:3000/docs/local/getting-started/concepts.

Changes to local MDX files are reflected on page reload via on-the-fly conversion to Lexical.

The website documentation is stored as Markdown files in the Payload repository on GitHub. You can synchronize these docs into the CMS using the "Sync Docs" button within the CMS interface.

When triggered, the sync process:

1. Pulls docs from the Payload GitHub repository.
2. Converts MDX to Lexical format.
3. Stores the converted docs in the CMS.
4. Revalidates the frontend documentation pages.

To enable GitHub synchronization, configure the following environment variables in your .env file:

# For reading from GitHub
GITHUB_ACCESS_TOKEN=ghp_
GITHUB_CLIENT_SECRET=

# For writing to GitHub
COMMIT_DOCS_API_URL=
COMMIT_DOCS_API_KEY=

The internal LiveLogs component manages the WebSocket connection to fetch logs for a specific deployment type (BUILD or DEPLOY).

WebSocket URL Construction

The component connects to a WebSocket endpoint derived from the NEXT_PUBLIC_CLOUD_CMS_URL environment variable. The URL is constructed as follows:

ws://{CLOUD_CMS_URL_WITHOUT_HTTP}/api/deployments/{deploymentID}/logs?logType={type}&env={environmentSlug}

Log Message Handling

When a message is received via WebSocket, the component expects a JSON payload with the following structure:

{
  "data": [ ... ],
  "logType": "historic" | "live"
}

• logType: 'historic': The received logs replace the current log state.
• logType: 'live': The received logs are appended to the existing log list.

Logs are processed through the styleLogs utility before being rendered by the SimpleLogs component.

The website supports rendering different versions of documentation using specific environment variables:

Beta Docs

• Enable beta docs: Set NEXT_PUBLIC_ENABLE_BETA_DOCS=true.
• Specify version: Set NEXT_PUBLIC_BETA_DOCS_REF to a branch, commit, or tag (defaults to beta).

Legacy Docs

• Enable legacy docs: Set NEXT_PUBLIC_ENABLE_LEGACY_DOCS=true.
• Specify version: Set NEXT_PUBLIC_LEGACY_DOCS_REF to a branch, commit, or tag (defaults to null, which falls back to the main branch).

When type="reference" is used, CMSLink resolves the href based on the relationTo field in the reference object:

• pages: Attempts to use the last item in the breadcrumbs array to find the url. If breadcrumbs are unavailable, it falls back to /${relationTo}/${value.slug}.
• posts: Resolves to /blog/${value.slug}.
• case_studies: Resolves to /case-studies/${value.slug}.
• Other collections: Falls back to the pattern /${relationTo}/${value.slug}.

Note: The value in the reference can be either a full object (containing slug, breadcrumbs, etc.) or a simple string ID.

The deployment system uses specific status strings to determine the UI state. The InfraOnline component categorizes these into 'final' stages to decide if a deployment is considered successful or failed.

Final Deployment Stages

Statuses that represent a completed state:

• ACTIVE (considered 'Online/Success')
• SUPERSEDED (considered 'Online/Success')

Other Statuses

• Success/Progressing: BUILDING, DEPLOYING (shown with a spinner)
• Pending: PENDING_BUILD, PENDING_DEPLOY (shown with a spinner)
• Error/Failure: ERROR, CANCELED (shown as 'Offline/Error')