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 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
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
!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
Returns the document's basename.
A document's basename is its filename without the extension.
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
Returns the document's relative path within the collection.
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.yaml, or the pod's
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
Returns the document's path format, which the router uses to generate the
Url object. The path format is specified in the
key of the document's fields, or if absent, inherited from the
_collection.yaml. For localized documents, the
is used instead of the
$path key. If no
is specified, the
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
undefined is returned.
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
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 whether a document is servable, given a pod path.
The pod path of the document.
Lists documents using glob patterns, as outlined by the
Note the following behavior:
Various techniques can be used to list docs depending on your needs:
// All docs within the "pages" collection:
// Only Markdown docs within the "pages" collection:
// All docs within both the "pages" and "posts" collections:
Document.list(pod, ['/content/pages/**', '/content/posts/**'])
// All Markdown docs within the entire pod:
// All docs named `index.yaml` within the entire pod:
The pod object.
A list of glob patterns or a single glob pattern. If nothing is supplied, all docs within the pod will be returned.
Generated using TypeDoc