YAML types
Amagaki treats custom YAML types as first-class citizens so you can model references, partials, translations, and environment/locale conditionals directly inside your content files — without hardcoding URLs or paths.
Built-in YAML types
| Tag | Syntax | Description |
|---|---|---|
!pod.doc |
!pod.doc '/content/pages/about.yaml' or !pod.doc ['/content/pages/about.yaml', !pod.locale 'de'] |
Resolves to a Document object. |
!pod.docs |
!pod.docs ['/content/posts/**', {sort: 'order'}] |
Resolves to an array of Document objects. |
!pod.collection |
!pod.collection '/content/posts' |
Resolves to a Collection object. |
!pod.collections |
!pod.collections ['/content/**', {sort: 'order'}] |
Resolves to an array of Collection objects. |
!pod.staticFile |
!pod.staticFile '/static/images/logo.svg' |
Resolves to a StaticFile object. |
!pod.string |
!pod.string 'Hello' or !pod.string {value: 'Old', prefer: 'New'} |
Resolves to a TranslationString localized for the current document. |
!pod.yaml |
!pod.yaml '/content/partials/nav.yaml' or !pod.yaml '/content/data.yaml?footer.links' |
Loads a YAML file (with optional ?dot.path query). |
!pod.locale |
!pod.locale 'ja' |
Resolves to a Locale object. |
!pod.locales |
!pod.locales ['en', 'de', 'ja'] |
Resolves to a LocaleSet of Locale objects. |
!pod.meta |
!pod.meta 'siteTitle' |
Reads a key from pod.meta configured in amagaki.ts. |
!pod |
!pod 'basePath' |
Reads a property directly from the Pod instance. |
!IfEnvironment |
!IfEnvironment {default: 'a', prod: 'b'} |
Returns the value matching pod.env.name, falling back to default. |
!IfLocale |
!IfLocale {default: 'a', ja: 'b'} |
Returns the value matching doc.locale.id, falling back to default. |
Examples
Referencing documents and collections
# Single document
home: !pod.doc '/content/pages/index.yaml'
# Single document in a specific locale
homeDe: !pod.doc ['/content/pages/index.yaml', !pod.locale 'de']
# Explicit list of documents
featured: !pod.docs ['/content/pages/index.yaml', '/content/posts/launch.md']
# Glob with options
posts: !pod.docs ['/content/posts/**', {sort: 'order'}]
Partial YAML & dot-path queries
# Load an entire partial file
header: !pod.yaml '/content/partials/header.yaml'
# Load a nested key from a YAML file
primaryCta: !pod.yaml '/content/partials/ctas.yaml?signup.button'
Environment and locale conditionals
analyticsId: !IfEnvironment
default: ''
staging: 'G-STAGING'
prod: 'G-PROD'
heroImage: !IfLocale
default: !pod.staticFile '/static/images/hero-en.png'
ja: !pod.staticFile '/static/images/hero-ja.png'
Custom YAML types
You can define your own YAML tags in amagaki.ts or a plugin (for example, to validate structured components or fetch data from an external CMS).