-
-
Notifications
You must be signed in to change notification settings - Fork 1.6k
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Co-authored-by: Paul Valladares <[email protected]> Co-authored-by: Sarah Rainsberger <[email protected]>
- Loading branch information
3 people
authored
Oct 26, 2023
1 parent
eb2067f
commit 39eceec
Showing
1 changed file
with
77 additions
and
0 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -4,6 +4,8 @@ description: An introduction to Astro pages | |
| i18nReady: true | ||
| --- | ||
|
|
||
| import Since from '~/components/Since.astro' | ||
|
|
||
| **Pages** are files that live in the `src/pages/` subdirectory of your Astro project. They are responsible for handling routing, data loading, and overall page layout for every page in your website. | ||
|
|
||
| ## Supported page files | ||
|
|
@@ -51,6 +53,8 @@ Astro pages use the `.astro` file extension and support the same features as [As | |
| </html> | ||
| ``` | ||
|
|
||
| A page must produce a full HTML document. If not explicitly included, Astro will add the necessary `<! DOCTYPE html>` declaration and `<head>` content to any `.astro` component located within `src/pages/` by default. You can opt-out of this behavior on a per-component basis by marking it as a [partial](#page-partials) page. | ||
|
|
||
| To avoid repeating the same HTML elements on every page, you can move common `<head>` and `<body>` elements into your own [layout components](/en/core-concepts/layouts/). You can use as many or as few layout components as you'd like. | ||
|
|
||
| ```astro {3} /</?MySiteLayout>/ | ||
|
|
@@ -96,3 +100,76 @@ For a custom 404 error page, you can create a `404.astro` or `404.md` file in `/ | |
|
|
||
| This will build to a `404.html` page. Most [deploy services](/en/guides/deploy/) will find and use it. | ||
|
|
||
| ## Page Partials | ||
|
|
||
| <Since v="3.4.0" /> | ||
|
|
||
| :::caution | ||
| Page partials are intended to be used in conjunction with a front-end library, such as [htmx](https://htmx.org/) or [Unpoly](https://unpoly.com/). You can also use them if you are comfortable writing low-level front-end JavaScript. For this reason they are an advanced feature. | ||
|
|
||
| Additionally, partials should not be used if the component contains scoped styles or scripts, as these elements will be stripped from the HTML output. If you need scoped styles, it is better to use regular, non-partial pages along with a frontend library that knows how to merge the contents into the head. | ||
| ::: | ||
|
|
||
| Partials are page components located within `src/pages/` that are not intended to render as full pages. | ||
|
|
||
| Like components located outside of this folder, these files do not automatically include the `<! DOCTYPE html>` declaration, nor any `<head>` content such as scoped styles and scripts. | ||
|
|
||
| However, because they are located in the special `src/pages/` directory, the generated HTML is available at a URL corresponding to its file path. This allows a rendering library (e.g. htmx, Stimulus, jQuery) to access it on the client and load sections of HTML dynamically on a page without a browser refresh or page navigation. | ||
|
|
||
| Partials, when combined with a rendering library, provide an alternative to [Astro islands](/en/concepts/islands/) and [`<script>` tags](/en/guides/client-side-scripts/) for building dynamic content in Astro. | ||
|
|
||
| Page files that can export a value (e.g. `.astro` , `.mdx`) can be marked as partials. | ||
|
|
||
| Configure a file within the `src/pages/` directory to be a partial by adding the following export: | ||
|
|
||
| ```astro title="src/pages/partial.astro" ins={2} | ||
| --- | ||
| export const partial = true; | ||
| --- | ||
| <li>I'm a partial!</li> | ||
| ``` | ||
|
|
||
| The `export const partial` must be identifiable statically. It can have the value of: | ||
|
|
||
| - The boolean __`true`__. | ||
| - An environment variable using import.meta.env such as `import.meta.env.USE_PARTIALS`. | ||
|
|
||
| ### Using with a library | ||
|
|
||
| Partials are used to dynamically update a section of a page using a library such as [htmx](https://htmx.org/). | ||
|
|
||
| The following example shows an `hx-post` attribute set to a partial's URL. The content from the partial page will be used to update the targeted HTML element on this page. | ||
|
|
||
| ```astro title="src/pages/index.astro" 'hx-post="/partials/clicked/"' | ||
| <html> | ||
| <head> | ||
| <title>My page</title> | ||
| <script src="https://unpkg.com/[email protected]" | ||
| integrity="sha384-FhXw7b6AlE/jyjlZH5iHa/tTe9EpJ1Y55RjcgPbjeWMskSxZt1v9qkxLJWNJaGni" | ||
| crossorigin="anonymous"></script> | ||
| </head> | ||
| </html> | ||
| <section> | ||
| <div id="parent-div">Target here</div> | ||
| <button hx-post="/partials/clicked/" | ||
| hx-trigger="click" | ||
| hx-target="#parent-div" | ||
| hx-swap="innerHTML" | ||
| > | ||
| Click Me! | ||
| </button> | ||
| </section> | ||
| ``` | ||
|
|
||
| The .`astro` partial must exist at the corresponding file path, and include an export defining the page as a partial: | ||
|
|
||
| ```astro title="src/pages/partials/clicked.astro" {2} | ||
| --- | ||
| export const partial = true; | ||
| --- | ||
| <div>I was clicked!</div> | ||
| ``` | ||
|
|
||
| See the [htmx documentation](https://htmx.org/docs/) for more details on using htmx. | ||