Getting started

FrontMark is Markdown-first. Use Markdown files for content, site.config.yaml for structure, and make for local commands. The npm scripts stay implementation details behind the Makefile.

Clone the project

git clone https://gitea.newkube.ia86.cc/sigMAX/Image_frontmark
cd Image_frontmark
make install

make install bootstraps Ubuntu/Debian systems with apt-get and macOS with Homebrew. It installs build dependencies, ensures Node.js >=22.12.0 and npm are available, then runs npm install.

On very small Linux base images, install make first:

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 equivalent packages before running make install: ca-certificates, curl, bash, git, make, a C/C++ build toolchain, python3, xz-utils and pkg-config.

Start locally

DevelopmentProduction preview

make dev

Open the URL printed by Astro, usually http://localhost:4321/frontmark/, to work with hot reload.

make preview

make preview cleans generated artifacts, rebuilds the site, then serves the production output.

Use Make commands

Command	Action
`make`	Show available tasks.
`make install`	Install system dependencies, Node.js/npm and project dependencies.
`make dev`	Start the development server.
`make build`	Generate tags, optimize images, build Astro and prepare the static runtime.
`make preview`	Clean, rebuild and preview the static production site.
`make preview_build`	Rebuild the preview output without cleaning first.
`make clean`	Remove generated build/runtime artifacts.
`make tags`	Rebuild `public/search/tags.json`.
`make import /path/to/mkdocs-site`	Import Markdown, public assets and navigation from a MkDocs Material site.
`make erase`	Remove local Markdown and MDX content files under `src/content`, then rebuild tags when npm dependencies are installed.
`make erase-all`	Run `make erase`, reset menus, restore default brand assets, then remove demo media/assets and Supabase Svelte examples.

Advanced commands for Svelte compilation, image optimization, import, upgrade, Docker and CI/CD are documented in Going further.

Configure the site

All structural settings live in site.config.yaml.

Area	Configuration
Public URL and base path	`site.url`, `site.base`
Site name and SEO defaults	`site`, `seo`
Logo, favicon and hero image	`brand`, files under `public/brand/`
Top menu	`astro.menu.links`
Documentation sidebar	`menus.sidebar`
Theme and CSS overrides	`theme`, `theme.css`, `public/styles/overrides.css`
Image optimization	`images`
Static Nginx cache	`runtime.nginx.cache`
Sveltia collections	`admin.collections`

The most important fields to check before publishing are:

site:
  base: /frontmark
  url: https://example.com
  name: FrontMark Generator

brand:
  logo: /brand/icon.png
  heroImage: /brand/frontmark-hero.png

git:
  origin: https://yourgitinstance.example.com
  repository: sigMAX/Image_frontmark
  repositoryUrl: https://yourgitinstance.example.com/sigMAX/Image_frontmark
  branch: main

Use site.base: "" to publish at the domain root. Use a value such as /frontmark when the site is served under a prefix.

Markdown pages vs Astro pages

Use Markdown files for documentation, editorial pages and content managed through Git or Sveltia.

File or folder	Route	Role
`src/content/docs/*.md`	`/docs/<slug>/`	Documentation pages rendered by Starlight.
`src/content/astro/*.md`	`/<slug>/`	Top-menu pages rendered from Markdown.
`src/content/astro/index.md`	`/`	Markdown content used by the home page.

Use Astro files only when the page itself is application code: custom route logic, generated indexes, API endpoints, wrappers, admin routes or layouts that cannot reasonably be expressed as Markdown content.

Astro-only pages use astro.layout for their readable width:

astro:
  layout:
    mainWidth: 1120px
    contentWidth: 1100px

Use astro.pageWidth or PUBLIC_ASTRO_PAGE_WIDTH when the same width should apply to both values.

Modify the site content

Most edits should happen in Markdown or in site-level configuration.

