Configure your Starport site

Overview

After Promptless completes your onboarding, you maintain the site’s settings yourself. Most of them live in two places: astro.config.mjs for the site’s structure and appearance, and environment variables for values that change per environment. Promptless sets working values during onboarding, so change a setting here only when you want the site to behave differently. For the managed setup that comes first, see How Starport works and Migrate to Starport.

Before you start

• Write access to your Starport site’s Git repository.
• Access to your hosting provider’s environment variables for the site, such as your Vercel project’s settings. The default publish workflow pulls the production environment from Vercel when it builds.
• For local builds, a .env file copied from .env.example. Git ignores .env, so values in it apply only to builds on your machine.

Set site metadata

The site’s identity comes from four environment variables. Each one falls back to a default in astro.config.mjs when it’s unset.

Variable	What it sets
SITE_URL	The canonical URL, which the sitemap and OpenGraph links also use.
SITE_TITLE	The site title.
SITE_DESCRIPTION	The site description.
EDIT_LINK_BASE_URL	The repository and branch that each page’s edit link points to.

1. In your hosting provider’s environment variables, set the variables you want to change.

2. Optional. To build with the same values locally, set them in .env:

   .env

   SITE_URL=https://docs.your-company.com
   SITE_TITLE=Your Docs
   SITE_DESCRIPTION=Product documentation for your product.
   EDIT_LINK_BASE_URL=https://github.com/your-org/your-repo/edit/main/

3. Redeploy the site so the build picks up the new values.

Set branding

1. In public/, replace logo.svg and favicon.svg with your own files. astro.config.mjs points the logo and favicon options at them.

2. In src/styles/custom.css, set your brand color in the --sl-color-accent token family: --sl-color-accent, --sl-color-accent-low, and --sl-color-accent-high.

3. In the same file, set your typeface with the --sl-font token.

4. Under the :root[data-theme='dark'] selector, set the dark-mode accent values.

5. Check color contrast in both light and dark mode.

Configure search

Site search is on by default and needs no credentials. These starlightSearch() options in astro.config.mjs tune it:

Option	What it controls
ranking.fields	How much each field counts toward a match. The fields are title, description, heading, and body, weighted 4, 3, 2, and 1 by default.
starterLinks	Up to four suggested destinations per language that seed the empty search box. Each one must point to a published page.
exclude	Exact paths, or prefixes ending in /*, to keep out of the search index.

1. In astro.config.mjs, edit the starlightSearch() options.

2. Rebuild the site with npm run build. The build regenerates the search index.

Turn on the site assistant

The optional site assistant answers reader questions from your published pages. It runs on Anthropic models through your own Anthropic account, and it runs on Vercel. See Agent-ready docs for what readers see.

1. In your Anthropic account, create an API key.

2. In your hosting provider’s environment variables, set ANTHROPIC_API_KEY for both build and runtime. On Vercel, add it to Production, and to Preview if you test there. Leave off any PUBLIC_ prefix, so the key stays on the server.

3. Optional. Set STARPORT_ASSISTANT_MODEL to choose a different model than the default, claude-sonnet-5. The model must support Anthropic’s effort parameter.

4. Redeploy the site. The template turns on the assistant when the build finds the key.

ANTHROPIC_API_KEY=your-anthropic-api-key
STARPORT_ASSISTANT_MODEL=claude-sonnet-5

Caution

Each question the assistant answers calls your Anthropic account. The site limits each IP address to 20 questions every ten minutes, per server instance. That limit isn’t a spending cap, so set usage limits in your Anthropic account.

Without the key, site search still runs and the assistant stays hidden. After you remove the key, rebuild the site to hide the assistant.

Configure the API reference and page actions

The OpenAPI reference reads one entry per API from the starlightOpenAPI([...]) array in astro.config.mjs. Each entry has a base path, a label, and a schema file.

1. Add the API’s OpenAPI spec file to the openapi/ directory.

2. In the starlightOpenAPI([...]) array, add an entry with its base, label, and schema. Each entry gets its own sidebar group.

3. To drop an API, remove its entry.

Page actions take a position setting and an actions list that turns each action on or off, in the starlightPageActions() options.

Author redirects

Author redirects in redirects.json when a page moves or a URL changes.

1. In redirects.json, add a source and destination pair to the redirects array:

   {
     "redirects": [
       { "source": "/old-guide", "destination": "/docs/new-guide" }
     ]
   }

2. Run npm run build. The build first runs build:redirects, which writes each pair into vercel.json as a permanent redirect.

If you deploy somewhere other than Vercel, adapt scripts/build-redirects.ts to your host’s redirect format.

Configure deploy settings

Starport deploys to Vercel through .github/workflows/publish.yml on every merge to main. The template’s README also documents how to deploy to GitHub Pages and Cloudflare Pages.

1. In your GitHub repository’s Actions secrets, set VERCEL_TOKEN, VERCEL_ORG_ID, and VERCEL_PROJECT_ID. The token comes from your Vercel account, and the two IDs come from .vercel/project.json after you run vercel link. The workflow skips the deploy until all three are set.

2. In your GitHub repository’s Actions variables, set AFDOCS_URL to your published site’s URL so the daily afdocs check runs.

3. Optional. In your hosting provider’s environment variables, set the docs MCP server’s options:

   MCP_ENABLED=true
   MCP_RUNTIME=vercel

   MCP_ENABLED defaults to true. Set it to false to turn off the docs MCP server and build a fully static site. The MCP server needs an on-demand runtime, which MCP_RUNTIME selects. It defaults to vercel, the verified runtime.

Your hosting provider handles your custom domain and its TLS certificate, outside the repository.

To let Promptless read whether each deploy succeeded, connect Vercel or Cloudflare Pages read-only on the integrations page. That connection only reads deploy status. Your CI uses the VERCEL_* secrets to publish. See Monitor a Starport site through read-only connections.

Run checks before you merge

Run the same checks your CI runs before you merge a change:

1. Run npm run check to typecheck, test, and build the site.

2. Run npm run lint:md to lint Markdown structure.

3. Run npm run lint:frontmatter to validate frontmatter. This script needs Node 24 or newer. The other scripts run on Node 22.12 or newer.

4. Run vale src/content to lint prose.

These files configure the build and its checks:

File	What it configures
package.json	The scripts, such as dev, build, preview, check, and build:pdf.
pdf-exports.json	The named PDF export sets, each with a name and its entry points.
docmeta.config.yaml	Frontmatter validation.
.vale.ini	Prose linting.
.remarkrc.mjs	Markdown structure linting.

See also

• Agent-ready docs, for what the docs MCP server, page actions, and site assistant give readers and agents.
• Starport analytics, to send search and assistant events to your analytics provider.
• Monitor a Starport site through read-only connections, to let Promptless read deploy status and reader analytics.