Support for partials #697
Description
- Accepted Date: 2023-09-13
- Reference Issues/Discussions: A way to not use <!DOCTYPE html> #266
- Author: @matthewp
- Champion(s): @matthewp
- Implementation PR:
Summary
Allow pages to be marked as being partials, preventing the doctype tag and any head injection from taking place. A partial is defined as a template which belongs in the context of another page and is dependent on that page in order to be fully functional.
Background & Motivation
Partials are a technique that has been used by web applications for decades, popularized in frameworks such as Ruby on Rails. Frontend oriented JavaScript frameworks have typically not used partials, but instead use JSON APIs and front-end templating in order to dynamically change parts of the page. Nevertheless, partials have remained a niche feature, and with Astro's backend focus we have had interest in support for a long time.
Recently the popularity of projects like htmx and Unpoly have revived interest in this technique. Since Astro treats each page request as a request for a full page it automatically attaches the doctype and head elements, making it difficult to simply inject into the page.
Goals
- The ability to request a URL from Astro that excludes the usual page elements (doctype, head injection).
- Some way to optionally communicate extra dependencies, such as styles and scripts, so libraries that support head-diffing can achieve that.
- The base feature should work the same in SSG and SSR apps. Partials are still output as
.htmlfiles in a static build.
Non-Goals
- This isn't an integration specifically for HTMX or any one library. It should work with any library or manual DOM manipulation that does
innerHTML.- We may take into account special headers from popular libraries if there is a way to enhance the base experience.
- No client-side scripts from Astro will be part of this change.
- Routing should mostly be unchanged; this is metadata about a page but doesn't change the location or where routes live (still in the
pagesfolder).