From 9d264f4b6629ceb5cbd8fe6fe40be59b4e1cb6ce Mon Sep 17 00:00:00 2001 From: Sarah Rainsberger Date: Thu, 28 Apr 2022 21:44:25 +0000 Subject: [PATCH 1/6] polished component and slot content --- reference/api-reference.md | 195 ------------------ .../en/core-concepts/astro-components.md | 56 +++-- 2 files changed, 35 insertions(+), 216 deletions(-) delete mode 100644 reference/api-reference.md 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 8f4c35fc0a8d2..3d970b25f27f6 100644 --- a/src/pages/en/core-concepts/astro-components.md +++ b/src/pages/en/core-concepts/astro-components.md @@ -6,7 +6,7 @@ description: An intro to the .astro component syntax. **Astro components** are the basic building blocks of any Astro project. They are HTML-only templating components with no client-side runtime. -Astro component syntax is a superset of HTML. The syntax was designed to feel familiar to anyone with experience writing HTML or JSX, and adds support for including components and JavaScript expressions. You can spot an Astro component by its file extension: `.astro`. +Astro component syntax is a superset of HTML. The syntax was [designed to feel familiar to anyone with experience writing HTML or JSX](/en/comparing-astro-vs-other-tools/#astro-vs-jsx), and adds support for including components and JavaScript expressions. You can spot an Astro component by its file extension: `.astro`. Astro components are extremely flexible. Often, an Astro component will contain some **reusable UI on the page**, like a header or a profile card. At other times, an Astro component may contain a smaller snippet of HTML, like a collection of common `` tags that make SEO easy to work with. Astro components can even contain an entire page layout. @@ -77,7 +77,7 @@ Below the component script, sits the component template. The component template If you write plain HTML here, your component will render that HTML in any Astro page it is imported and used. -However, Astro's component template syntax also supports **JavaScript expressions**, **imported components** and **special Astro directives**. Data and values defined (at page build time) in the component script can be used in the component template to produce dynamically-created HTML. +However, Astro's component template syntax also supports **JavaScript expressions**, **imported components** and [**special Astro directives**](/en/reference/directives-reference/). Data and values defined (at page build time) in the component script can be used in the component template to produce dynamically-created HTML. ```astro --- @@ -100,6 +100,9 @@ const myFavoritePokemon = [/* ... */]; {myFavoritePokemon.map((data) =>
  • {data.name}
    • )}
      + +

      + ``` @@ -215,12 +218,21 @@ 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. - -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). +Astro components can accept HTML content in your component template. This "child" content will be injected into its `` element. +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. ```astro +--- +// src/pages/index.astro +import Wrapper from '../components/Wrapper.astro'; +--- + +

      I am a person.

      +

      Here is some stuff about me.

      + + + // src/components/Wrapper.astro --- import Header from './Header.astro'; @@ -236,20 +248,25 @@ const { name } = Astro.props