collage

Pages composed from cached fragments.

collage is a Go framework for server-rendered sites. A page is a layout around fragments; each fragment fetches its own data, and the page is cached and invalidated by what it was built from. No client framework, no JavaScript build step, no dependencies.

Read the guide View on GitHub 
go install github.com/Elagoht/collage/cmd/collage@latest
collage new mysite && cd mysite && go mod tidy
collage dev

Fragments, not components

A template, a data handler and the slots it exposes. Siblings fetch concurrently; the page is written in order.

Cached by what it depends on

Pages and data carry tags. Change an author and one call drops the author and every page that shows them.

Forms without JavaScript

Actions answer POST with forgery protection built in, and a cached page can still carry a form.

Served or exported

One program is a server and a static site generator. This site is the second.

Getting started

  • IntroductionWhat collage is, the idea it is built on, and when it is the right tool.
  • InstallationInstall Go and the collage CLI, scaffold a project with collage new, and run it under collage dev.
  • Your first pageA hands-on tutorial — build a recipe page with a layout, a typed data handler and a template, then add a second fragment in a slot.

Core concepts

  • Pages and layoutsWhat a page is, how its layout and content fit together, the paths that reach it, how it is cached, what it shows when it fails, and what registration does to it.
  • Fragments and slotsFragments, the slots they expose, what happens when one fails, and slots filled from content at render time.
  • Data handlersHow a fragment fetches its data — the typed handler contract, dependency tags, 404s, concurrency, the render context, sharing data, and timeouts.
  • TemplatesWhere templates live, how they are loaded and embedded, how they reload in development, slots, built-in and custom functions, and escaping.

Building a site

  • CachingHow collage caches rendered pages and the data they are made from, and how it knows what to throw away.
  • Forms and actionsHandling form posts, fetch calls and webhooks with actions, and protecting them from request forgery.
  • Links and localesServing a site in several languages, and linking between pages by name so links follow them in every locale.
  • Head and SEOTitles, meta tags, stylesheets and structured data declared by the fragment that knows them, placed by the layout.
  • Static assetsServing stylesheets, scripts, images and downloads from a directory or an embedded file system, with URLs that can be cached for a year.
  • Documents: sitemaps, feeds, robots.txtRoutes that answer with bytes instead of HTML — sitemaps, feeds, robots.txt, JSON — cached and invalidated like pages.
  • Middleware and your own APIStandard net/http middleware with app.Use, cache keys that depend on a header with collage.Vary, and your own http.Handler with app.Handle.
  • PreviewsShow editors unpublished drafts on the real site, without the cache serving them the published page or anyone else the draft.

Shipping

  • Static exportRender the site to static files with collage export — what is written, what is skipped and why, dynamic paths, and publishing to a static host.
  • DeploymentBuild the binary, run it in a container or under systemd, set what production needs, and put it behind TLS.
  • TestingTest the real application through app.Handler() and net/http/httptest — pages, forms with their forgery token, documents and the static export.

Extending

  • Using pluginsWhat a plugin can do, how to register and configure one, and the three published plugins.
  • Writing a pluginThe plugin contract, what Host and ConfigHost expose, every hook and what it may change, and a complete plugin with its tests.

Reference

  • The collage CLIEvery command of the collage CLI — new, dev, build, export, serve, version and help — with its flags and exactly what it runs.
  • ConfigurationEvery field of collage.Config and its sub-structs, with its default and what validation checks.
  • Template functionsEvery built-in template function — slot, hoist, asset, stylesheet, csrfToken, the URL functions and the string helpers — with its signature, an example and its edge cases.
  • ErrorsEvery exported error value in collage, grouped by where it comes from, with what it means and what to do about it.