Configuration #

Glaze reads project configuration from glaze.neon in your project root. It uses NEON format – the same format used for page frontmatter.

A glaze.neon file is optional. Start minimal and add settings only when you need them.

Full example #

pageTemplate: page

paths:
  content: content
  template: templates
  static: static
  public: public
  extensions: extensions

site:
  title: My Site
  description: Notes on web, PHP, and experiments.
  baseUrl: https://example.com
  basePath: /blog
  meta:
    robots: index,follow
    og:type: website

images:
  driver: gd
  presets:
    thumb:
      w: 320
      h: 180
      fit: crop
    hero:
      w: 1200
      h: 630

taxonomies:
  tags:
    generatePages: true
    basePath: /tags
    termTemplate: taxonomy/tags-term
    listTemplate: taxonomy/tags-list
  categories:
    generatePages: false

contentTypes:
  blog:
    paths:
      - match: blog
        createPattern: blog/{date:Y/m}
    defaults:
      template: blog
      draft: false

  docs:
    paths:
      - match: docs
    defaults:
      template: docs

djot:
  xhtml: false
  significantNewlines: false
  profile: null
  codeHighlighting:
    enabled: true
    theme: nord
    themes:
      dark: github-dark
      light: github-light
    withGutter: false
  headerAnchors:
    enabled: false
    symbol: "#"
    position: after
    cssClass: permalink-wrapper
    ariaLabel: Anchor link
    levels: [1, 2, 3, 4, 5, 6]
  autolink:
    enabled: false
    allowedSchemes: [https, http, mailto]
  externalLinks:
    enabled: false
    internalHosts: []
    target: _blank
    rel: noopener noreferrer
    nofollow: false
  smartQuotes:
    enabled: false
    locale: null
  mentions:
    enabled: false
    urlTemplate: '/users/view/{username}'
    cssClass: mention
  semanticSpan:
    enabled: false
  defaultAttributes:
    enabled: false
    defaults: {}

build:
  clean: false
  drafts: false
  vite:
    enabled: false
    command: "npm run build"
    assetBaseUrl: /
    manifestPath: public/.vite/manifest.json
    defaultEntry: assets/css/site.css

devServer:
  php:
    host: 127.0.0.1
    port: 8080
  vite:
    enabled: false
    host: 127.0.0.1
    port: 5173
    url: http://127.0.0.1:5173
    injectClient: true
    defaultEntry: assets/css/site.css
    command: "npm run dev -- --host {host} --port {port} --strictPort"

i18n:
  defaultLanguage: en
  languages:
    en:
      label: English
      urlPrefix: ""
    nl:
      label: Nederlands
      urlPrefix: /nl
      contentDir: content/nl

`pageTemplate` #

Default Sugar template name used to render pages. The value is a template name without the .sugar.php extension, resolved relative to paths.template (default: templates).

pageTemplate: page

This means pages render with templates/page.sugar.php unless a per-page template frontmatter value overrides it.

`paths` #

Configure key project directories in one place.

paths:
  content: content
  template: templates
  static: static
  public: public
  extensions: extensions
  translations: i18n

content – content source directory (used for page discovery)
template – Sugar template directory (used by page rendering)
static – static asset source directory copied during builds
public – build output directory
extensions – project extension auto-discovery directory
translations – directory containing NEON translation files (see Internationalization)

Values can be relative to the project root or absolute paths:

paths:
  template: /my/absolute/path
  static: myStatic

`site` #

Global site metadata. All values are available in templates as properties on the $site object.

title – site name; used in <title> tags and headings
description – default meta description
baseUrl – canonical base URL (used for sitemaps, feed links, etc.)
basePath – URL prefix for subfolder deployments (e.g. /blog); prepended to all generated links

`images` #

Controls League Glide image transform behavior.

`images.driver` #

PHP image processing driver. Supported values: gd (default), imagick.

images:
  driver: imagick

`images.presets` #

Named transform presets. Each preset is a map of Glide parameters. Use a preset in content or templates with ?p=name (or ?preset=name).

images:
  presets:
    thumb:
      w: 320
      h: 180
      fit: crop
    hero:
      w: 1200
      h: 630
      fm: webp

Raw query parameters still work when presets are defined. Raw values override preset values when both are present in the same URL.

`taxonomies` #

Declares which frontmatter keys are treated as taxonomy fields. Values are extracted from page frontmatter, indexed during build, and made available through collection query helpers in templates.

The default taxonomy when no taxonomies key is present in glaze.neon is tags.

See Taxonomies for a full reference including template query examples.

Simple list syntax #

taxonomies:
  - tags
  - categories

With this config, tags: [php, oss] in a page’s frontmatter becomes accessible via $this->taxonomyTerm('tags', 'php') in templates.

Map syntax #

The map syntax enables per-taxonomy options:

taxonomies:
  tags:
    generatePages: true
    basePath: /tags
    termTemplate: taxonomy/tags-term
    listTemplate: taxonomy/tags-list
  categories:
    generatePages: false

Option	Default	Description
`generatePages`	`false`	Auto-generate a list page and one term page per distinct term
`basePath`	`/{name}`	URL prefix for generated pages (e.g. `/tags`)
`termTemplate`	`taxonomy/term`	Sugar template for individual term pages
`listTemplate`	`taxonomy/list`	Sugar template for the taxonomy list (all terms) page

Both syntax styles may be mixed in the same config. A bare key with no options (categories: {}) is equivalent to generatePages: false.

`contentTypes` #

Classifies pages by path prefix and optionally applies metadata defaults.

contentTypes:
  blog:
    paths:
      - match: blog
        createPattern: blog/{date:Y/m}
    defaults:
      template: blog
      draft: false

`paths` #

Each entry under paths is a rule with two keys:

