Configure Sveltia

Sveltia CMS is generated from site.config.yaml. The old public/admin/config.yml file is no longer edited by hand.

FrontMark exposes generated admin files:

URL	Purpose
`/frontmark/admin/config.json`	JSON config loaded by Sveltia.
`/frontmark/admin/config.yml`	YAML view of the same generated config.
`/frontmark/admin/sveltia-cms.js`	Sveltia bundle from `@sveltia/cms`.

The default build is static. In that mode, these files are generated at build time and Sveltia uses Forgejo OAuth through the dedicated OAuth/API proxy. Token sign-in remains available as a fallback method.

Central Settings

Configure the public site, the Forgejo instance and the OAuth application in one file:

site:
  base: /frontmark
  url: https://example.com

git:
  provider: forgejo
  origin: https://yourgitinstance.example.com
  repository: sigMAX/Image_frontmark
  repositoryUrl: https://yourgitinstance.example.com/sigMAX/Image_frontmark
  branch: main
  appId: 00000000-0000-0000-0000-000000000000

These fields generate the Sveltia backend values:

`site.config.yaml` field	Generated Sveltia field	Example result
`git.repository`	`backend.repo`	`sigMAX/Image_frontmark`
`git.branch`	`backend.branch`	`main`
`site.url` + `site.base`	`backend.api_root`	`https://example.com/frontmark/api/forgejo/v1`
`site.url` + `site.base`	`backend.base_url`	`https://example.com/frontmark/oauth/forgejo`
`admin.authEndpoint`	`backend.auth_endpoint`	`login/oauth/authorize`
`git.appId`	`backend.app_id`	`00000000-0000-0000-0000-000000000000`
`admin.authMethods`	`backend.auth_methods`	`oauth`, `token`

Sveltia receives values equivalent to:

backend:
  name: gitea
  repo: sigMAX/Image_frontmark
  branch: main
  api_root: https://example.com/frontmark/api/forgejo/v1
  base_url: https://example.com/frontmark/oauth/forgejo
  auth_endpoint: login/oauth/authorize
  app_id: 00000000-0000-0000-0000-000000000000
  auth_methods:
    - oauth
    - token

OAuth is the primary method. To build a direct-token-only CMS config for an environment without the OAuth proxy, set SVELTIA_BACKEND_MODE=direct during the build.

OAuth Proxy Routes

Sveltia opens the Forgejo authorization page in a popup, then exchanges the returned code for an access token. Direct browser calls to the Forgejo token endpoint can fail because of CORS or because the OAuth app uses a confidential client secret. FrontMark supports that flow with the dedicated Dockerfile.oauth container.

The real Forgejo instance is:

https://yourgitinstance.example.com

The generated CMS config uses these public routes:

Sveltia URL	Forwarded to
`https://example.com/frontmark/api/forgejo/v1/*`	`https://yourgitinstance.example.com/api/v1/*`
`https://example.com/frontmark/oauth/forgejo/login/oauth/authorize`	`https://yourgitinstance.example.com/login/oauth/authorize`
`https://example.com/frontmark/oauth/forgejo/login/oauth/access_token`	`https://yourgitinstance.example.com/login/oauth/access_token`

With the dedicated proxy container, route /frontmark/oauth/forgejo/* and /frontmark/api/forgejo/v1/* to Dockerfile.oauth, and route the rest of /frontmark/* to the static site container. The proxy accepts both Traefik layouts: with /frontmark preserved or stripped before the request reaches the container.

If the Forgejo OAuth application requires a secret, mount it only on the proxy container:

GITEA_CLIENT_SECRET=...

The static site container does not need this secret.

OAuth Application

Create or update the OAuth application in Forgejo with the git.appId value from site.config.yaml.

For a hosted site under /frontmark, add this redirect URI:

https://example.com/frontmark/admin/

For local development, add the local callback too:

http://localhost:4321/frontmark/admin/

If the popup opens http://localhost:4321/... on the hosted site, the deployed app is still serving an old generated config. Rebuild and redeploy with:

make rebuild

OAuth checklist:

Check	Expected value
OAuth client id in Forgejo	Same value as `git.appId`.
Hosted callback	`https://example.com/frontmark/admin/`
Local callback	`http://localhost:4321/frontmark/admin/`
Authorization popup on hosted site	Starts with `https://example.com/frontmark/oauth/forgejo/login/oauth/authorize`.

Collections And Previews

Collections are configured under admin.collections in site.config.yaml.

admin:
  publicFolder: /uploads
  collections:
    - name: docs
      folder: src/content/docs
      previewPath: /docs/{{slug}}/

Field mapping:

`site.config.yaml` field	Generated Sveltia field	Notes
`admin.appTitle`	`app_title`	CMS window title.
`admin.mediaFolder`	`media_folder`	Repository path for uploaded media.
`admin.publicFolder`	`public_folder`	Public URL path; `site.base` is added automatically.
`admin.logo.src`	`logo.src`	Public logo path; `site.base` is added automatically.
`admin.slug.encoding`	`slug.encoding`	Slug encoding strategy.
`admin.slug.cleanAccents`	`slug.clean_accents`	Converts accents before slug creation.
`admin.slug.sanitizeReplacement`	`slug.sanitize_replacement`	Replacement character for invalid slug characters.
`admin.collections[].previewPath`	`collections[].preview_path`	Public preview URL; `site.base` is added automatically.
`admin.collections[].fields`	`collections[].fields`	Passed directly to Sveltia.

The active site.base is added automatically. With site.base: /frontmark, the generated Sveltia config uses:

public_folder: /frontmark/uploads
preview_path: /frontmark/docs/{{slug}}/

To remove every prefix, set site.base: ""; the generated Sveltia URLs will lose /frontmark automatically.

Debug The Generated Config

Run the site and open the generated config directly:

make dev

Then inspect:

http://localhost:4321/frontmark/admin/config.yml

The generated config should contain FrontMark Forgejo proxy URLs:

api_root: http://localhost:4321/frontmark/api/forgejo/v1
base_url: http://localhost:4321/frontmark/oauth/forgejo

For the direct-token fallback, build with SVELTIA_BACKEND_MODE=direct:

SVELTIA_BACKEND_MODE=direct make build