7.7 KiB
📚 API
Astro
global
The Astro
global is available in all contexts in .astro
files. It has the following functions:
config
Astro.config
returns an object with the following properties:
Name | Type | Description |
---|---|---|
site |
string |
Your website’s public root domain. Set it with site: "https://mysite.com" in your Astro config |
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.
// ./astro/components/my-component.astro
---
const data = Astro.fetchContent('../pages/post/*.md'); // returns an array of posts that live at ./astro/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
}[];
collection
export let collection;
When using the Collections API, 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()
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, 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 | Optional: generate an RSS 2.0 feed from this collection (docs). |
* 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:
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,
/** (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, /astro/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:
<link rel="alternate" type="application/rss+xml" title="My RSS Feed" href="/feed/podcast.xml" />