match (required) – path prefix; pages whose relativePath starts with this value are assigned to this type
createPattern (optional) – path template used by glaze new when creating a page of this type

createPattern supports the {date:FORMAT} placeholder, which is replaced with today’s date formatted using PHP date format characters:

createPattern: blog/{date:Y/m}
# creates pages under: blog/2026/02/

createPattern: posts/{date:Y}
# creates pages under: posts/2026/

Shorthand path entries (a plain string instead of a map) are also supported and behave as a match-only rule with no createPattern:

contentTypes:
  docs:
    paths:
      - docs

`defaults` #

A metadata map merged into all pages of this type, before page frontmatter is applied. Page frontmatter always wins over type defaults.

defaults:
  template: blog
  draft: false
  meta:
    layout: wide

Explicit type override in frontmatter #

A page can declare its type directly in frontmatter, bypassing path matching:

---
type: blog
title: My post
---

The resolved type is available in templates as $page->type.

`djot` #

Djot rendering options live under the djot key. This covers syntax highlighting, heading anchors, table of contents, source includes, autolink, external links, smart quotes, mentions, semantic spans, and default attributes.

See Djot for the full reference.

`paths.extensions` #

Directory Glaze scans for classes decorated with #[GlazeExtension]. Relative to the project root. Defaults to extensions.

paths:
  extensions: extensions

Classes carrying #[GlazeExtension('name', helper: true)] in this directory are auto-registered as template helpers callable from templates as $this->extension('name'). Classes with only #[ListensTo] methods are registered as event subscribers. See Extensions for full details.

`extensions` #

Opt-in list of named extensions to activate. Entries can be a core extension name, a project extension name (matching the name in its #[GlazeExtension] attribute), or a fully-qualified class name.

extensions:
    - sitemap
    - llms-txt

Pass options to configurable extensions using the map form:

extensions:
    my-extension:
        apiKey: abc123

See Core extensions for the full list of built-in extensions and their configuration options.

`devServer.php` #

Optional defaults for glaze serve host and port.

devServer:
  php:
    host: 127.0.0.1
    port: 8080

host – default host interface for the PHP built-in server
port – default port for the PHP built-in server

CLI options override these values (--host, --port).

`devServer.vite` #

Optional settings for glaze serve --vite in live mode.

devServer:
  php:
    host: 127.0.0.1
    port: 8080
  vite:
    enabled: false
    host: 127.0.0.1
    port: 5173
    url: http://127.0.0.1:5173
    injectClient: true
    defaultEntry: resources/js/app.ts
    command: "npm run dev -- --host {host} --port {port} --strictPort"

enabled – opt-in default for Vite integration (false by default)
host – Vite host interface
port – Vite port
url – explicit Vite dev server URL used by template integration (optional; defaults to http://{host}:{port})
injectClient – inject @vite/client automatically in development mode (true by default)
defaultEntry – default entry used by s:vite when no entry argument is passed
command – command template used to start Vite; {host} and {port} are replaced at runtime

CLI options always override these values (--vite, --vite-host, --vite-port, --vite-command).

`build` #

Optional defaults for glaze build options.

build:
  clean: false
  drafts: false
  vite:
    enabled: false
    command: "npm run build"
    assetBaseUrl: /
    manifestPath: public/.vite/manifest.json
    defaultEntry: assets/css/site.css

clean – clean output directory before build (false by default; --clean forces it for a single run)
drafts – include drafts during build (equivalent to --drafts)
vite.enabled – opt-in default for Vite build integration (false by default)
vite.command – command used to run Vite build in the project root
vite.assetBaseUrl – base URL for emitted production assets in template tags
vite.manifestPath – path to Vite manifest used for production template rendering
vite.defaultEntry – default entry used by s:vite in production mode

CLI options override these values (--clean, --drafts, --vite, --vite-command).

`build.vite` #

Nested Vite build settings under build.

build:
  vite:
    enabled: false
    command: "npm run build"
    assetBaseUrl: /
    manifestPath: public/.vite/manifest.json
    defaultEntry: css/site.css

enabled – opt-in default for Vite build integration (false by default)
command – command used to run Vite build in the project root
assetBaseUrl – base URL used for generated script/link tags in production mode
manifestPath – manifest file path for Vite production assets
defaultEntry – default entry used when s:vite receives no explicit entry

Vite scaffold + template integration #

Glaze can scaffold and wire Vite support with one command:

glaze init my-site --preset vite

This creates vite.config.js, package.json, and enables Vite defaults in glaze.neon.

In templates, use Sugar’s s:vite directive:

<s-template s:vite="'assets/css/site.css'" />

Live mode (glaze serve --vite) renders dev server tags, while static build mode renders production tags from the configured manifest.

`i18n` #

Enable multilingual support. Only activates when defaultLanguage is set.

See Internationalization for a full setup guide, directory structure examples, and the complete template helper reference.

Notes #

A missing glaze.neon is valid; Glaze uses sensible defaults.
Unknown top-level keys are ignored.

Configuration #

Full example #

pageTemplate #

paths #

site #

images #

images.driver #

images.presets #

taxonomies #

Simple list syntax #

Map syntax #

contentTypes #

paths #

defaults #

Explicit type override in frontmatter #

djot #

paths.extensions #

extensions #

devServer.php #

devServer.vite #

build #

build.vite #

Vite scaffold + template integration #

i18n #

Notes #

`pageTemplate` #

`paths` #

`site` #

`images` #

`images.driver` #

`images.presets` #

`taxonomies` #

`contentTypes` #

`paths` #

`defaults` #

`djot` #

`paths.extensions` #

`extensions` #

`devServer.php` #

`devServer.vite` #

`build` #

`build.vite` #

`i18n` #