Area	File or folder	What to change
Documentation pages	`src/content/docs/*.md`	Product documentation, guides and reference pages.
Top-menu pages	`src/content/astro/*.md`	About, contact, home text and other non-doc pages.
Page metadata	Markdown frontmatter	Title, description, tags, ordering metadata and protected-content options.
Sidebar navigation	`site.config.yaml`, `menus.sidebar`	Documentation menu labels, links and icons.
Top navigation	`site.config.yaml`, `astro.menu.links`	Header links such as About, Getting Started and Contact.
Local CSS overrides	`public/styles/overrides.css`	Site-specific CSS loaded after the active theme.
Astro page CSS overrides	`public/styles/astro-overrides.css`	CSS overrides for top-menu Markdown pages.
Theme files	`public/styles/themes/<name>/theme.css`	Bundled theme CSS. Prefer overrides for local project changes.
Images and downloads	`public/images/`, `public/documents/`, `public/uploads/`	Public assets referenced from Markdown.
Brand assets	`public/brand/`, `public/favicon.svg`, `public/favicon.ico`	Logo, icon, favicon and hero image.

Do not edit generated files under dist/, .astro/, public/search/, public/admin/, public/svelte/ or public/_optimized/ by hand. They are recreated by Make commands.

Complete Markdown page example

Create a file such as src/content/docs/deploy-the-portal.md:

---
title: "Deploy the portal"
description: "Build and publish the FrontMark portal behind a reverse proxy."
tags:
  - "deployment"
  - "frontmark"
  - "nginx"
---

# Deploy the portal

This page explains the deployment path used by the team. Keep the source
readable: short sections, normal Markdown links, and public asset paths.

!!! tip "Before you start"
    Run a local preview before publishing so generated tags, optimized images
    and static routes are refreshed.

## Build locally

```sh
make preview
```

Open the preview URL printed by Astro and check the page navigation.

## Add a diagram

![Deployment architecture](/images/deployment/architecture.png){ width="720" }

Use public paths such as `/images/...`, `/documents/...` and `/videos/...`.
FrontMark adds the configured `site.base` during the build.

## Compare commands

| Command | Purpose |
| --- | --- |
| `make dev` | Work with hot reload. |
| `make preview` | Clean, rebuild and preview production output. |
| `make build` | Build the static site for deployment. |

=== "Static site"

    ```sh
    make build
    ```

=== "Docker image"

    ```sh
    make image IMAGE=registry.example.com/frontmark:latest
    ```

## Mount an interactive component

::: svelte { component=modal title="Release checklist" button-text="Open checklist" }
- Verify the public URL.
- Check the generated search index.
- Confirm reverse-proxy cache headers.
:::

## Link to related pages

- [Images](/docs/images-material/)
- [Svelte Components](/docs/svelte-components/)
- [Going further](/docs/going-further/)

Reset local content

Use these commands when a project must be emptied before a fresh import or reset to the reference branding.

make erase removes .md and .mdx files under src/content, then rebuilds the generated tag index when npm dependencies are installed. If dependencies are missing, it prints the make install && make tags recovery command instead of stopping after deletion. The default target root is controlled by CONTENT_MARKDOWN_ROOTS.

make erase-all

make erase-all removes Markdown content, resets astro.menu.links and menus.sidebar to empty lists while keeping their previous values as temporary YAML comments, restores the default brand assets from https://gitea.newkube.ia86.cc/sigMAX/Image_frontmark on the main branch, then removes demo media/assets such as local .mp4, .cast, test.svg, frontmark-hero.png, generated Svelte bundles and Supabase Svelte example sources, while keeping the emptied folders with .keep files. The next make import removes those menu comments after importing the MkDocs navigation. It rebuilds tags when npm dependencies are installed; otherwise it finishes the cleanup and prints the make install && make tags recovery command. This matters for forks: the default branding is fetched from the upstream FrontMark repository, not from the current fork origin.

Preview the result

After editing content, configuration or local overrides, rebuild and preview the complete site:

make preview