Website

Astro website with Starlight documentation, Sveltia CMS administration and a local compatibility layer for MkDocs Material-style Markdown.

Project Structure

The project is an Astro site with Starlight documentation, Svelte islands, lightweight server endpoints and one central configuration file.

/
├── site.config.yaml
├── public/
├── src/
│   └── pages/
│       └── index.astro
└── package.json

Structural site settings live in site.config.yaml: base path, public URL, site name, theme mode, menus, Git repository, Forgejo app id, SEO defaults, and Sveltia CMS collections.

Usage

make is the supported entry point for day-to-day usage. Run every command from the project root.

Command	Action
make	Show available tasks
make install	Install dependencies
make dev	Start the Astro development server
make build	Generate tags, optimize images and build the static site to dist/
make preview	Build, optimize images and preview the static site
make preview_oauth	Run the dedicated Forgejo OAuth/API proxy locally
make rebuild	Clean generated artifacts, then build
make clean	Remove generated build/runtime artifacts
make optimize	Optimize configured public image folders
make images	Alias for make optimize
make image	Build the default static Docker image
make image_oauth	Build the dedicated OAuth/API proxy image
make image_run	Run the static Docker image for local testing
make image_run_oauth	Run the OAuth/API proxy image for local testing
make image_stop	Stop the local static Docker test container
make image_stop_oauth	Stop the local OAuth/API proxy test container
make tags	Rebuild the generated tag index
make status	Show the repository Git status
make astro ARGS="-- --help"	Run the Astro CLI through the Makefile
make import MKDOCS=/path/site	Import a MkDocs site, then rebuild tags
make import_test	Verify the MkDocs Material importer
make upgrade	Upgrade FrontMark core code from reference

The npm scripts remain implementation details used by the Makefile.

MkDocs Material Import

make import MKDOCS=/path/site reads mkdocs.yml or mkdocs.yaml, imports Markdown pages from docs_dir, copies documents/, images/ and videos/, skips tags.md, overrides/, js/ and css/, and updates site.config.yaml with site metadata, logo/language and the sidebar menu derived from nav.

The importer respects include_dir_to_nav sorting options:

plugins:
  - include_dir_to_nav:
      reverse_sort_file: true
      reverse_sort_directory: true

MkDocs Material theme internals, palettes, features, plugins, markdown extensions and extra JavaScript/CSS are not migrated; FrontMark owns those layers.

FrontMark Upgrade

make upgrade updates the FrontMark engine from the reference repository:

make upgrade

It clones https://gitea.newkube.ia86.cc/sigMAX/Image_frontmark, overlays core code, then runs npm install by default.

Protected site-specific paths are not touched: site.config.yaml, Makefile, VERSION, src/content/, src/imported/, and site assets such as public/brand/, public/images/, public/videos/, public/media/, public/documents/, public/icons/, public/uploads/, generated search/admin/svelte output, dist/, .astro/ and node_modules/.

Useful options:

make upgrade UPGRADE_DRY_RUN=1
make upgrade UPGRADE_REF=main
make upgrade UPGRADE_INSTALL=0
make upgrade UPGRADE_REPO=https://example.test/FrontMark.git

The default Docker image is fully static: Dockerfile builds Astro, optimizes images, generates the static CMS files, prepares a prefixed Nginx document root, and serves only files. make image_run exposes the container on http://127.0.0.1:4321. Override the usual Make variables when needed:

make image IMAGE=frontmark-website:test
make image_run IMAGE=frontmark-website:test PORT=4325
make image_stop

When Traefik fronts the static container at a subpath such as /frontmark, keep site.base set to that public prefix. The generated Nginx runtime accepts both common Traefik layouts: a router that preserves PathPrefix("/frontmark"), and a router using StripPrefix("/frontmark"). Route Traefik to the container port 4321; the port does not need to be exposed publicly.

For a static site with OAuth sign-in, build the static image and run the dedicated OAuth/API proxy beside it:

make image IMAGE=frontmark-website:test
make image_oauth OAUTH_IMAGE=frontmark-oauth:test

Route /frontmark/oauth/forgejo/* and /frontmark/api/forgejo/v1/* to the OAuth proxy container, and route the rest of /frontmark/* to the static container. Give the OAuth/API routers a higher priority than the /frontmark/* catch-all. The proxy accepts both Traefik layouts, with or without StripPrefix("/frontmark").

CI/CD pipelines can run docker build -t image-name . for the default OAuth-ready static image and docker build -f Dockerfile.oauth -t oauth-image-name . for the dedicated OAuth/API proxy. The static site Dockerfile compiles Svelte, rebuilds tags, runs image optimization, computes the version tag from Git during the build and stores it in VERSION.

Site Configuration

To build the site under a prefix, change site.base in site.config.yaml:

site:
  base: /frontmark

Use an empty site.base to publish at the domain root:

site:
  base: ""

Then run make build. Set SITE_CONFIG_FILE=/path/to/site.config.yaml when the runtime config is mounted outside the project directory.

Static Docker images generate their Nginx cache policy from site.config.yaml:

runtime:
  nginx:
    cache:
      validation:
        etag: true
        if_modified_since: exact
      html: public, no-cache
      stable_assets: public, no-cache
      optimized_assets: public, max-age=31536000, immutable
      optimized_manifest: public, no-cache
      astro_assets: public, max-age=31536000, immutable
      admin_config: public, no-cache
      cms_bundle: public, max-age=31536000, immutable

Keep long immutable caching only for content-versioned URLs: Astro assets, optimized image variants and the CMS bundle loaded as /admin/sveltia-cms.js?v=<content-hash>. Keep HTML, manifests, admin config and stable public assets in no-cache; browsers may store them, but must revalidate with ETag/Last-Modified before reuse, so a changed file is invalidated cleanly.

Image Optimization

make build, make preview and both Docker builds run make optimize or npm run optimize before Astro. The script scans configured public folders, keeps source files untouched, and writes cacheable variants plus a manifest under public/_optimized/. Hashed variants are served with a one-year immutable cache policy; the manifest is revalidated.

Supported source formats are PNG, JPEG and WebP. SVG, GIF, videos, documents, tiny files and already optimized outputs are skipped by default. Markdown should continue to reference canonical public paths such as /images/schema.png; during the build FrontMark emits AVIF/WebP sources with an optimized original-format fallback when variants exist.

Configure the pipeline in site.config.yaml:

images:
  optimize: true
  mode: build
  output:
    directory: /_optimized
    keep_original_fallback: true
    content_hash: true
  formats:
    - avif
    - webp
    - original
  quality:
    jpeg: 82
    webp: 82
    avif: 68
    png_lossless: true
  folders:
    /images:
      profile: documentation
    /uploads:
      profile: balanced
    /brand:
      profile: lossless
    /icons:
      profile: lossless
    /media:
      profile: balanced

Sveltia CMS

Sveltia configuration is generated from site.config.yaml.

• JSON config: /frontmark/admin/config.json
• YAML config: /frontmark/admin/config.yml
• CMS bundle: /frontmark/admin/sveltia-cms.js

In the default static build these files are generated at build time. OAuth with Forgejo is the primary method, so the generated CMS config points OAuth and API requests to /frontmark/oauth/forgejo and /frontmark/api/forgejo/v1. Token sign-in remains listed as a fallback. The old static files in public/admin/ are generated artifacts and should not be edited by hand.