Website

Astro website with Starlight documentation 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, SEO defaults, and an optional AssetManager working bucket.

site.animationdelay defines the default delay, in milliseconds, applied when an anim= element enters the viewport. A block-level delay= attribute takes priority. Astro return-to-top visibility can be configured globally with astro.showBackToTop, then overridden per theme with theme.availableStyles[].astro.showBackToTop.

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 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_run	Run the static Docker image for local testing
make image_stop	Stop the local static Docker 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 overwritten: site.config.yaml, src/content/, src/imported/, brand assets such as public/brand/, public/favicon.ico, public/favicon.svg, both local CSS overrides (public/styles/overrides.css and public/styles/astro-overrides.css), site assets such as public/images/, public/videos/, public/media/, public/documents/, public/icons/, public/uploads/, generated runtime/search/svelte output, dist/, .astro/ and node_modules/. Missing site.config.yaml options are added from the reference while existing local values are kept. 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 public/styles/astro-overrides.css"

Upgrades remove the retired private administration engine and its generated files. The migration keeps public settings, authored content, uploads and any existing admin.DefaultBucket value. If the upgrade was launched with an older copy of the upgrade script, run the migration once after that first upgrade:

npm run migrate:legacy-admin -- --dry-run
npm run migrate:legacy-admin

The default Docker image is fully static: Dockerfile builds Astro, optimizes images, 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.

CI/CD pipelines can run docker build -t image-name . for the static image. The Dockerfile compiles Svelte, rebuilds tags and runs image optimization. The displayed version is injected with Docker build args, typically APP_VERSION and VERSION_MAJOR.

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

Keep long immutable caching only for content-versioned URLs: Astro assets and optimized image variants. Keep HTML, manifests 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.

Progressive header and first-screen scrolling

Each entry in theme.availableStyles can define the header position. In addition to true and false, alwaysOnTop: transparent keeps the header fixed and transparent near the top, then restores the selected theme surface after transparentScrollY pixels.

Two responsive variants retain the existing book or sandwich icon and only force its colors on tablet and mobile layouts:

• transparent_white_in_mini: white background with a black icon;
• transparent_black_in_mini: black background with a white icon.

The optional brand.logo2 provides a dedicated logo for that transparent state. Below the threshold the header displays logo2; at and beyond the threshold it switches back to brand.logo. Without logo2, the primary logo is used throughout.

brand:
  logo: /brand/logo.png
  logo2: /brand/logo-transparent.png

theme:
  availableStyles:
    - name: underground
      header:
        alwaysOnTop: transparent
        transparentScrollY: 100
      astro:
        showBackToTop: true

Astro and documentation Markdown pages can override those values in frontmatter. scrollonpage: true turns a downward wheel, touch or keyboard gesture made inside the first root=top section into a responsive smooth move to that section's rendered end. The behavior remains available whenever the visitor returns inside the opening section.

---
layout: full
scrollonpage: true
header:
  alwaysOnTop: transparent
  transparentScrollY: 100
---

The full reference is in src/content/docs/page-shell.md; container placement and root-header options are documented in src/content/docs/containers.md, along with URL or JavaScript actions through onclick and onhover.

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

AssetManager working bucket

The optional admin.DefaultBucket value selects a working bucket for AssetManager. Leave it empty or omit it when no bucket is specified. It does not affect site generation.

admin:
  # Optional working bucket for AssetManager; empty or omitted means no bucket is specified. Does not affect site generation.
  DefaultBucket: ""