The render pipeline.
Every request follows the same sequence, from the host on the request to the bytes on the wire. Knowing the order explains where your template sits, why a path resolves the way it does, and when a change goes live.
The sequence
- Resolve the site. The request host is matched to a site by its domain, cname or alternate domains. Everything after this is scoped to that site.
- Resolve the render mode. The site's
render_modeis read once and carried through the render. See Render modes. - Find the content for the path. The path is matched against templates and posts by permalink. The root path is treated as
/index. A template whose permalink matches wins. - Pick a layout for a post. When the match is a post, it is rendered through the layout template for its type. See Type-based layouts.
- Build the context. The site, the page or post, the environment, bits, categories, the request parameters and the signed-in user are assembled into the variable map. See Objects.
- Render the Liquid. The template body is rendered, tolerantly: undefined variables are empty, a broken tag does not take down the page, and unknown tags are dropped (compat) or surfaced (standard).
- Inject meta and SEO. The title, description, canonical, social tags and JSON-LD are inserted into the head. See SEO and meta.
- Serve. The finished page is returned, and cached briefly for the next visitor.
Path resolution
A path resolves to the first template or post whose permalink matches it. The root / resolves as /index, and both slash forms of a path are tried. When nothing matches, the request falls through a short chain rather than failing outright, so a missing path lands on a sensible page instead of a blank error. Because of this, test a new route by its real URL after you save it.
Caching and going live
Rendered pages are held in a short-lived in-memory cache, on the order of tens of seconds, so a burst of traffic to one page does not re-render it every time. Saving a template purges the pages it affects, keyed by permalink.
The home page is served at / but keyed internally as /index. If a home-page edit does not appear at once, that difference plus the short cache window is usually why; give it a moment. Template bodies used by includes are cached separately for about a minute.
Taking over the output
A template body that begins with the <%= no_render %> marker is served with the marker removed and the automatic head-meta injection turned off. This lets a template return something other than a normal HTML page, for example a JSON document or a feed, without the meta pipeline rewriting its head.