Going further

This page collects advanced FrontMark operations: compiled Svelte components, optimized assets, cache policy, imports, upgrades, translations, protected content, Sveltia collections and deployment pipelines.

Compile Svelte components

Markdown can mount Svelte components with ::: svelte. The source files live in svelte-components/src/** and are compiled to public/svelte/ before Astro builds the site.

make svelte

During component development, run the watcher beside make dev:

make svelte_watch

make build, make preview and both Docker image builds compile the Svelte bundle before Astro. See Svelte Components for directive syntax and component configuration examples.

Optimize public images

FrontMark optimizes local PNG, JPEG and WebP images at build time with Sharp. Originals stay in place, generated variants go to public/_optimized/, and Markdown keeps referencing canonical public paths.

make optimize

make build, make preview and Docker builds run optimization before Astro. Existing variants are reused when the source image and image configuration have not changed.

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
  skip:
    max_width_below: 300
    size_below_kb: 15
    extensions:
      - svg
      - gif

Available profiles are balanced, documentation, screenshots, photos, lossless, brand, logos, icons and bypass. Use screenshots for captures containing text, photos for stronger compression, and lossless or bypass for brand-sensitive assets.

Configure static Nginx cache

Static Docker images generate nginx.conf 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
      stable_asset_paths:
        - /brand/
        - /documents/
        - /favicon.ico
        - /favicon.svg
        - /icons/
        - /images/
        - /media/
        - /scripts/
        - /styles/
        - /uploads/
        - /videos/

Use immutable caching only for URLs that change when content changes: /_astro/, optimized image variants and /admin/sveltia-cms.js?v=<content-hash>. Keep HTML, manifests, admin config and stable asset paths in no-cache; Nginx sends ETag/Last-Modified validators so browsers revalidate changed files cleanly.

Import a MkDocs Material site

Use the importer when an existing MkDocs Material project must become a FrontMark/Starlight site:

make import /path/to/mkdocs-site
make import MKDOCS=/path/to/mkdocs-site
make install import /path/to/mkdocs-site

The make install import /path/to/mkdocs-site form bootstraps dependencies first, then runs the same import. The importer reads mkdocs.yml or mkdocs.yaml, then copies the MkDocs docs_dir into FrontMark-friendly locations.

Source item	Imported behavior
`index.md`	Imported as the documentation entry page, with generated frontmatter when needed.
Markdown subfolders	Imported recursively, with slugified file and folder names.
`documents/`	Copied to `public/documents/`.
`images/`	Copied to `public/images/`.
`videos/`	Copied to `public/videos/`.
`tags.md`	Ignored, because FrontMark builds its own tag index.
`overrides/`, `js/`, `css/`	Ignored, because FrontMark owns rendering, scripts and styles.

The importer updates site.config.yaml with portable MkDocs values only.

Config item	Imported behavior
`site_name`, `site_url`, `site_description`, `site_author`, `copyright`	Mapped to FrontMark site, SEO and brand metadata.
`theme.logo`, `theme.favicon`, `theme.language` or `theme.locale`	Mapped to FrontMark brand and language settings.
`nav`	Converted to `menus.sidebar`.
Existing `astro.menu.links`	Preserved during import.
Previous-menu comments from `make erase-all`	Removed when `site.config.yaml` is rewritten.
Analytics IDs found in `ga.js`	Mapped to `analytics.ids`.
`extra.consent`	Normalized to FrontMark consent keys.
Public `encryptcontent` UI labels	Normalized to `security.encryptcontent`.

Run make erase-all before importing when you want a clean navigation state. It resets astro.menu.links and menus.sidebar to empty lists and comments their previous values temporarily; make import then fills menus.sidebar from the MkDocs nav and removes those comments.

Directory entries such as Raquettes a neige: raquettes are expanded from the matching folder. If include_dir_to_nav is configured, reverse_sort_file and reverse_sort_directory are respected so numbered files and folders keep the same ordering as MkDocs.

MkDocs Material features, palette, markdown_extensions, arbitrary extra data, plugin internals, passwords, theme internals, extra_css and extra_javascript are not migrated.

Every imported Markdown page receives at least frontmatter title; description is filled from site_description when the page does not define one. Relative links to copied assets are rewritten to public paths such as /images/photo.jpg, /documents/manual.pdf and /videos/demo.mp4.

Run the importer test after changing import behavior:

make import_test

Upgrade FrontMark core

Use make upgrade to refresh the FrontMark engine of an existing site without replacing local content or central configuration.

make upgrade

By default, the upgrade clones https://gitea.newkube.ia86.cc/sigMAX/Image_frontmark, copies the core implementation over the current project, refreshes the Makefile so the upgrade target itself can evolve, then runs npm install.

Protected paths are skipped:

Protected path	Reason
`site.config.yaml`	Central site configuration stays local.
`VERSION`	Local release/version metadata stays local.
`src/content/`	Markdown pages and collections stay local.
`src/imported/`	Imported MkDocs sidebar and redirects stay local.
`public/brand/`, `public/favicon.ico`, `public/favicon.svg`, `public/styles/overrides.css`	Branding assets and local CSS overrides stay local.
`public/images/`, `public/videos/`, `public/media/`, `public/documents/`, `public/icons/`, `public/uploads/`	Site assets stay local.
`public/scripts/mkdocs-import-config.js`, `public/search/`, `public/admin/`, `public/svelte/`, `dist/`, `.astro/`, `node_modules/`	Generated artifacts stay local or are rebuilt.

Useful variants:

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"

Bundled themes under public/styles/themes/ are part of FrontMark core and are refreshed by make upgrade. Put local CSS changes in public/styles/overrides.css instead.

The left documentation menu is controlled by menus.sidebar.

menus:
  sidebar:
    - label: FrontMark
      items:
        - label: Overview
          link: /docs/
          icon: material-home-outline
        - label: Getting started
          link: /docs/getting-started/
          icon: material-playlist-check
        - label: Going further
          link: /docs/going-further/
          icon: material-rocket-launch-outline

Rules:

link values are written without the public prefix.
site.base is added at build time.
External entries use href and external: true; they are rendered with target="_blank" and do not receive site.base.
icon values use the same icon shortcode style as the imported MkDocs Material content.

Configure visual styles

The active style is selected in site.config.yaml. A style is one folder containing its CSS and optional font files under public/styles/themes/<name>/.

theme:
  defaultMode: auto
  showThemeSwitcher: ondev
  cssOverrides:
    - /styles/overrides.css
  style: sigmax
  availableStyles:
    - name: sigmax
      label: sigMAX
      colorMode: dark
      stylesheet: /styles/themes/sigmax/theme.css
      footer:
        enabled: true
        fullWidthInDoc: true
        alwaysOnTop: true
      i18n:
        visibility: footer
      header:
        minimizeOnScroll: true
        minimizeScrollY: 56

Available bundled styles include sigmax, health, mountains, caving, software and wired. Use theme.defaultMode: auto to follow the active style colorMode, or set dark or light to force the site theme. The top light/dark selector is only usable when the active style declares colorMode: switch.

CSS override files are loaded after the active bundled theme. The default public/styles/overrides.css file is protected from make upgrade, which makes it the safest place for project-specific CSS.

Configure translations

The language selector is generated from i18n.languages. The number of available translation buttons is derived from that list, or limited explicitly with languageCount. Toolbar placement is configured per style with theme.availableStyles[].i18n.visibility.

i18n:
  enabled: true
  provider: google
  defaultLanguage: en
  defaultTextScale: xlarge
  languageCount: 3
  languages:
    - code: en
      label: English
      nativeLabel: English
      flag: GB
    - code: fr
      label: French
      nativeLabel: Francais
      flag: FR

The language and text-size toolbar is marked as notranslate, so Google Translate does not rewrite the controls themselves.

The cookie consent banner is generated from the central YAML configuration.

consent:
  enabled: true
  storageKey: frontmark-cookie-consent
  title: Cookie preferences
  description: FrontMark can store local preferences such as language and text size.
  acceptText: Accept
  rejectText: Reject
  policyLink: /docs/going-further/#cookie-banner
  policyText: Learn more

Encrypt content

FrontMark supports the common mkdocs-encryptcontent-plugin frontmatter pattern. Use password for a page-specific password, or level for a named password stored centrally.

security:
  encryptcontent:
    enabled: true
    rememberPassword: true
    storage: session
    levels:
      demo: frontmark

---
title: Protected page
level: demo
---

The example page is available at Encrypt Content. Its demo password is frontmark.

Configure Sveltia collections

Collections live under admin.collections.

admin:
  mediaFolder: public/uploads
  publicFolder: /uploads
  collections:
    - name: docs
      label: FrontMark Documentation
      folder: src/content/docs
      create: true
      extension: md
      format: frontmatter
      slug: "{{slug}}"
      previewPath: /docs/{{slug}}/
      fields:
        - label: Title
          name: title
          widget: string
        - label: Content
          name: body
          widget: markdown

Important details:

folder points to the repository folder edited by Sveltia.
previewPath is written without /frontmark; the active site.base is added automatically.
publicFolder is also written without /frontmark; the generated Sveltia config adds the base.
mediaFolder is the repository path where uploaded files are committed.
fields are passed to Sveltia as-is, so nested fields, selects, booleans and lists are defined here.

The broader Sveltia backend setup is documented in Configure Sveltia.

Remove every prefix

To publish the site at the domain root with no /frontmark prefix anywhere, change only site.base:

site:
  base: ""

The build, tag routes, runtime config, Sveltia api_root, Sveltia base_url, public_folder, logo paths and every preview_path are generated from the same configuration. No manual edit is needed in generated runtime files.

After changing the base, rebuild:

make rebuild

Then check the site at /, the documentation at /docs/, the admin at /admin/, and static assets such as /favicon.svg.

Verify generated configuration

After editing site.config.yaml, run:

make rebuild

Then check the generated Sveltia endpoints:

URL with `/frontmark`	Expected result
`/frontmark/admin/config.json`	JSON config consumed by the CMS.
`/frontmark/admin/config.yml`	YAML view useful for debugging.
`/frontmark/admin/sveltia-cms.js`	Sveltia CMS JavaScript bundle.

For a domain-root deployment, use /admin/config.json, /admin/config.yml and /admin/sveltia-cms.js.

Add it to a CI/CD pipeline

Use Make commands in CI:

steps:
  - name: Install dependencies
    run: make install

  - name: Build site
    run: make build

For Docker deployments:

make image IMAGE=registry.example.com/frontmark:latest
docker push registry.example.com/frontmark:latest

The default Dockerfile builds the fully static variant: Svelte is compiled, tags are generated, images are optimized, Astro writes static files, the CMS config is generated for Forgejo OAuth through the dedicated proxy, and Nginx serves the prepared static root. Cache headers are generated from runtime.nginx.cache.

Behind Traefik, keep site.base equal to the public prefix, for example /frontmark. The static Nginx runtime accepts both upstream shapes: Traefik can preserve the PathPrefix("/frontmark") path, or an existing StripPrefix("/frontmark") middleware can strip it before the request reaches the container.

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

make image IMAGE=registry.example.com/frontmark:latest
make image_oauth OAUTH_IMAGE=registry.example.com/frontmark-oauth:latest
docker push registry.example.com/frontmark:latest
docker push registry.example.com/frontmark-oauth:latest

Route these Traefik prefixes to the OAuth proxy service:

Public path	Service
`/frontmark/oauth/forgejo/*`	OAuth/API proxy container.
`/frontmark/api/forgejo/v1/*`	OAuth/API proxy container.
`/frontmark/*`	Static FrontMark container.

The proxy container accepts both Traefik modes: preserving /frontmark or using StripPrefix("/frontmark"). Configure PUBLIC_GIT_ORIGIN when the Gitea/Forgejo origin should come from the environment instead of site.config.yaml.

Going further

Going further

Compile Svelte components

Optimize public images

Configure static Nginx cache

Import a MkDocs Material site

Upgrade FrontMark core

Configure navigation

Configure visual styles

Configure translations

Cookie banner

Encrypt content

Configure Sveltia collections

Remove every prefix

Verify generated configuration

Add it to a CI/CD pipeline