diff --git a/reference/api-reference.md b/reference/api-reference.md deleted file mode 100644 index c3cf860bcfceb..0000000000000 --- a/reference/api-reference.md +++ /dev/null @@ -1,195 +0,0 @@ ---- -layout: ~/layouts/MainLayout.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.slots` - -`Astro.slots` returns an object with any slotted regions passed into the current Astro file. - -```js -const { - heading as headingSlot, // true or undefined, based on whether `<* slot="heading">` was used. - default as defaultSlot, // true or undefined, based on whether `<* slot>` or `<* default>` was used. -} = Astro.slots; -``` - -### `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 `.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 [Vite](https://vitejs.dev/guide/env-and-mode.html). - -**import.meta.env.SSR** can be used to know when rendering on the server. Sometimes 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 diff --git a/src/pages/en/core-concepts/astro-components.md b/src/pages/en/core-concepts/astro-components.md index a7c6dd23d59eb..9f5e24bc1e783 100644 --- a/src/pages/en/core-concepts/astro-components.md +++ b/src/pages/en/core-concepts/astro-components.md @@ -102,9 +102,6 @@ const myFavoritePokemon = [/* ... */];

- - - ``` ### Dynamic JSX Expressions @@ -219,84 +216,104 @@ const name = "Astro" ### Slots -The `` element is a placeholder for HTML which will be passed in from outside of the component by "children" (as they are called in React or Preact). Slots are a way of passing data into an Astro component and are useful when you will want to reuse an "outer" component, rendered "around" data coming from an external source. +The `` element is a placeholder for external HTML content, allowing you to inject (or "slot") child elements from other files into your component template. -A component that uses the `` element can be thought of as a reusable "wrapper" around other content, and this pattern is the basis of an Astro [Layout component](/en/core-concepts/layouts). +By default, all child elements passed to a component will be rendered in its `` +> 💡Unlike _props_, which are attributes passed to an Astro component available for use throughout your component with `Astro.props()`, _slots_ render child HTML elements where they are written. ```astro -// src/components/Wrapper.astro --- +// src/components/Wrapper.astro import Header from './Header.astro'; import Logo from './Logo.astro'; import Footer from './Footer.astro'; -const { name } = Astro.props +const { title } = Astro.props ---

-

{name}

+

{title}

+``` -// src/components/Person.astro - - -

I am a person.

-

Here is some stuff about me.

+```astro +--- +// src/pages/fred.astro +import Wrapper from '../components/Wrapper.astro'; +--- + +

All about Fred

+

Here is some stuff about Fred.

 ``` +This pattern is the basis of an Astro layout component: an entire page of HTML content can be “wrapped” with `` tags and sent to the Layout component to render inside of common page elements. + + + #### Named Slots -Inside of an Astro component, slots can also be **named**. Rather than a single `` element which renders _all_ children, named slots allow you to specify multiple places where children should be placed. +An Astro component can also have named slots. This allows you to pass only HTML elements with the corresponding slot name into a slot's location. ```astro -// src/components/Wrapper.astro --- +// src/components/Wrapper.astro import Header from './Header.astro'; import Logo from './Logo.astro'; import Footer from './Footer.astro'; -const { name } = Astro.props +const { title } = Astro.props ---
-

{name}

+

{title}

+``` -// src/components/Person.astro - - - -

I am a person.

-

Here is some stuff about me.

+```astro +--- +// src/pages/fred.astro +import Wrapper from '../components/Wrapper.astro'; +--- + + +

All about Fred

+

Here is some stuff about Fred.

+

Copyright 2022

 ``` + +Use a `slot="my-slot"` attribute on the child element that you want to pass through to a matching `` placeholder in your component. + +> ⚠️ This only works when you’re passing slots to other Astro components. Learn more about including other [UI framework components](en/guides/framework-components) in Astro files. + + #### Fallback Content for Slots Slots can also render **fallback content**. When there are no matching children passed to a ``, a `` element will render its own placeholder children. ```astro -// src/components/Wrapper.astro --- +// src/components/Wrapper.astro import Header from './Header.astro'; import Logo from './Logo.astro'; import Footer from './Footer.astro'; -const { name } = Astro.props +const { title } = Astro.props ---
-

{name}

+

{title}

This is my fallback content, if there is no child passed into slot