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 Linux/macOS build tools, Node.js/npm and project dependencies
make dev	Start the Astro development server
make build	Generate tags, optimize images and build the static site to dist/
make preview	Clean, rebuild, 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 /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.

Installation Requirements

make install bootstraps the project on Ubuntu/Debian systems with apt-get and on macOS with Homebrew. It installs build dependencies, ensures Node.js >=22.12.0 and npm are available, then runs npm install. On macOS, Node.js is installed or upgraded with Homebrew. On Linux systems without a recent node, Node.js is installed with nvm.

On a very small base image or server, make itself may be missing. Install it first, then let the project Makefile install the rest:

sudo apt-get update
sudo apt-get install -y make
make install

On macOS, install the Xcode Command Line Tools and Homebrew first if they are missing. Homebrew must be available from the shell, or installed in the standard Apple Silicon (/opt/homebrew) or Intel (/usr/local) location.

xcode-select --install
make install

On other systems, install the equivalent of these packages before running make install: ca-certificates, curl, bash, git, make, a C/C++ build toolchain, python3, xz-utils and pkg-config. make install can still install nvm and Node.js afterwards if curl and bash are available.

make preview is intentionally a clean production preview: it removes generated artifacts, rebuilds Svelte components, tags, optimized images and Astro output, then serves dist/. For a faster rebuild without cleaning first, use make preview_build.

MkDocs Material Import

Use one of these commands to import an existing MkDocs Material site:

make import /path/site
make import MKDOCS=/path/site
make install import /path/site

The make install import /path/site form bootstraps dependencies first, then imports the site in the same run.

The importer:

• reads mkdocs.yml or mkdocs.yaml;
• imports Markdown pages from docs_dir with generated frontmatter when needed;
• copies public assets from documents/, images/ and videos;
• rewrites imported Markdown links to FrontMark routes such as /docs/page/;
• skips tags.md, overrides/, js/ and css/;
• updates site.config.yaml with site metadata, logo/language, portable runtime options and the sidebar menu derived from nav;
• removes previous-menu comments created by make erase-all once site.config.yaml is rewritten.

make import runs make erase-all before importing, after checking that a MkDocs path was provided. This starts from a clean navigation state by emptying astro.menu.links and menus.sidebar, while keeping their previous values as temporary YAML comments. The import then cleans those comments after converting the MkDocs 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, most plugins, markdown extensions and extra JavaScript/CSS are not migrated; FrontMark owns those layers. Portable values such as analytics IDs, extra.consent and public encryptcontent labels are normalized into site.config.yaml, then the build generates public/scripts/mkdocs-import-config.js.

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, refreshes the Makefile so upgrade logic can evolve, then runs npm install by default.

Protected site-specific and branding paths are not touched: site.config.yaml, VERSION, src/content/, src/imported/, brand assets such as public/brand/, public/favicon.ico, public/favicon.svg, the local CSS override public/styles/overrides.css, site assets such as public/images/, public/videos/, public/media/, public/documents/, public/icons/, public/uploads/, generated runtime/search/admin/svelte output, dist/, .astro/ and node_modules/. Bundled themes under public/styles/themes/ are part of FrontMark core and are refreshed by make upgrade.

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
make upgrade UPGRADE_PROTECTED_PATHS="site.config.yaml public/brand public/styles/overrides.css"

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.