Documents, Collections & URLs
Document
Represents a content file (.yaml, .yml, .md, or .html) paired with a Locale. Obtain documents with pod.doc(podPath, locale?) or pod.docs(patterns?, options?).
Static Members
| Member |
Signature / Value |
Description |
Document.list |
list(pod, patterns?, options?): Document[] |
Glob-matches documents under pod.root (supports options.exclude and options.sort). |
Document.isServable |
isServable(podPath: string): boolean |
Returns true if podPath is not _-prefixed and has a supported extension. |
Document.SupportedExtensions |
Set<string> |
.yaml, .yml, .md, .html. |
Document.FrontMatterOnlyExtensions |
Set<string> |
.yaml, .yml. |
Document.SelfReferencedView |
'self' |
Special $view: self value indicating the document renders itself as a template. |
Instance Properties & Methods
| Member |
Type |
Description |
podPath |
string |
Pod-relative file path (e.g. '/content/pages/about.yaml'). |
locale |
Locale |
Locale bound to this document instance. |
pod |
Pod |
Parent Pod reference. |
ext |
string |
File extension including leading dot (e.g. '.md'). |
basename |
string |
Filename without extension ('about' for /content/pages/about.yaml). |
collection |
Collection or null |
Nearest enclosing collection containing _collection.yaml. |
collectionPath |
string |
Document's relative directory path inside its collection. |
fields |
any |
Parsed YAML object or front matter, localized for doc.locale. |
body |
string |
Markdown or HTML body below the --- front matter delimiter (empty string for YAML). |
content |
string or null |
Raw file contents from disk. |
view |
DocumentView |
Template pod path (e.g. '/views/page.njk'), 'self', or custom async render function. |
pathFormat |
string or false |
Resolved $path (or $localization.path for non-default locales); false for partial/hidden docs. |
url |
Url or undefined |
Resolved serving Url from pod.router, or undefined if non-routed. |
locales |
Set<Locale> |
Effective locales for this document ($localization.locales → collection → pod). |
defaultLocale |
Locale |
Effective default locale ($localization.defaultLocale → collection → pod). |
render(context?) |
Promise<string> |
Resolves async YAML fields and renders the document through its template engine. |
DocumentListOptions
| Option |
Type |
Description |
exclude |
string or string[] |
Glob pattern(s) of pod paths to exclude from results. |
sort |
string |
Field name on doc.fields to sort by (strings sorted with localeCompare, numbers numerically). |
TemplateContext
Every template rendered by doc.render() receives:
| Variable |
Type |
Description |
doc |
Document |
Current document being rendered. |
pod |
Pod |
Current pod instance. |
env |
Environment |
Current environment (pod.env). |
process |
NodeJS.Process |
Node.js process object (e.g. process.env). |
route |
Route (optional) |
Active DocumentRoute when rendered via router/builder. |
req |
express.Request (optional) |
Express request object during amagaki serve. |
Collection
Represents a content directory configured by a _collection.yaml file. Obtain via pod.collection(podPath) or pod.collections(patterns?, options?).
Static Members
| Member |
Signature |
Description |
Collection.ConfigFile |
'_collection.yaml' |
Filename that identifies a collection directory. |
Collection.list |
list(pod, patterns?, options?): Collection[] |
Lists collections matching glob pattern(s); supports {sort: 'field'}. |
Collection.find |
find(pod, path): Collection or null |
Walks upwards from path to locate the nearest _collection.yaml. |
Collection.normalizePath |
normalizePath(path: string): string |
Normalizes 'content/pages/' to '/content/pages'. |
Instance Properties & Methods
| Member |
Type |
Description |
podPath |
string |
Normalized collection pod path (e.g. '/content/blog'). |
collectionPath |
string |
Path to the collection's _collection.yaml. |
basename |
string |
Directory name ('blog' for '/content/blog'). |
exists |
Boolean |
Whether _collection.yaml exists in this directory. |
fields |
any |
Parsed contents of _collection.yaml. |
locales |
Set<Locale> |
Effective locales for this collection (falls back to pod.locales). |
index |
Document |
The collection's index.* document. |
parent |
Collection or null |
Immediate parent collection, if one exists. |
parents |
Collection[] |
Ancestor collections up to the root collection. |
parentPath |
string |
Parent directory pod path. |
subcollections |
Collection[] |
All nested child collections recursively. |
docs(options?) |
Document[] |
Lists documents in this collection; pass {excludeSubcollections: true} to omit nested collections. |
StaticFile
Represents a static asset (CSS, JS, image, font, etc.) obtained via pod.staticFile(podPath) or !pod.staticFile.
| Property |
Type |
Description |
podPath |
string |
Pod-relative path to the source file (e.g. '/static/css/main.css'). |
url |
Url or undefined |
Serving Url mapped by staticRoutes in amagaki.ts. |
fingerprint |
string |
MD5 hash of the file contents (useful for cache-busting query strings). |
exists |
Boolean |
Whether the static file exists on disk. |
Url
Represents a serving URL for a document or static file.
| Property / Method |
Type |
Description |
path |
string |
URL path component (e.g. '/docs/getting-started/cli/'). |
scheme |
string |
Protocol ('http' or 'https'), defaulting to env.scheme. |
host |
string |
Hostname, defaulting to env.host. |
port |
string |
Port string, defaulting to env.port. |
toString() |
string |
Full serialized URL (e.g. 'https://example.com/about/'). |
Url.relative(other, base) |
string |
Computes a relative URL from base (Document or string) to other (Document or string). |