1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
|
## 📚 API
### `Astro` global
The `Astro` global is available in all contexts in `.astro` files. It has the following functions:
#### `fetchContent()`
`Astro.fetchContent()` is a way to load local `*.md` files into your static site setup. You can either use this on its own, or within [Astro Collections][docs-collections].
```jsx
// ./src/components/my-component.astro
---
const data = Astro.fetchContent('../pages/post/*.md'); // returns an array of posts that live at ./src/pages/post/*.md
---
<div>
{data.slice(0, 3).map((post) => (
<article>
<h1>{post.title}</h1>
<p>{post.description}</p>
<a href={post.url}>Read more</a>
</article>
))}
</div>
```
`.fetchContent()` only takes one parameter: a relative URL glob of which local files you’d like to import. Currently only `*.md` files are supported. It’s synchronous, and returns an array of items of type:
```
{
url: string; // the URL of this item (if it’s in pages/)
content: string; // the HTML of this item
// frontmatter data expanded here
}[];
```
#### `request`
`Astro.request` returns an object with the following properties:
| Name | Type | Description |
| :------------- | :---- | :---------------------------------------------- |
| `url` | `URL` | The URL of the request being rendered. |
| `canonicalURL` | `URL` | [Canonical URL][canonical] of the current page. |
⚠️ Temporary restriction: this is only accessible in top-level pages and not in sub-components.
#### `site`
`Astro.site` returns a `URL` made from `buildOptions.site` in your Astro config. If undefined, this will return a URL generated from `localhost`.
### `collection`
```jsx
export let collection;
```
When using the [Collections API][docs-collections], `collection` is a prop exposed to the page with the following shape:
| Name | Type | Description |
| :------------------------ | :-------------------: | :-------------------------------------------------------------------------------------------------------------------------------- |
| `collection.data` | `Array` | Array of data returned from `data()` for the current page. |
| `collection.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.). |
| `collection.end` | `number` | Index of last item on current page. |
| `collection.total` | `number` | The total number of items across all pages. |
| `collection.page.current` | `number` | The current page number, starting with `1`. |
| `collection.page.size` | `number` | How many items per-page. |
| `collection.page.last` | `number` | The total number of pages. |
| `collection.url.current` | `string` | Get the URL of the current page (useful for canonical URLs) |
| `collection.url.prev` | `string \| undefined` | Get the URL of the previous page (will be `undefined` if on page 1). |
| `collection.url.next` | `string \| undefined` | Get the URL of the next page (will be `undefined` if no more pages). |
| `collection.params` | `object` | If page params were used, this returns a `{ key: value }` object of all values. |
### `createCollection()`
```jsx
export async function createCollection() {
return {
async data({ params }) {
// load data
},
pageSize: 25,
routes: [{ tag: 'movie' }, { tag: 'television' }],
permalink: ({ params }) => `/tag/${params.tag}`,
};
}
```
When using the [Collections API][docs-collections], `createCollection()` is an async function that returns an object of the following shape:
| Name | Type | Description |
| :---------- | :---------------------------: | :--------------------------------------------------------------------------------------------------------- |
| `data` | `async ({ params }) => any[]` | **Required.** Load data with this function to be returned. |
| `pageSize` | `number` | Specify number of items per page (default: `25`). |
| `routes` | `params[]` | **Required for URL Params.** Return an array of all possible URL `param` values in `{ name: value }` form. |
| `permalink` | `({ params }) => string` | **Required for URL Params.** Given a `param` object of `{ name: value }`, generate the final URL.\* |
| `rss` | [RSS][rss] | Optional: generate an RSS 2.0 feed from this collection ([docs][rss]). |
_\* Note: don’t create confusing URLs with `permalink`, e.g. rearranging params conditionally based on their values._
⚠️ `createCollection()` executes in its own isolated scope before page loads. Therefore you can’t reference anything from its parent scope. If you need to load data you may fetch or use async `import()`s within the function body for anything you need (that’s why it’s `async`—to give you this ability). If it wasn’t isolated, then `collection` would be undefined! Therefore, duplicating imports between `createCollection()` and your Astro component is OK.
#### 📡 RSS Feed
You can optionally generate an RSS 2.0 feed from `createCollection()` by adding an `rss` option. Here are all the options:
```jsx
export async function createCollection() {
return {
async data({ params }) {
// load data
},
pageSize: 25,
rss: {
title: 'My RSS Feed',
description: 'Description of the feed',
/** (optional) add xmlns:* properties to root element */
xmlns: {
itunes: 'http://www.itunes.com/dtds/podcast-1.0.dtd',
content: 'http://purl.org/rss/1.0/modules/content/',
},
/** (optional) add arbitrary XML to <channel> */
customData: `<language>en-us</language>
<itunes:author>The Sunset Explorers</itunes:author>`,
/** Format each item from things returned in data() */
item: (item) => ({
title: item.title,
description: item.description,
pubDate: item.pubDate + 'Z', // enforce GMT timezone (otherwise it’ll be different based on where it’s built)
/** (optional) add arbitrary XML to each <item> */
customData: `<itunes:episodeType>${item.type}</itunes:episodeType>
<itunes:duration>${item.duration}</itunes:duration>
<itunes:explicit>${item.explicit || false}</itunes:explicit>`,
}),
},
};
}
```
Astro will generate an RSS 2.0 feed at `/feed/[collection].xml` (for example, `/src/pages/$podcast.xml` would generate `/feed/podcast.xml`).
⚠️ Even though Astro will create the RSS feed for you, you’ll still need to add `<link>` tags manually in your `<head>` HTML:
```html
<link rel="alternate" type="application/rss+xml" title="My RSS Feed" href="/feed/podcast.xml" />
```
[canonical]: https://en.wikipedia.org/wiki/Canonical_link_element
[config]: ../README.md#%EF%B8%8F-configuration
[docs-collections]: ./collections.md
[rss]: #-rss-feed
|
