🧱 Synticore Website Compiler - Project Structure

🎯 Purpose

This page documents the current on-disk structure used by Synticore, including what each folder/file is for, what is generated, and what is safe to delete.

🪵 Two Different Roots To Understand

A. Compiler Root (This Repository)

This is where the Synticore tool itself lives.

Common files/folders:

• gulpfile.js - task definitions and compiler pipeline
• gui.py - GUI application
• config/ - tool-level defaults and app settings
• source/ - bundled resources, custom modules, migration/test data
• wiki/ - documentation pages
• _log/ - compiler-level logs (gulpfile.log, gui.log, setup.log)

B. Project Root (Your Selected Website Project)

This is the website content directory Synticore builds.

By default, examples are:

• example/full
• example/min

The selected project is typically config/settings.json -> dir_recent[0].

🧩 Standard Project Layout

<project>/
  config.json
  config.schema.json          (optional)
  info.json
  in/
    _html/
    asset/
      audio/
      brand/
      css/
      file/
      font/
      font-icon/
      image/
      js/
      module/
      video/
    *.html
    browserconfig.xml
    manifest.webmanifest
    favicon.ico
  out/                        (generated)
  _cache/                     (generated)
    project/
      dependency_graph.json
      file.json
      image_dimension.json
      manifest_html_tags.json
    compiler/
      file.json
  _log/                       (generated)
    task_<task-name>.log
  _package/                   (generated when packaging)

🗂️ Directory And File Responsibilities

📄 config.json

• Project configuration overrides.
• Primary file you edit to control build behavior.
• Read together with tool defaults from config/default/project/config.json.

🧾 Config.Schema.Json (Optional)

• Project-level schema extensions for custom keys.
• Used by GUI config editor for types/tooltips/editor widgets.

🧾 info.json

• Project metadata, including project version.
• Used by version check and migration logic.
• Used by GUI version status display.

📥 in/

• Source input tree.
• Synticore compiles/transforms from here into out/.

🧩 in/_html/

• Partial/template/include material.
• Common place for frame/header/footer include fragments.

🗂️ in/asset/

• Typed asset sources.
• Task groups map to these folders (audio/image/js/css/font/etc).

📤 out/

• Build output tree.
• Deployable static site output.
• Safe to delete (recreated by build tasks).

🧠 _cache/

• Incremental build cache and derived metadata.
• Safe to delete (recreated as needed).
• Used to skip unchanged work and speed rebuilds.
• project/dependency_graph.json stores reference relationships (e.g., HTML -> image/svg) used by watch mode to trigger dependent rebuild tasks.

🧾 _log/

• Per-project task logs.
• Safe to delete.

📦 _package/

• Package output location (zip and/or directory variants depending on config).

🧹 Generated Vs Source (Safe Deletion Guide)

Source files (do not delete unless intentional):

• config.json
• config.schema.json (if you use custom schema)
• info.json
• in/**

Generated/safe-to-delete:

• out/**
• _cache/**
• _log/**
• _package/**

🧭 Naming And Ignore Conventions

• option.path.ignore_prefix (default _) controls automatic ignore behavior for prefixed paths.
• Common pattern: keep partials and non-page content under underscore-prefixed names.
• Sitemap exclusion is controlled via option.path.ignore_sitemap.

✅ Minimal Valid Project Checklist

At minimum, a project should contain:

• config.json
• in/

Recommended:

• info.json
• config.schema.json when custom keys are used

If these are missing, GUI selection and tasks may fail validation.