--- layout: ~/layouts/Main.astro title: API Reference --- ## `Astro` global The `Astro` global is available in all contexts in `.astro` files. It has the following functions: ### `Astro.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](/core-concepts/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 ---
{data.slice(0, 3).map((post) => (

{post.title}

{post.description}

Read more
))}
``` `.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: ```js { /** frontmatter from the post.. example frontmatter: title: '', tag: '', date: '', image: '', author: '', description: '', **/ astro: { headers: [], // an array of h1...h6 elements in the markdown file source: '' // raw source of the markdown file html: '' // rendered HTML of the markdown file }, url: '' // the rendered path }[] ``` ### `Astro.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. ### `Astro.site` `Astro.site` returns a `URL` made from `buildOptions.site` in your Astro config. If undefined, this will return a URL generated from `localhost`. ## Collections API ### `collection` prop ```jsx const { collection } = Astro.props; ``` When using the [Collections API](/core-concepts/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](/core-concepts/collections), `createCollection()` is an async function that returns an object of the following shape: | Name | Type | Description | | :---------- | :--------------------------------------: | :--------------------------------------------------------------------------------------------------------- | | `data` | `async ({ params }) => any[]` | **Required.** Load an array of 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](/reference/api-reference#rss-feed) | Optional: generate an RSS 2.0 feed from this collection ([docs](/reference/api-reference#rss-feed)) | _\* 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 */ customData: `en-us The Sunset Explorers`, /** 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 */ customData: `${item.type} ${item.duration} ${item.explicit || false}`, }), }, }; } ``` 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 `` tags manually in your `` HTML: ```html ``` ## `import.meta` All ESM modules include a `import.meta` property. Astro adds `import.meta.env` through [Snowpack](https://www.snowpack.dev/). **import.meta.env.SSR** can be used to know when rendering on the server. Some times you might want different logic, for example a component that should only be rendered in the client: ```jsx import { h } from 'preact'; export default function () { return import.meta.env.SSR ? : ; } ``` [canonical]: https://en.wikipedia.org/wiki/Canonical_link_element on> Unnamed repository; edit this file 'description' to name the repository.
summaryrefslogtreecommitdiff
path: root/examples/minimal/src (unfollow)
AgeCommit message (Collapse)AuthorFilesLines
2023-11-27Remove support for simple objects in endpoints (#9181)Gravatar Bjorn Lu 56-529/+206
* Deprecate simple object from endpoints * Update changeset * Add missing Response return Co-authored-by: Happydev <81974850+MoustaphaDev@users.noreply.github.com> * Update .changeset/clever-beds-notice.md Co-authored-by: Sarah Rainsberger <sarah@rainsberger.ca> --------- Co-authored-by: Happydev <81974850+MoustaphaDev@users.noreply.github.com> Co-authored-by: Matthew Phillips <matthew@skypack.dev> Co-authored-by: Sarah Rainsberger <sarah@rainsberger.ca>
2023-11-28Remove shiki lang path property support (#9196)Gravatar Bjorn Lu 7-427/+22
2023-11-28Remove deprecated features from Astro 3.0 (#9168)Gravatar Bjorn Lu 47-398/+95
2023-11-28Remove deprecated markdown-remark APIs (#9182)Gravatar Bjorn Lu 4-59/+7
2023-11-27[ci] release (#9180)astro@3.6.1Gravatar Houston (Bot) 32-65/+63
Co-authored-by: github-actions[bot] <github-actions[bot]@users.noreply.github.com>
2023-11-24Remove vercel deprecated analytics option (#9184)Gravatar Bjorn Lu 3-30/+12
2023-11-24[ci] formatGravatar Guspan Tanadi 1-2/+1
2023-11-24style: highlight markdown Tip Note section CONTRIBUTING (#9123)Gravatar Guspan Tanadi 1-5/+7
2023-11-23fix scroll restoration issue on webKit browsers (#9186)Gravatar Martin Trapp 2-1/+7
* fix scroll restoration issue on webKit browsers * add changeset * Update .changeset/shaggy-socks-glow.md * Update .changeset/shaggy-socks-glow.md Co-authored-by: Sarah Rainsberger <sarah@rainsberger.ca> --------- Co-authored-by: Sarah Rainsberger <sarah@rainsberger.ca>
2023-11-23fix(middleware): rename internal middleware id (#9173)Gravatar Arsh 2-1/+6
* rename internal middleware id * add changeset
2023-11-23fix: Changelog formatting for 3.6.0 View Transition events (#9176)Gravatar Martin Trapp 1-3/+3
Co-authored-by: Eva Decker <itsevadecker@gmail.com>
2023-11-22[ci] formatGravatar Eva Decker 1-3/+3
2023-11-22Fix View Transitions code block formatting (#9174)Gravatar Eva Decker 1-3/+3
2023-11-22Rename entryPoint to entrypoint (#9161)Gravatar Bjorn Lu 14-26/+38
Co-authored-by: Sarah Rainsberger <sarah@rainsberger.ca>
2023-11-22Fix esbuild warning for local dev (#9160)Gravatar Bjorn Lu 1-1/+1
2023-11-22[ci] release (#9165)astro@3.6.0Gravatar Houston (Bot) 34-90/+83
Co-authored-by: github-actions[bot] <github-actions[bot]@users.noreply.github.com>