• Public
  • Public/Protected
  • All

Documents represent dynamically rendered pages. The document object controls all aspects of rendering itself, with references to things like its template renderer, its locale, and its content type. A document is defined by a content file within the pod's content directory.

The structure of a document's content comes in two parts: fields and body. fields represent either a full YAML document, or YAML front matter. For Markdown and HTML-formatted documents, a document's body is everything below the front matter delimiter (---) or the entire file contents in absence of a front matter delimiter. YAML files may not have a body.

Documents are grouped into collections. A collection is a directory within the pod's content directory. A _collection.yaml file defines a collection.

The same document may be available in multiple locales. Each locale has its own document object (documents are instantiated with both a podPath and a locale parameter). If a locale parameter is not provided, the pod's default locale is used to instantiate the document. Localized documents will automatically resolve any localizable elements (such as !pod.string YAML types or !a.Localized YAML types) to their correct locale.

Finally, documents may or may not actually be bound to routes. In other words, a document can be a partial document and only used as a data source or input for another document, or it might just be hidden. If a document lacks a pathFormat, it won't be generated as an individual route. A document's url object is determined by its own pathFormat and coupled to the pod's router.


  • Document




_content?: string
ext: string
locale: Locale
parts: DocumentParts
pod: Pod
podPath: string
FrontMatterOnlyExtensions: Set<string> = ...
SelfReferencedView: string = 'self'
SupportedExtensions: Set<string> = ...


  • get basename(): string
  • Returns the document's basename.

    A document's basename is its filename without the extension.

    The basename for /content/pages/index.yaml is index.

    Returns string

  • get body(): string
  • Returns the document's collection object. If no _collection.yaml is found within the document's content directory, the directory structure will be walked upwards until locating a _collection.yaml.

    Returns Collection

  • get collectionPath(): string
  • Returns the document's relative path within the collection.

    The collectionPath for /content/pages/sub/path/index.yaml is /sub/path.

    Returns string

  • get content(): string
  • get defaultLocale(): any
  • Returns the default locale for the document. The default locale of a document can be specified one of three ways, in order: $localization?defaultLocale field within the document's fields, the collection's _collection.yaml, or the pod's amagaki.ts.

    Returns any

  • get fields(): any
  • Returns the document's set of locale objects. In order, the locales are determined by the $localization:locales from the document's fields, or if not specified, inherited from the _collection.yaml, or if not specified there, then amagaki.ts.

    Returns Set<Locale>

  • get pathFormat(): any
  • Returns the document's path format, which the router uses to generate the document's actual Url object. The path format is specified in the $path key of the document's fields, or if absent, inherited from the _collection.yaml. For localized documents, the $localization.path key is used instead of the $path key. If no $path or $localization.path is specified, the pathFormat is false.

    Returns any

  • Returns the document's url object by looking it up in the pod's router. If the document has no url (i.e. if it's a partial document or if it's disabled), undefined is returned.

    Returns Url


  • initPartsFromFrontMatter(): DocumentParts
  • render(context?: Record<string, any>): Promise<string>
  • Resolves any async fields. This is commonly used in conjunction with async YAML types. For example, if a YAML type fetches data from an API or loads content asynchronously, resolveFields ensures that the YAML type's promise is resolved. resolveFields is invoked prior to rendering a document, so any async data is immediately available for templates.


    Returns Promise<void>

  • toString(): string
  • isServable(podPath: string): boolean
  • Lists documents using glob patterns, as outlined by the glob module.

    Note the following behavior:

    • Files prefixed with _ are ignored.
    • Only files with supported doc extensions are returned.

    Various techniques can be used to list docs depending on your needs:

    // All docs within the "pages" collection:
    Document.list(pod, '/content/pages/**')

    // Only Markdown docs within the "pages" collection:
    Document.list(pod, '/content/pages/**\/*.md')

    // All docs within both the "pages" and "posts" collections:
    Document.list(pod, ['/content/pages/**', '/content/posts/**'])

    // All Markdown docs within the entire pod:
    Document.list(pod, '**\/*.md')

    // All docs named `index.yaml` within the entire pod:
    Document.list(pod, '**\/index.yaml')


    • pod: Pod

      The pod object.

    • Optional patterns: string | string[]

      A list of glob patterns or a single glob pattern. If nothing is supplied, all docs within the pod will be returned.

    • Optional options: DocumentListOptions

    Returns Document[]

Generated using TypeDoc