Resources, Data, and the Cost of Reuse
Hugo's resource and data features answer a practical question: how can a page use images, structured information, or generated material without losing ownership of what it depends on? This chapter compares page-local, global, and remote resources; follows a transformation from discovery to publication; and then examines data sources and content adapters. The goal is to choose the smallest scope that fits the dependency, while understanding why reuse can add memory, cache, network, and collision costs.
The distinction matters because “available to a template” does not mean “the same kind of input.” A page bundle gives an image a local owner. A global resource makes an asset available across pages. A remote resource adds a network dependency. A data file can augment an existing page, while a content adapter can create new graph nodes. Hugo supports all of these, but each crosses a different boundary in the build.
Choose resource scope by ownership
A page resource belongs to a page bundle. If a report directory contains an index file and a cover image, the cover is naturally associated with that report. The page can retrieve it through its resource collection, transform it, and emit a link relative to the page. That locality is useful because the dependency is visible where the content lives: moving or removing the bundle changes the resource relationship with the page that owns it.
Page resources are a good default when an asset explains or accompanies one piece of content. They can include more than images. Hugo documents page resources for data files, documents, audio, video, snippets, and other supported formats. A template can read a Markdown snippet as content or unmarshal a JSON file as structured data, still keeping the lookup relative to the owning page.
A global resource lives in the project's asset space and can be acquired by many pages. Shared stylesheets, site-wide scripts, logos, or common image variants often belong here. The benefit is reuse without copying the same file into many bundles. The cost is a wider dependency surface: changing the global resource may affect every template that uses it, and the resource's owner is the project rather than one page.
A remote resource is acquired through a URL. This can be valuable when the build intentionally consumes an external image or data feed, but it changes the failure model. The build now depends on network availability, the remote response's media type, the URL allowlist, and the behavior of the source. A remote input is not automatically more reusable simply because it is outside the repository. It is reusable with an external dependency attached.
The choice can be expressed as a question of ownership. If the asset should change with one page, keep it in the page bundle. If many pages share the same build-time asset, make it global. If the source of truth must remain elsewhere and the build is allowed to depend on it, use a remote resource with explicit policy and failure handling. The point is not to avoid global or remote inputs; it is to make their broader consequences visible in the graph.
A transformation is a value before it is a file
Hugo treats a resource as something a template can acquire and transform, not merely something it copies. Image processing methods can resize, crop, rotate, adjust, or otherwise derive a new resource.