Site schema

This schema describes the top-level site.yaml configuration used to build a linked publication: source and output paths, identity, locales, navigation, layouts, and theme settings.

Copy page

Margo site configuration v1

Closed YAML/JSON configuration for a Margo documentation site.

assetsstring
Whether generated pages reference copied assets or embed supported assets.
enum=["local","inline"]; default="local"
base_pathstring
Normalized public path prefix used by routes and canonical URLs.
default="/"; pattern="^(|/.*)$"
bindingsobject
Named host binding declarations keyed by semantic provider kind.
custom_cssarray
Additional local or approved HTTPS stylesheets.
default=[]
- *
  - css_urlstring*
    minLength=1
frameobject
Legacy frame presentation authority; mutually exclusive with layout and shell.
- builtinstring
- commandstring
- go_moduleobject
  - constructorstring*
    minLength=1
  - importstring*
    minLength=1
  - valuesobject
  - versionstring*
    minLength=1
- protocolstring
- valuesobject
layoutobject | object | object
Typed site layout and its closed kind-specific values.
- defaultobject
  - contentobject
    - layoutvalue
      const="article"
  - familiesarray
    minItems=1; uniqueItems=true
  - navigationarray
  - shellboolean
  - sidebarboolean
  - tocboolean
- kindvalue
  const="article"
- valuesobject
  - contentobject
    - layoutvalue
      const="article"
  - familystring
    minLength=1
  - navigationarray
  - shellboolean
  - sidebarboolean
  - tocboolean
localesobject
- defaultstring
  Canonical BCP 47 default locale.
  default="en"; pattern="^[A-Za-z]{2,8}(?:-[A-Za-z0-9]{1,8})*$"
- supportedarray
  Unique canonical BCP 47 locales; must include default.
  minItems=1; uniqueItems=true
navigationobject
- excludearray
  Normalized glob patterns omitted from generated navigation.
  uniqueItems=true
- modestring
  Navigation strategy for the configured site.
  enum=["file-tree"]; default="file-tree"
offlineboolean
Keep the generated publication independent of network fetches.
default=true
outputstring
Normalized relative directory receiving the published artifact tree.
default="dist"; minLength=1
shellobject
Legacy shell presentation authority; mutually exclusive with layout and frame.
- builtinstring
- commandstring
- go_moduleobject
  - constructorstring*
    minLength=1
  - importstring*
    minLength=1
  - valuesobject
  - versionstring*
    minLength=1
- protocolstring
- valuesobject
siteobject*
- base_urlstring
  Optional absolute HTTPS origin used for canonical URLs and feeds.
  format="uri"; pattern="^https://"
- descriptionstring
  Public site description used in page and social metadata.
- homestring
  Markdown path below source used as the public home route.
  default="index.md"; pattern="^(|.*\\.(md|markdown))$"
- iconstring*
  Normalized local favicon or site icon path below the config directory.
  minLength=1
- logostring*
  Normalized local SVG logo path below the config directory.
  minLength=1
- namestring*
  Public site name.
  minLength=1
- repository_urlstring
  Optional absolute HTTPS source repository URL.
  format="uri"; pattern="^https://"
- social_imageobject*
  - altstring*
    Non-empty alternative text for the social preview image.
    minLength=1; maxLength=160
  - pathstring*
    Local JPEG or PNG social preview path; Margo validates a 1280x640 image.
    minLength=1
- versionstring
  Optional release or development label displayed by the site shell.
  maxLength=64
sourcestring*
Normalized relative directory containing Markdown sources.
minLength=1
themeobject
- allow_switch_themeboolean
  default=false
- builtinboolean
  default=false
- color_modestring
  enum=["system","light","dark"]; default="system"
- namestring
  default="modern"; pattern="^[a-z][a-z0-9_-]{0,63}$"
themesarray
Additional local or approved HTTPS theme entries.
default=[]
- *
  - css_urlstring*
    Normalized local stylesheet path or approved HTTPS stylesheet URL.
    minLength=1
  - namestring*
    Lowercase theme identifier.
    pattern="^[a-z][a-z0-9_-]{0,63}$"
  - token_catalogstring*
    Normalized local token catalog path.
    minLength=1
versionvalue*
Exact site configuration contract version.
const=1

Used by

margo site and margo serve.
YAML language-server and editor associations for site.yaml.
margo schema site, which emits the exact embedded bytes.