Post: {pid}
+``` + +Any route like `/post/1`, `/post/abc`, etc. will be matched by `pages/post/[pid].astro`. The matched path parameter will be passed to the page component at `Astro.request.params`. + +For example, the route `/post/abc` will have the following `Astro.request.params` object available: + +```json +{ "pid": "abc" } +``` + +Multiple dynamic route segments can be combined to work the same way. The page `pages/post/[pid]/[comment].astro` will match the route `/post/abc/a-comment` and its `query` object will be: + +```json +{ "pid": "abc", "comment": "a-comment" } +``` + +### Rest parameters + +If you need more flexibility in your URL routing, you can use a rest parameter as a universal catch-all. You do this by adding three dots (`...`) inside your brackets. For example: + +- `pages/post/[...slug].astro` → (`/post/a`, `/post/a/b`, `/post/a/b/c`, etc.) + +Matched parameters will be sent as a query parameter (`slug` in the example) to the page. In the example above, the path `/post/a/b/c` will have the following `query` object: + +```json +{ "slug": "a/b/c" } +``` + +You can use names other than `slug`, such as: `[...param]` or `[...name]`. + +Rest parameters are optional by default, so `pages/post/[...slug].astro` could match `/post/` as well. + +#### Example: Rest parameters + +For a real-world example, you might implement GitHub's file viewer like so: + +``` +/[org]/[repo]/tree/[branch]/[...file] +``` + +In this example, a request for `/snowpackjs/astro/tree/main/docs/public/favicon.svg` would result in the following parameters being available to the page: + +```js +{ + org: 'snowpackjs', + repo: 'astro', + branch: 'main', + file: 'docs/public/favicon.svg' +} +``` + +## Caveats + +- Static routes without path params will take precedence over all other routes, and named path params over catch all path params. Take a look at the following examples: + - `pages/post/create.astro` - Will match `/post/create` + - `pages/post/[pid].astro` - Will match `/post/1`, `/post/abc`, etc. But not `/post/create` + - `pages/post/[...slug].astro` - Will match `/post/1/2`, `/post/a/b/c`, etc. But not `/post/create`, `/post/abc` diff --git a/docs/src/pages/foo/index.astro b/docs/src/pages/foo/index.astro new file mode 100644 index 000000000..653debaa8 --- /dev/null +++ b/docs/src/pages/foo/index.astro @@ -0,0 +1 @@ +hello
\ No newline at end of file diff --git a/docs/src/pages/guides/pagination.md b/docs/src/pages/guides/pagination.md new file mode 100644 index 000000000..bcce12e6b --- /dev/null +++ b/docs/src/pages/guides/pagination.md @@ -0,0 +1,108 @@ +--- +layout: ~/layouts/MainLayout.astro +title: Pagination +--- + +Astro supports built-in, automatic pagination for large collections of data that need to be split into multiple pages. Astro also automatically includes pagination metadata for things like previous/next page URL, total number of pages, and more. + +## When to use pagination + +Pagination is only useful when you need to generate multiple, numbered pages from a larger data set. + +If all of your data can fit on a single page then you should consider using a static [page component](/core-concepts/astro-pages) instead. + +If you need to split your data into multiple pages but do not want those page URLs to be numbered, then you should use a [dynamic page](/core-concepts/routing) instead without pagination (Example: `/tag/[tag].astro`). + +## How to use pagination + +### Create your page component + +To automatically paginate some data, you'll first need to create your page component. This is the component `.astro` file that every page in the paginated collection will inherit from. + +Pagination is built on top of dynamic page routing, with the page number in the URL represented as a dynamic route param: `[page].astro` or `[...page].astro`. If you aren't familiar with routing in Astro, quickly familiarize yourself with our [Routing documentation](/core-concepts/routing) before continuing. + +Your first page URL will be different depending on which type of query param you use: + +- `/posts/[page].astro` will generate the URLs `/posts/1`, `/posts/2`, `/posts/3`, etc. +- `/posts/[...page].astro` will generate the URLs `/posts`, `/posts/2`, `/posts/3`, etc. + +### calling the `paginate()` function + +Once you have decided on the file name/path for your page component, you'll need to export a [`getStaticPaths()`](/reference/api-reference#getstaticpaths) function from the component. `getStaticPaths()` is where you tell Astro what pages to generate. + +`getStaticPaths()` provides the `paginate()` function that we'll use to paginate your data. In the example below, we'll use `paginate()` to split a list of 150 Pokemon into 15 pages of 10 Pokemon each. + +```js +export async function getStaticPaths({ paginate }) { + // Load your data with fetch(), Astro.fetchContent(), etc. + const response = await fetch(`https://pokeapi.co/api/v2/pokemon?limit=150`); + const result = await response.json(); + const allPokemon = result.results; + // Return a paginated collection of paths for all posts + return paginate(allPokemon, { pageSize: 10 }); +} +// If set up correctly, The page prop now has everything that +// you need to render a single page (see next section). +const { page } = Astro.props; +``` + +`paginate()` generates the correct array of path objects for `getStaticPaths()`. This automatically tells Astro to create a new URL for every page of the collection. The page data will then be passed as a `page` prop to the `.astro` page component. + +### using the `page` prop + +Once you've set up your page component and defined your `getStaticPaths()` function, you're ready to design your page template. Each page in the paginated collection will be passed its data in the `page` prop. + +```astro +--- +export async function getStaticPaths { /* ... */ } +const { page } = Astro.props; +--- +Page {page.currentPage}
+-
+ {page.data.map(item =>
- {item.title})} +
{id}
+``` -/* the paginated return value, aka the prop passed to every page in the collection. */ -interface PaginatedCollectionResult { - /** result */ - data: any[]; +Then Astro will statically generate `posts/1` and `posts/2` at build time. - /** metadata */ - /** the count of the first item on the page, starting from 0 */ - start: number; - /** the count of the last item on the page, starting from 0 */ - end: number; - /** total number of results */ - total: number; - page: { - /** the current page number, starting from 1 */ - current: number; - /** number of items per page (default: 25) */ - size: number; - /** number of last page */ - last: number; - }; - url: { - /** url of the current page */ - current: string; - /** url of the previous page (if there is one) */ - prev: string | undefined; - /** url of the next page (if there is one) */ - next: string | undefined; - }; +### Data Passing with `props` + +To pass additional data to each generated page, you can also set a `props` value on every returned path object. Unlike `params`, `props` are not encoded into the URL and so aren't limited to only strings. + +For example, suppose that you generate pages based off of data fetched from a remote API. You can pass the full data object to the page component inside of `getStaticPaths`: + +```js +--- +export async function getStaticPaths() { + const data = await fetch('...').then(response => response.json()); + return data.map((post) => { + return { + params: { id: post.id }, + props: { post } }; + }); +} +const {id} = Astro.request.params; +const {post} = Astro.props; +--- +{id}: {post.name}
+``` + +Then Astro will statically generate `posts/1` and `posts/2` at build time using the page component in `pages/posts/[id].astro`. The page can reference this data using `Astro.props`: + +### `paginate()` + +Pagination is a common use-case for websites that Astro natively supports via the `paginate()` function. `paginate()` will automatically generate the array to return from `getStaticPaths()` that creates one URL for every page of the paginated collection. The page number will be passed as a param, and the page data will be passed as a `page` prop. + +```js +export async function getStaticPaths({ paginate }) { + // Load your data with fetch(), Astro.fetchContent(), etc. + const response = await fetch(`https://pokeapi.co/api/v2/pokemon?limit=150`); + const result = await response.json(); + const allPokemon = result.results; + // Return a paginated collection of paths for all posts + return paginate(allPokemon, { pageSize: 10 }); +} +// If set up correctly, The page prop now has everything that +// you need to render a single page (see next section). +const { page } = Astro.props; +``` + +`paginate()` assumes a file name of `[page].astro` or `[...page].astro`. The `page` param becomes the page number in your URL: + +- `/posts/[page].astro` would generate the URLs `/posts/1`, `/posts/2`, `/posts/3`, etc. +- `/posts/[...page].astro` would generate the URLs `/posts`, `/posts/2`, `/posts/3`, etc. + +#### The pagination `page` prop + +Pagination will pass a `page` prop to every rendered page that represents a single page of data in the paginated collection. This includes the data that you've paginated (`page.data`) as well as metadata for the page (`page.url`, `page.start`, `page.end`, `page.total`, etc). This metadata is useful for for things like a "Next Page" button or a "Showing 1-10 of 100" message. + +| Name | Type | Description | +| :----------------- | :-------------------: | :-------------------------------------------------------------------------------------------------------------------------------- | +| `page.data` | `Array` | Array of data returned from `data()` for the current page. | +| `page.start` | `number` | Index of first item on current page, starting at `0` (e.g. if `pageSize: 25`, this would be `0` on page 1, `25` on page 2, etc.). | +| `page.end` | `number` | Index of last item on current page. | +| `page.size` | `number` | How many items per-page. | +| `page.total` | `number` | The total number of items across all pages. | +| `page.currentPage` | `number` | The current page number, starting with `1`. | +| `page.lastPage` | `number` | The total number of pages. | +| `page.url.current` | `string` | Get the URL of the current page (useful for canonical URLs) | +| `page.url.prev` | `string \| undefined` | Get the URL of the previous page (will be `undefined` if on page 1). | +| `page.url.next` | `string \| undefined` | Get the URL of the next page (will be `undefined` if no more pages). | + +### `rss()` + +RSS feeds are another common use-case that Astro supports natively. Call the `rss()` function to generate an `/rss.xml` feed for your project using the same data that you loaded for this page. This file location can be customized (see below). + +```js +// Example: /src/pages/posts/[...page].astro +// Place this function inside your Astro component script. +export async function getStaticPaths({rss}) { + const allPosts = Astro.fetchContent('../post/*.md'); + const sortedPosts = allPosts.sort((a, b) => new Date(b.date) - new Date(a.date)); + // Generate an RSS feed from this collection + rss({ + // The RSS Feed title, description, and custom metadata. + title: 'Don’s Blog', + description: 'An example blog on Astro', + customData: `{post.title}
- {author.name} + {author.name}{post.description} diff --git a/examples/blog-multiple-authors/src/pages/$author.astro b/examples/blog-multiple-authors/src/pages/$author.astro deleted file mode 100644 index 76b372897..000000000 --- a/examples/blog-multiple-authors/src/pages/$author.astro +++ /dev/null @@ -1,105 +0,0 @@ ---- -import MainHead from '../components/MainHead.astro'; -import Nav from '../components/Nav.astro'; -import PostPreview from '../components/PostPreview.astro'; -import Pagination from '../components/Pagination.astro'; - -// page -let title = 'Don’s Blog'; -let description = 'An example blog on Astro'; -let canonicalURL = Astro.request.canonicalURL; - -// collection -import authorData from '../data/authors.json'; - -export function createCollection() { - /** Load posts */ - let allPosts = Astro.fetchContent('./post/*.md'); - return { - paginate: true, - route: `/author/:author/:page?`, - paths() { - let allAuthorsUnique = [...new Set(allPosts.map(p => p.author))]; - return allAuthorsUnique.map(author => ({params: {author}})) - }, - async props({ params, paginate }) { - /** filter posts by author, sort by date */ - const filteredPosts = allPosts - .filter((post) => post.author === params.author) - .sort((a, b) => new Date(b.date) - new Date(a.date)); - return { - posts: paginate(filteredPosts, {pageSize: 1}), - } - }, - }; -} - - -const { posts } = Astro.props; -const { params } = Astro.request; -const author = authorData[posts.data[0].author]; ---- - - -
-