diff --git a/src/content/docs/en/guides/cms/builderio.mdx b/src/content/docs/en/guides/cms/builderio.mdx index 9fee1778745ba..eef6bb078f866 100644 --- a/src/content/docs/en/guides/cms/builderio.mdx +++ b/src/content/docs/en/guides/cms/builderio.mdx @@ -8,6 +8,7 @@ i18nReady: true --- import PackageManagerTabs from '~/components/tabs/PackageManagerTabs.astro' import { FileTree } from '@astrojs/starlight/components'; +import { Steps } from '@astrojs/starlight/components'; [Builder.io](https://www.builder.io/) is a visual CMS that supports drag-and-drop content editing for building websites. @@ -140,11 +141,13 @@ In the above example, `` tells Builder where to insert the co #### Setting the new route as the preview URL + 1. Copy the full URL of your preview, including the protocol, to your clipboard (e.g. `https://{your host}/builder-preview`). 2. Go to the **Models** tab in your Builder space, pick the model you've created and paste the URL from step 1 into the **Preview URL** field. Make sure the URL is complete and includes the protocol, for example `https://`. 3. Click the **Save** button in the upper right. + :::tip When you deploy your site, change the preview URL to match your production URL, for example `https://myAwesomeAstroBlog.com/builder-preview`. @@ -152,11 +155,13 @@ When you deploy your site, change the preview URL to match your production URL, #### Testing the preview URL setup + 1. Make sure your site is live (e.g. your dev server is running) and the `/builder-preview` route is working. 2. In your Builder space under the **Content** tab, click on **New** to create a new content entry for your `blogpost` model. 3. In the Builder editor that just opened, you should be able to see the `builder-preview.astro` page with a big **Add Block** in the middle. + :::tip[Troubleshooting] @@ -172,13 +177,19 @@ For more ideas, read [Builder's troubleshooting guide](https://www.builder.io/c/ ### Creating a blog post + 1. In Builder's visual editor, create a new content entry with the following values: - **title:** 'First post, woohoo!' - **slug:** 'first-post-woohoo' + 2. Complete your post using the **Add Block** button and add a text field with some post content. + 3. In the text field above the editor, give your entry a name. This is how it will be listed in the Builder app. + 4. When you're ready click the **Publish** button in the upper right corner. + 5. Create as many posts as you like, ensuring that all content entries contain a `title` and a `slug` as well as some post content. + ### Displaying a list of blog posts @@ -328,15 +339,23 @@ If your project is using Astro's default static mode, you will need to set up a ##### Netlify + 1. Go to your site dashboard, then **Site Settings** and click on **Build & deploy**. + 2. Under the **Continuous Deployment** tab, find the **Build hooks** section and click on **Add build hook**. + 3. Provide a name for your webhook and select the branch you want to trigger the build on. Click on **Save** and copy the generated URL. + ##### Vercel + 1. Go to your project dashboard and click on **Settings**. + 2. Under the **Git** tab, find the **Deploy Hooks** section. + 3. Provide a name for your webhook and the branch you want to trigger the build on. Click **Add** and copy the generated URL. + ##### Adding a webhook to Builder @@ -344,9 +363,13 @@ If your project is using Astro's default static mode, you will need to set up a See [Builder's guide on adding webhooks](https://www.builder.io/c/docs/webhooks) for more information. ::: + 1. In your Builder dashboard, go into your **`blogpost`** model. Under **Show More Options**, select **Edit Webhooks** at the bottom. + 2. Add a new webhook by clicking on **Webhook**. Paste the URL generated by your hosting provider into the **Url** field. + 3. Click on **Show Advanced** under the URL field and toggle the option to select **Disable Payload**. With the payload disabled, Builder sends a simpler POST request to your hosting provider, which can be helpful as your site grows. Click **Done** to save this selection. + With this webhook in place, whenever you click the **Publish** button in the Builder editor, your hosting provider rebuilds your site - and Astro fetches the newly published data for you. Nothing to do but lean back and pump out that sweet sweet content! @@ -360,4 +383,3 @@ With this webhook in place, whenever you click the **Publish** button in the Bui ## Community resources - Read [Connecting Builder.io's Visual CMS to Astro](https://www.hamatoyogi.dev/blog/astro-log/connecting-builderio-to-astro) by Yoav Ganbar. - diff --git a/src/content/docs/en/guides/cms/buttercms.mdx b/src/content/docs/en/guides/cms/buttercms.mdx index ab75fbddc1c27..37f54260cd16c 100644 --- a/src/content/docs/en/guides/cms/buttercms.mdx +++ b/src/content/docs/en/guides/cms/buttercms.mdx @@ -6,10 +6,9 @@ service: ButterCMS stub: false i18nReady: true --- +import { Steps } from '@astrojs/starlight/components'; import PackageManagerTabs from '~/components/tabs/PackageManagerTabs.astro' - - [ButterCMS](https://buttercms.com/) is a headless CMS and blog engine that allows you to publish structured content to use in your project. ## Integrating with Astro @@ -28,6 +27,7 @@ To get started, you will need to have the following: ### Setup + 1. Create a `.env` file in the root of your project and add your API token as an environment variable: ```ini title=".env" @@ -64,6 +64,7 @@ To get started, you will need to have the following: export const butterClient = Butter(import.meta.env.BUTTER_TOKEN); ``` + **This authenticates the SDK using your API Token and exports it to be used across your project.** diff --git a/src/content/docs/en/guides/cms/contentful.mdx b/src/content/docs/en/guides/cms/contentful.mdx index 2c6536ebec791..74da59ae156cd 100644 --- a/src/content/docs/en/guides/cms/contentful.mdx +++ b/src/content/docs/en/guides/cms/contentful.mdx @@ -6,9 +6,8 @@ service: Contentful i18nReady: true --- import { FileTree } from '@astrojs/starlight/components'; -import PackageManagerTabs from '~/components/tabs/PackageManagerTabs.astro' - - +import PackageManagerTabs from '~/components/tabs/PackageManagerTabs.astro'; +import { Steps } from '@astrojs/starlight/components'; [Contentful](https://www.contentful.com/) is a headless CMS that allows you to manage content, integrate with other services, and publish to multiple platforms. @@ -545,21 +544,25 @@ If your project is using Astro's default static mode, you will need to set up a To set up a webhook in Netlify: + 1. Go to your site dashboard and click on **Build & deploy**. 2. Under the **Continuous Deployment** tab, find the **Build hooks** section and click on **Add build hook**. 3. Provide a name for your webhook and select the branch you want to trigger the build on. Click on **Save** and copy the generated URL. + ##### Vercel To set up a webhook in Vercel: + 1. Go to your project dashboard and click on **Settings**. 2. Under the **Git** tab, find the **Deploy Hooks** section. 3. Provide a name for your webhook and the branch you want to trigger the build on. Click **Add** and copy the generated URL. + ##### Adding a webhook to Contentful diff --git a/src/content/docs/en/guides/cms/datocms.mdx b/src/content/docs/en/guides/cms/datocms.mdx index da93c91f2b6a4..cdfbc972df9a9 100644 --- a/src/content/docs/en/guides/cms/datocms.mdx +++ b/src/content/docs/en/guides/cms/datocms.mdx @@ -6,6 +6,7 @@ stub: false service: DatoCMS i18nReady: true --- +import { Steps } from '@astrojs/starlight/components'; import { FileTree } from '@astrojs/starlight/components'; [DatoCMS](https://datocms.com/) is a web-based, headless CMS to manage digital content for your sites and apps. @@ -38,7 +39,6 @@ interface ImportMetaEnv { } ``` - Your root directory should now include these files: @@ -85,7 +85,6 @@ const data = json.data.home; ---

{data.title}

- ``` This GraphQL query will fetch the `title` field in the `home` page from your DatoCMS Project. When you refresh your browser, you should see the title on your page. @@ -169,10 +168,8 @@ const data = json.data.home; } }) } - ``` - ## Publishing your site To deploy your website, visit our [deployment guides](/en/guides/deploy/) and follow the instructions for your preferred hosting provider. @@ -185,17 +182,25 @@ If your project is using Astro’s default static mode, you will need to set up To set up a webhook in Netlify: + 1. Go to your site dashboard and click on **Build & deploy**. + 2. Under the **Continuous Deployment** tab, find the **Build hooks** section and click on **Add build hook**. + 3. Provide a name for your webhook and select the branch you want to trigger the build on. Click on **Save** and copy the generated URL. + ### Vercel To set up a webhook in Vercel: + 1. Go to your project dashboard and click on **Settings**. + 2. Under the **Git** tab, find the **Deploy Hooks** section. + 3. Provide a name for your webhook and the branch you want to trigger the build on. Click **Add** and copy the generated URL. + ### Adding a webhook to DatoCMS diff --git a/src/content/docs/en/guides/cms/decap-cms.mdx b/src/content/docs/en/guides/cms/decap-cms.mdx index 15464d0da6979..b5a1bd35170e0 100644 --- a/src/content/docs/en/guides/cms/decap-cms.mdx +++ b/src/content/docs/en/guides/cms/decap-cms.mdx @@ -6,10 +6,11 @@ stub: true service: Decap CMS i18nReady: true --- -import Grid from '~/components/FluidGrid.astro' -import Card from '~/components/ShowcaseCard.astro' -import { FileTree } from '@astrojs/starlight/components' -import PackageManagerTabs from '~/components/tabs/PackageManagerTabs.astro' +import Grid from '~/components/FluidGrid.astro'; +import Card from '~/components/ShowcaseCard.astro'; +import { Steps } from '@astrojs/starlight/components'; +import { FileTree } from '@astrojs/starlight/components'; +import PackageManagerTabs from '~/components/tabs/PackageManagerTabs.astro'; [Decap CMS](https://www.decapcms.org/) (formerly Netlify CMS) is an open-source, Git-based content management system. @@ -55,13 +56,16 @@ There are two options for adding Decap to Astro: ## Configuration + 1. Create a static admin folder at `public/admin/` -2. Add `config.yml` to `public/admin/`: + +2. Add `config.yml` to `public/admin/`: - public - admin - config.yml + 3. To add support for content collections, configure each schema in `config.yml`. The following example configures a `blog` collection, defining a `label` for each entry's frontmatter property: ```yml title="/public/admin/config.yml" collections: @@ -79,7 +83,6 @@ There are two options for adding Decap to Astro: ``` 4. Add the `admin` route for your React app. This file can be either `public/admin/index.html` alongside your `config.yml` or, if you prefer to use an Astro route, `src/pages/admin.astro`. - - public - admin @@ -107,6 +110,7 @@ There are two options for adding Decap to Astro: media_folder: "src/assets/images" # Location where files will be stored in the repo public_folder: "src/assets/images" # The src attribute for uploaded media ``` + See the [the Decap CMS configuration documentation](https://decapcms.org/docs/configure-decap-cms/) for full instructions and options. diff --git a/src/content/docs/en/guides/cms/hygraph.mdx b/src/content/docs/en/guides/cms/hygraph.mdx index dee8fdec55d13..9d93353c710f7 100644 --- a/src/content/docs/en/guides/cms/hygraph.mdx +++ b/src/content/docs/en/guides/cms/hygraph.mdx @@ -5,6 +5,7 @@ type: cms service: Hygraph i18nReady: true --- +import { Steps } from '@astrojs/starlight/components'; import { FileTree } from '@astrojs/starlight/components'; [Hygraph](https://hygraph.com/) is a federated content management platform. It exposes a GraphQL endpoint for fetching content. @@ -110,6 +111,7 @@ const posts: Post[] = json.data.blogPosts; To set up a webhook in Netlify: + 1. Deploy your site to Netlify with [this guide](/en/guides/deploy/netlify/). Remember to add your `HYGRAPH_ENDPOINT` to the environment variables. 2. Then Go to your Hygraph project dashboard and click on **Apps**. @@ -117,6 +119,7 @@ To set up a webhook in Netlify: 3. Go to the marketplace and search for Netlify and follow the instructions provided. 4. If all went good, now you can deploy your website with a click in the Hygraph interface. + ## Community Resources diff --git a/src/content/docs/en/guides/cms/keystatic.mdx b/src/content/docs/en/guides/cms/keystatic.mdx index 06fbe24b05ec0..50bd7590a1d0d 100644 --- a/src/content/docs/en/guides/cms/keystatic.mdx +++ b/src/content/docs/en/guides/cms/keystatic.mdx @@ -5,8 +5,9 @@ type: cms service: Keystatic i18nReady: true --- +import { Steps } from '@astrojs/starlight/components'; import { FileTree } from '@astrojs/starlight/components'; -import PackageManagerTabs from '~/components/tabs/PackageManagerTabs.astro' +import PackageManagerTabs from '~/components/tabs/PackageManagerTabs.astro'; [Keystatic](https://keystatic.com/) is an open source, headless content-management system that allows you to structure your content and sync it with GitHub. @@ -157,30 +158,30 @@ Visit `http://127.0.0.1:4321/keystatic` in the browser to see the Keystatic Admi ## Creating a new post + 1. In the Keystatic Admin UI dashboard, click on the “Posts” collection. - 2. Use the button to create a new post. Add the title "My First Post" and some content, then save the post. - - 3. This post should now be visible from your "Posts" collection. You can view and edit your individual posts from this dashboard page. - - 4. Return to view your Astro project files. You will now find a new `.mdoc` file inside the `src/content/posts` directory for this new post: +2. Use the button to create a new post. Add the title "My First Post" and some content, then save the post. - - - src/ - - content/ - - posts/ - - **my-first-post.mdoc** - +3. This post should now be visible from your "Posts" collection. You can view and edit your individual posts from this dashboard page. -5. Navigate to that file in your code editor and verify that you can see the Markdown content you entered. For example: +4. Return to view your Astro project files. You will now find a new `.mdoc` file inside the `src/content/posts` directory for this new post: + + - src/ + - content/ + - posts/ + - **my-first-post.mdoc** + - ```markdown - --- - title: My First Post - --- - - This is my very first post. I am **super** excited! - ``` +5. Navigate to that file in your code editor and verify that you can see the Markdown content you entered. For example: + ```markdown + --- + title: My First Post + --- + + This is my very first post. I am **super** excited! + ``` + ## Rendering Keystatic content diff --git a/src/content/docs/en/guides/cms/kontent-ai.mdx b/src/content/docs/en/guides/cms/kontent-ai.mdx index 62d7243517c35..89cca003819a3 100644 --- a/src/content/docs/en/guides/cms/kontent-ai.mdx +++ b/src/content/docs/en/guides/cms/kontent-ai.mdx @@ -5,6 +5,7 @@ type: cms service: Kontent.ai i18nReady: true --- +import { Steps } from '@astrojs/starlight/components'; import { FileTree } from '@astrojs/starlight/components'; import PackageManagerTabs from '~/components/tabs/PackageManagerTabs.astro' @@ -529,19 +530,27 @@ If your project is using Astro's default static mode, you will need to set up a To set up a webhook in Netlify: + 1. Go to your site dashboard and click on **Build & deploy**. + 2. Under the **Continuous Deployment** tab, find the **Build hooks** section and click on **Add build hook**. + 3. Provide a name for your webhook and select the branch you want to trigger the build on. Click on **Save** and copy the generated URL. + ##### Vercel To set up a webhook in Vercel: + 1. Go to your project dashboard and click on **Settings**. + 2. Under the **Git** tab, find the **Deploy Hooks** section. + 3. Provide a name for your webhook and the branch you want to trigger the build on. Click **Add** and copy the generated URL. + -Adding a webhook to Kontent.ai +##### Adding a webhook to Kontent.ai In the [Kontent.ai app](https://kontent.ai/learn/docs/webhooks/javascript), go to **Environment settings -> Webhooks**. Click on **Create new webhook** and provide a name for your new webhook. Paste in the URL you copied from Netlify or Vercel and select which events should trigger the webhook. By default, for rebuilding your site when published content changes, you only need **Publish** and **Unpublish** events under **Delivery API triggers**. When you're finished, click on Save. diff --git a/src/content/docs/en/guides/cms/payload.mdx b/src/content/docs/en/guides/cms/payload.mdx index 8d1afdce5e455..29f24b4918716 100644 --- a/src/content/docs/en/guides/cms/payload.mdx +++ b/src/content/docs/en/guides/cms/payload.mdx @@ -6,6 +6,7 @@ stub: true service: Payload CMS i18nReady: true --- +import { Steps } from '@astrojs/starlight/components'; [PayloadCMS](https://payloadcms.com/) is a headless open-source content management system that can be used to provide content for your Astro project. @@ -13,7 +14,6 @@ i18nReady: true ### Prerequisites - 1. **An Astro project** - If you don't have an Astro project yet, our [Installation guide](/en/install/auto/) will get you up and running in no time. 2. **A MongoDB database** - PayloadCMS will ask you for a MongoDB connection string when creating a new project. You can set one up locally or use [MongoDBAtlas](https://www.mongodb.com/) to host a database on the web for free. 3. **A PayloadCMS REST API** - Create a [PayloadCMS](https://payloadcms.com/docs/getting-started/installation) project and connect it to your MongoDB database during the setup. @@ -28,8 +28,7 @@ Choosing any of the available templates at this step (such as 'blog') automatica Your Payload project template will contain a file called Posts.ts in `src/collections/`. If you did not choose a template during installation that created a content collection for you, you can create a new Payload CMS Collection by adding this configuration file manually. The example below shows this file for a collection called `posts` that requires `title`, `content`, and `slug` fields: - -```astro title="src/collections/Posts.ts" +```ts title="src/collections/Posts.ts" import { CollectionConfig } from "payload/types"; const Posts: CollectionConfig = { @@ -63,9 +62,9 @@ const Posts: CollectionConfig = { export default Posts; ``` + 1. Import and add both `Users` (available in all PayloadCMS projects) and any other collections (e.g. `Posts`) to the available collections in the `payload.config.ts` file. - - ```astro title="src/payload.config.ts" ins={4, 5, 12} + ```ts title="src/payload.config.ts" ins={4, 5, 12} import { buildConfig } from "payload/config"; import path from "path"; @@ -92,7 +91,6 @@ export default Posts; 2. Enter the "Posts" collection and create a new post. After saving it, you will notice the API URL appear in the bottom right corner. 3. With the dev server running, open `http://localhost:4321/api/posts` in your browser. You should see a JSON file containing the post you have created as an object. - ```json { "docs":[ @@ -116,6 +114,7 @@ export default Posts; "nextPage":null } ``` + :::tip By default, both Astro and PayloadCMS will use port 4321. You might want to change the PayloadCMS port in the `src/server.ts` file. Don't forget to update the `serverURL` in `src/payload.config.ts` as well. @@ -216,9 +215,7 @@ export async function getStaticPaths() { To deploy your site visit our [deployment guide](/en/guides/deploy/) and follow the instructions for your preferred hosting provider. - ## Community Resources - Try this [Payload CMS & Astro Template](https://github.com/Lambdo-Labs/payloadcms-astro-template). - Check out [Astroad](https://github.com/mooxl/astroad) for easy development and VPS deployment with Docker. - diff --git a/src/content/docs/en/guides/cms/preprcms.mdx b/src/content/docs/en/guides/cms/preprcms.mdx index db3e6876aead6..351a8d33bf30f 100644 --- a/src/content/docs/en/guides/cms/preprcms.mdx +++ b/src/content/docs/en/guides/cms/preprcms.mdx @@ -6,8 +6,9 @@ service: Prepr CMS stub: true i18nReady: true --- +import { Steps } from '@astrojs/starlight/components'; import { FileTree } from '@astrojs/starlight/components'; -import PackageManagerTabs from '~/components/tabs/PackageManagerTabs.astro' +import PackageManagerTabs from '~/components/tabs/PackageManagerTabs.astro'; [Prepr CMS](https://www.prepr.io/) is a headless CMS with built-in personalization. @@ -32,8 +33,12 @@ PREPR_ENDPOINT=YOUR_PREPR_API_URL ``` You will find your `YOUR_PREPR_API_URL` value from your Prepr account settings: + + 1. Go to  **Settings > Access tokens** to view both your Preview and Production access tokens. + 2. Use the **API URL** value from the **GraphQL Production** access token to only retrieve published content items for your Astro site. + ### Configuring the Prepr endpoint @@ -70,9 +75,11 @@ Your root directory should now include these files: You will fetch your data from Prepr by writing queries to interact with its GraphQL API. #### Create a GraphQL query to retrieve your blog articles: + + 1. Create a new folder `src/queries/` and add a file named `get-articles.js`. -2. Add the following query to this file to retrieve all articles: +2. Add the following query to this file to retrieve all articles: ```js title="src/queries/get-articles.js" const GetArticles = ` @@ -90,7 +97,6 @@ You will fetch your data from Prepr by writing queries to interact with its Grap ``` 3. To display a linked list of your blog posts on a page, import and execute your query, including the necessary Prepr endpoint. You will then have access to all your posts titles and their slugs to render to the page. (In the next step, you will [create individual pages for your blog posts](#creating-individual-blog-post-pages).) - ```astro title="src/pages/index.astro" ins={3-4, 6-8, 15-23} --- import Layout from '../layouts/Layout.astro'; @@ -117,7 +123,7 @@ You will fetch your data from Prepr by writing queries to interact with its Grap ``` - + Your root directory should include these new files: @@ -136,10 +142,9 @@ Your root directory should include these new files: To create a page for each blog post, you will execute a new GraphQL query on a [dynamic routing](/en/guides/routing/#server-ssr-mode) `.astro` page. This query will fetch a specific article by its slug and a new page will be created for each individual blog post. + 1. Create a file called `get-article-by-slug.js` in the `queries` folder and add the following to query a specific article by its slug and return data such as the article `title` and `content`: - ```js title="src/lib/queries/get-article-by-slug.js" - const GetArticleBySlug = ` query ($slug: String) {    Article (slug: $slug) { @@ -163,13 +168,12 @@ To create a page for each blog post, you will execute a new GraphQL query on a [ export default GetArticleBySlug ``` -:::tip -You can create and [test GraphQL queries](https://docs.prepr.io/reference/graphql/v1/test-queries) using the [Apollo explorer](https://studio.apollographql.com/sandbox/explorer) in Prepr. Open the API Explorer from the *Article* content item page in Prepr. -The Article content is stored in a *Dynamic content field*. Check out the GraphQL docs for more details on [how to fetch the data within this field](https://docs.prepr.io/reference/graphql/v1/schema-field-types-dynamic-content-field). -::: + :::tip + You can create and [test GraphQL queries](https://docs.prepr.io/reference/graphql/v1/test-queries) using the [Apollo explorer](https://studio.apollographql.com/sandbox/explorer) in Prepr. Open the API Explorer from the *Article* content item page in Prepr. + The Article content is stored in a *Dynamic content field*. Check out the GraphQL docs for more details on [how to fetch the data within this field](https://docs.prepr.io/reference/graphql/v1/schema-field-types-dynamic-content-field). + ::: 2. Inside the `src/pages` folder, create a file called `[…slug].astro`. Add the following code to import and execute the query from the previous step and display the retrieved article: - ```astro title="src/pages/[...slug].astro" --- import Layout from '../layouts/Layout.astro'; @@ -202,6 +206,7 @@ The Article content is stored in a *Dynamic content field*. Check out the GraphQ ``` + Your root directory should now include these new files: diff --git a/src/content/docs/en/guides/cms/sitecore.mdx b/src/content/docs/en/guides/cms/sitecore.mdx index 677825bfd14c9..acd33c773bd6a 100644 --- a/src/content/docs/en/guides/cms/sitecore.mdx +++ b/src/content/docs/en/guides/cms/sitecore.mdx @@ -6,17 +6,22 @@ stub: true service: Sitecore XM i18nReady: true --- +import { Steps } from '@astrojs/starlight/components'; [Sitecore Experience Manager (XM)](https://www.sitecore.com/products/experience-manager) is an enterprise-level content management system built on ASP.NET. ## Getting started + 1. [Create a Sitecore Headless website](https://doc.sitecore.com/xp/en/developers/sxa/103/sitecore-experience-accelerator/create-a-headless-tenant-and-site.html) following Sitcore's official documentation. + 2. Run the following project initialization command in your terminal: - ```shell - npx @astro-sitecore-jss/create-astro-sitecore-jss@latest - ``` + ```shell + npx @astro-sitecore-jss/create-astro-sitecore-jss@latest + ``` + 3. Follow the instructions in the terminal to create your project. + ## Community Resources diff --git a/src/content/docs/en/guides/cms/spinal.mdx b/src/content/docs/en/guides/cms/spinal.mdx index 0567f2cb71636..65ff12e24b4fb 100644 --- a/src/content/docs/en/guides/cms/spinal.mdx +++ b/src/content/docs/en/guides/cms/spinal.mdx @@ -6,14 +6,19 @@ stub: true service: Spinal i18nReady: true --- +import { Steps } from '@astrojs/starlight/components'; [Spinal](https://spinalcms.com/cms-for-astro/) is a commercial, SaaS-focused, Git-based CMS. ## Getting started + 1. [Create a Spinal account](https://spinalcms.com/signup/). + 2. Connect your GitHub account to Spinal. + 3. Select your Astro repository when prompted. + All Markdown content from the selected folder will be imported into your Spinal account and is ready to be edited. diff --git a/src/content/docs/en/guides/cms/storyblok.mdx b/src/content/docs/en/guides/cms/storyblok.mdx index d59215169cf33..e022153ba0862 100644 --- a/src/content/docs/en/guides/cms/storyblok.mdx +++ b/src/content/docs/en/guides/cms/storyblok.mdx @@ -6,6 +6,7 @@ service: Storyblok stub: false i18nReady: true --- +import { Steps } from '@astrojs/starlight/components'; import { FileTree } from '@astrojs/starlight/components'; import PackageManagerTabs from '~/components/tabs/PackageManagerTabs.astro' @@ -508,21 +509,25 @@ If your project is using Astro's default static mode, you will need to set up a To set up a webhook in Netlify: + 1. Go to your site dashboard and click on **Build & deploy**. 2. Under the **Continuous Deployment** tab, find the **Build hooks** section and click on **Add build hook**. 3. Provide a name for your webhook and select the branch you want to trigger the build on. Click on **Save** and copy the generated URL. + ##### Vercel To set up a webhook in Vercel: + 1. Go to your project dashboard and click on **Settings**. 2. Under the **Git** tab, find the **Deploy Hooks** section. 3. Provide a name for your webhook and the branch you want to trigger the build on. Click **Add** and copy the generated URL. + ##### Adding a webhook to Storyblok diff --git a/src/content/docs/en/guides/cms/strapi.mdx b/src/content/docs/en/guides/cms/strapi.mdx index 1f3d83995cb51..bc79d661c71c8 100644 --- a/src/content/docs/en/guides/cms/strapi.mdx +++ b/src/content/docs/en/guides/cms/strapi.mdx @@ -6,7 +6,7 @@ service: Strapi stub: false i18nReady: true --- - +import { Steps } from '@astrojs/starlight/components'; import { FileTree } from '@astrojs/starlight/components'; import PackageManagerTabs from '~/components/tabs/PackageManagerTabs.astro'; @@ -146,78 +146,78 @@ You can modify this interface, or create multiple interfaces, to correspond to y ### Displaying a list of articles + 1. Update your home page `src/pages/index.astro` to display a list of blog posts, each with a description and a link to its own page. 2. Import the wrapper function and the interface. Add the following API call to fetch your articles and return a list: - - ```astro title="src/pages/index.astro" - --- - import fetchApi from '../lib/strapi'; - import type Article from '../interfaces/article'; - - const articles = await fetchApi({ - endpoint: 'articles', // the content type to fetch - wrappedByKey: 'data', // the key to unwrap the response - }); - --- - ``` - - The API call requests data from `http://localhost:1337/api/articles` and returns `articles`: an array of json objects representing your data: - - ```json - [ - { - id: 1, - attributes: { - title: "What's inside a Black Hole", - description: "Maybe the answer is in this article, or not...", - content: "Well, we don't know yet...", - slug: "what-s-inside-a-black-hole", - createdAt: "2023-05-28T13:19:46.421Z", - updatedAt: "2023-05-28T13:19:46.421Z", - publishedAt: "2023-05-28T13:19:45.826Z" - } - }, - // ... - ] - ``` + ```astro title="src/pages/index.astro" + --- + import fetchApi from '../lib/strapi'; + import type Article from '../interfaces/article'; + + const articles = await fetchApi({ + endpoint: 'articles', // the content type to fetch + wrappedByKey: 'data', // the key to unwrap the response + }); + --- + ``` + + The API call requests data from `http://localhost:1337/api/articles` and returns `articles`: an array of json objects representing your data: + + ```json + [ + { + id: 1, + attributes: { + title: "What's inside a Black Hole", + description: "Maybe the answer is in this article, or not...", + content: "Well, we don't know yet...", + slug: "what-s-inside-a-black-hole", + createdAt: "2023-05-28T13:19:46.421Z", + updatedAt: "2023-05-28T13:19:46.421Z", + publishedAt: "2023-05-28T13:19:45.826Z" + } + }, + // ... + ] + ``` 3. Using data from the `articles` array returned by the API, display your Strapi blog posts in a list. These posts will link to their own individual pages, which you will create in the next step. - - ```astro title="src/pages/index.astro" - --- - import fetchApi from '../lib/strapi'; - import type Article from '../interfaces/article'; - - const articles = await fetchApi({ - endpoint: 'articles?populate=image', - wrappedByKey: 'data', - }); - --- - - - - - Strapi & Astro - - - -
- -
- - - ``` + ```astro title="src/pages/index.astro" + --- + import fetchApi from '../lib/strapi'; + import type Article from '../interfaces/article'; + + const articles = await fetchApi({ + endpoint: 'articles?populate=image', + wrappedByKey: 'data', + }); + --- + + + + + Strapi & Astro + + + +
+ +
+ + + ``` + ### Generating article pages @@ -267,7 +267,6 @@ const article = Astro.props; Create the template for each page using the properties of each post object. - ```astro title="src/pages/blog/[slug].astro ins={21-43} --- import fetchApi from '../../lib/strapi'; @@ -401,21 +400,25 @@ If your project is using Astro's default static mode, you will need to set up a To set up a webhook in Netlify: + 1. Go to your site dashboard and click on **Build & deploy**. 2. Under the **Continuous Deployment** tab, find the **Build hooks** section and click on **Add build hook**. 3. Provide a name for your webhook and select the branch you want to trigger the build on. Click on **Save** and copy the generated URL. + ##### Vercel To set up a webhook in Vercel: + 1. Go to your project dashboard and click on **Settings**. 2. Under the **Git** tab, find the **Deploy Hooks** section. 3. Provide a name for your webhook and the branch you want to trigger the build on. Click **Add** and copy the generated URL. + ##### Adding a webhook to Strapi diff --git a/src/content/docs/en/guides/cms/tina-cms.mdx b/src/content/docs/en/guides/cms/tina-cms.mdx index 2f0aea68878ff..9133ee5ce05c1 100644 --- a/src/content/docs/en/guides/cms/tina-cms.mdx +++ b/src/content/docs/en/guides/cms/tina-cms.mdx @@ -6,9 +6,10 @@ stub: false service: Tina CMS i18nReady: true --- -import PackageManagerTabs from '~/components/tabs/PackageManagerTabs.astro' -import Grid from '~/components/FluidGrid.astro' -import Card from '~/components/ShowcaseCard.astro' +import PackageManagerTabs from '~/components/tabs/PackageManagerTabs.astro'; +import Grid from '~/components/FluidGrid.astro'; +import Card from '~/components/ShowcaseCard.astro'; +import { Steps } from '@astrojs/starlight/components'; [Tina CMS](https://tina.io/) is a Git-backed headless content management system. @@ -16,6 +17,7 @@ import Card from '~/components/ShowcaseCard.astro' To get started, you'll need an existing Astro project. + 1. Run the following command to install Tina into your Astro project. @@ -145,6 +147,7 @@ To get started, you'll need an existing Astro project. Learn more about Tina collections [in the Tina docs](https://tina.io/docs/reference/collections/). 5. In production, TinaCMS can commit changes directly to your GitHub repository. To set up TinaCMS for production, you can choose to use [Tina Cloud](https://tina.io/docs/tina-cloud/) or self-host the [Tina Data Layer](https://tina.io/docs/self-hosted/overview/). You can [read more about registering for Tina Cloud](https://app.tina.io/register) in the Tina Docs. + ## Official Resources @@ -160,4 +163,4 @@ To get started, you'll need an existing Astro project. - \ No newline at end of file + diff --git a/src/content/docs/en/guides/deploy/aws.mdx b/src/content/docs/en/guides/deploy/aws.mdx index 0bdab62a2f96a..7bc92f373c89f 100644 --- a/src/content/docs/en/guides/deploy/aws.mdx +++ b/src/content/docs/en/guides/deploy/aws.mdx @@ -4,7 +4,8 @@ description: How to deploy your Astro site to the web using AWS. type: deploy i18nReady: true --- -import PackageManagerTabs from '~/components/tabs/PackageManagerTabs.astro' +import { Steps } from '@astrojs/starlight/components'; +import PackageManagerTabs from '~/components/tabs/PackageManagerTabs.astro'; [AWS](https://aws.amazon.com/) is a full-featured web app hosting platform that can be used to deploy an Astro site. @@ -14,8 +15,11 @@ Deploying your project to AWS requires using the [AWS console](https://aws.amazo AWS Amplify is a set of purpose-built tools and features that lets frontend web and mobile developers quickly and easily build full-stack applications on AWS. + 1. Create a new Amplify Hosting project. + 2. Connect your repository to Amplify. + 3. Modify your build settings to match your project's build process. @@ -82,6 +86,7 @@ AWS Amplify is a set of purpose-built tools and features that lets frontend web ``` + Amplify will automatically deploy your website and update it when you push a commit to your repository. @@ -89,6 +94,7 @@ Amplify will automatically deploy your website and update it when you push a com S3 is the starting point of any application. It is where your project files and other assets are stored. S3 charges for file storage and number of requests. You can find more information about S3 in the [AWS documentation](https://aws.amazon.com/s3/). + 1. Create an S3 bucket with your project's name. :::tip @@ -129,6 +135,7 @@ S3 is the starting point of any application. It is where your project files and :::note If you are deploying a single-page application (SPA), set your error document to `index.html`. ::: + ## S3 with CloudFront @@ -148,6 +155,7 @@ When connecting CloudFront to an S3 static website endpoint, you rely on S3 buck There are many ways to set up continuous deployment for AWS. One possibility for code hosted on GitHub is to use [GitHub Actions](https://github.com/features/actions) to deploy your website every time you push a commit. + 1. Create a new policy in your AWS account using [IAM](https://aws.amazon.com/iam/) with the following permissions. This policy will allow you to upload built files to your S3 bucket and invalidate the CloudFront distribution files when you push a commit. ```json @@ -214,6 +222,7 @@ There are many ways to set up continuous deployment for AWS. One possibility for :::note Your `BUCKET_ID` is the name of your S3 bucket. Your `DISTRIBUTION_ID` is your CloudFront distribution ID. You can find your CloudFront distribution ID in **CloudFront > Distributions > ID** ::: + ## Community Resources diff --git a/src/content/docs/en/guides/deploy/buddy.mdx b/src/content/docs/en/guides/deploy/buddy.mdx index 90409aeea00e9..14c6a6777b59d 100644 --- a/src/content/docs/en/guides/deploy/buddy.mdx +++ b/src/content/docs/en/guides/deploy/buddy.mdx @@ -4,6 +4,7 @@ description: How to deploy your Astro site to the web using Buddy. type: deploy i18nReady: true --- +import { Steps } from '@astrojs/starlight/components'; You can deploy your Astro project using [Buddy](https://buddy.works/), a CI/CD solution that can build your site and push it to many different deploy targets including FTP servers and cloud hosting providers. @@ -13,10 +14,15 @@ Buddy itself will not host your site. Instead, it helps you manage the build pro ## How to deploy + 1. [Create a **Buddy** account](https://buddy.works/sign-up). + 2. Create a new project and connect it with a git repository (GitHub, GitLab, BitBucket, any private Git Repository or you can use Buddy Git Hosting). + 3. Add a new pipeline. + 4. In the newly created pipeline add a **[Node.js](https://buddy.works/actions/node-js)** action. + 5. In this action add: ```bash @@ -25,4 +31,6 @@ Buddy itself will not host your site. Instead, it helps you manage the build pro ``` 6. Add a deployment action — there are many to choose from, you can browse them in [Buddy’s actions catalog](https://buddy.works/actions). Although their settings can differ, remember to set the **Source path** to `dist`. + 7. Press the **Run** button. + diff --git a/src/content/docs/en/guides/deploy/cleavr.mdx b/src/content/docs/en/guides/deploy/cleavr.mdx index df9baf5f2cf64..e63e8a6693c0c 100644 --- a/src/content/docs/en/guides/deploy/cleavr.mdx +++ b/src/content/docs/en/guides/deploy/cleavr.mdx @@ -4,6 +4,7 @@ description: How to deploy your Astro site to your VPS server using Cleavr. type: deploy i18nReady: true --- +import { Steps } from '@astrojs/starlight/components'; You can deploy your Astro project to your own Virtual Private Server (VPS) using [Cleavr](https://cleavr.io/), a server and app deployment management tool. @@ -20,6 +21,7 @@ To get started, you will need: ## Add your site + 1. In Cleavr, navigate to the server you want to add your Astro project to. 2. Select **Add Site** and fill in the details for your application, such as domain name. @@ -33,10 +35,11 @@ To get started, you will need: - Set **Artifact Folder** to `dist/server`. 6. Select **Add** to add the site to your server. - + ## Setup and deploy + 1. Once your new site is added, click **Setup and deploy**. 2. Select the **VC Profile**, **Repo**, and **Branch** for your Astro Project. @@ -44,5 +47,6 @@ To get started, you will need: 3. Make any additional configurations necessary for your project. 4. Click on the **Deployments** tab and then click on **Deploy**. + Congratulations, you've just deployed your Astro app! diff --git a/src/content/docs/en/guides/deploy/cloudflare.mdx b/src/content/docs/en/guides/deploy/cloudflare.mdx index 176149921ea3f..181b814700d10 100644 --- a/src/content/docs/en/guides/deploy/cloudflare.mdx +++ b/src/content/docs/en/guides/deploy/cloudflare.mdx @@ -4,7 +4,8 @@ description: How to deploy your Astro site to the web using Cloudflare Pages. type: deploy i18nReady: true --- -import ReadMore from '~/components/ReadMore.astro' +import ReadMore from '~/components/ReadMore.astro'; +import { Steps } from '@astrojs/starlight/components'; You can deploy your Astro project on [Cloudflare Pages](https://pages.cloudflare.com/), a platform for frontend developers to collaborate and deploy static (JAMstack) and SSR websites. @@ -23,11 +24,17 @@ To get started, you will need: ## How to deploy a site with Git + 1. Set up a new project on Cloudflare Pages. + 2. Push your code to your git repository (GitHub, GitLab). + 3. Log in to the Cloudflare dashboard and select your account in **Account Home** > **Pages**. + 4. Select **Create a new Project** and the **Connect Git** option. + 5. Select the git project you want to deploy and click **Begin setup** + 6. Use the following build settings: - **Framework preset**: `Astro` @@ -35,13 +42,19 @@ To get started, you will need: - **Build output directory:** `dist` 7. Click the **Save and Deploy** button. + ## How to deploy a site using Wrangler + 1. Install [Wrangler CLI](https://developers.cloudflare.com/workers/wrangler/get-started/). + 2. Authenticate Wrangler with your Cloudflare account using `wrangler login`. + 3. Run your build command. + 4. Deploy using `npx wrangler pages deploy dist`. + ```bash # Install Wrangler CLI @@ -66,7 +79,6 @@ pnpm add wrangler --save-dev It's then possible to update the preview script to run `wrangler` instead of Astro’s built-in preview command: - ```json title="package.json" "preview": "wrangler pages dev ./dist" ``` @@ -89,6 +101,7 @@ npx astro add cloudflare If you prefer to install the adapter manually instead, complete the following two steps: + 1. Add the `@astrojs/cloudflare` adapter to your project's dependencies using your preferred package manager. If you're using npm or aren't sure, run this in the terminal: ```bash @@ -106,6 +119,7 @@ If you prefer to install the adapter manually instead, complete the following tw adapter: cloudflare() }); ``` + Read more about [SSR in Astro](/en/guides/server-side-rendering/). diff --git a/src/content/docs/en/guides/deploy/deno.mdx b/src/content/docs/en/guides/deploy/deno.mdx index 17403c48461cc..d34c2ddb42c0f 100644 --- a/src/content/docs/en/guides/deploy/deno.mdx +++ b/src/content/docs/en/guides/deploy/deno.mdx @@ -4,7 +4,8 @@ description: How to deploy your Astro site to the web using Deno. type: deploy i18nReady: true --- -import ReadMore from '~/components/ReadMore.astro' +import ReadMore from '~/components/ReadMore.astro'; +import { Steps } from '@astrojs/starlight/components'; You can deploy a server-side rendered Astro site to [Deno Deploy](https://deno.com/deploy), a distributed system that runs JavaScript, TypeScript, and WebAssembly at the edge, worldwide. @@ -32,13 +33,14 @@ npx astro add deno If you prefer to install the adapter manually instead, complete the following two steps: + 1. Install [the `@astrojs/deno` adapter][Deno adapter] to your project’s dependencies using your preferred package manager. If you’re using npm or aren’t sure, run this in the terminal: ```bash npm install @astrojs/deno ``` -1. Update your `astro.config.mjs` project configuration file with the changes below. +2. Update your `astro.config.mjs` project configuration file with the changes below. ```js ins={3,6-7} // astro.config.mjs @@ -72,6 +74,7 @@ If you prefer to install the adapter manually instead, complete the following tw ```bash npm run preview ``` + ## How to deploy an SSR Astro site @@ -81,13 +84,14 @@ You can deploy to Deno Deploy through GitHub Actions or using Deno Deploy’s CL If your project is stored on GitHub, the [Deno Deploy website](https://dash.deno.com/) will guide you through setting up GitHub Actions to deploy your Astro site. + 1. Push your code to a public or private GitHub repository. -1. Sign in on [Deno Deploy](https://dash.deno.com/) with your GitHub account, and click on [New Project](https://dash.deno.com). +2. Sign in on [Deno Deploy](https://dash.deno.com/) with your GitHub account, and click on [New Project](https://dash.deno.com). -1. Select your repository, the branch you want to deploy from, and select **GitHub Action** mode. (Your Astro site requires a build step, and cannot use Automatic mode.) +3. Select your repository, the branch you want to deploy from, and select **GitHub Action** mode. (Your Astro site requires a build step, and cannot use Automatic mode.) -1. In your Astro project, create a new file at `.github/workflows/deploy.yml` and paste in the YAML below. This is similar to the YAML given by Deno Deploy, with the additional steps needed for your Astro site. +4. In your Astro project, create a new file at `.github/workflows/deploy.yml` and paste in the YAML below. This is similar to the YAML given by Deno Deploy, with the additional steps needed for your Astro site. ```yaml name: Deploy @@ -121,26 +125,27 @@ If your project is stored on GitHub, the [Deno Deploy website](https://dash.deno root: dist ``` -1. After committing this YAML file, and pushing to GitHub on your configured deploy branch, the deploy should begin automatically! +5. After committing this YAML file, and pushing to GitHub on your configured deploy branch, the deploy should begin automatically! You can track the progress using the "Actions" tab on your GitHub repository page, or on [Deno Deploy](https://dash.deno.com). - + ### CLI Deployment + 1. Install the [Deno Deploy CLI](https://docs.deno.com/deploy/manual/deployctl). ```bash deno install --allow-read --allow-write --allow-env --allow-net --allow-run --no-check -r -f https://deno.land/x/deploy/deployctl.ts ``` -1. Run your Astro build step. +2. Run your Astro build step. ```bash npm run build ``` -1. Run `deployctl` to deploy! +3. Run `deployctl` to deploy! In the command below, replace `` with your [Personal Access Token](https://dash.deno.com/account#access-tokens) and `` with your Deno Deploy project name. @@ -150,7 +155,7 @@ If your project is stored on GitHub, the [Deno Deploy website](https://dash.deno You can track all your deploys on [Deno Deploy](https://dash.deno.com). -1. (Optional) To simplify the build and deploy into one command, add a `deploy-deno` script in `package.json`. +4. (Optional) To simplify the build and deploy into one command, add a `deploy-deno` script in `package.json`. ```json ins={9} // package.json @@ -171,9 +176,8 @@ If your project is stored on GitHub, the [Deno Deploy website](https://dash.deno ```bash DENO_DEPLOY_TOKEN= npm run deno-deploy ``` - + Read more about [SSR in Astro](/en/guides/server-side-rendering/). - [Deno adapter]: https://github.com/denoland/deno-astro-adapter diff --git a/src/content/docs/en/guides/deploy/edgio.mdx b/src/content/docs/en/guides/deploy/edgio.mdx index de2ea4992db25..24b8ff4b9deea 100644 --- a/src/content/docs/en/guides/deploy/edgio.mdx +++ b/src/content/docs/en/guides/deploy/edgio.mdx @@ -4,6 +4,7 @@ description: How to deploy your Astro site to the web using Edgio. type: deploy i18nReady: true --- +import { Steps } from '@astrojs/starlight/components'; You can deploy your Astro project to [Edgio](https://www.edg.io/), an edge and CDN platform to deploy, protect and accelerate websites and APIs. @@ -13,6 +14,7 @@ Check out [the Astro guide in Edgio’s docs](https://docs.edg.io/guides/astro)! ## How to deploy + 1. Install [the Edgio CLI](https://docs.edg.io/guides/cli) globally from the Terminal, if you haven’t already. ```bash @@ -47,3 +49,4 @@ Check out [the Astro guide in Edgio’s docs](https://docs.edg.io/guides/astro)! ```bash edgio deploy ``` + diff --git a/src/content/docs/en/guides/deploy/flightcontrol.mdx b/src/content/docs/en/guides/deploy/flightcontrol.mdx index b588063250c1c..a94f6ee4c0678 100644 --- a/src/content/docs/en/guides/deploy/flightcontrol.mdx +++ b/src/content/docs/en/guides/deploy/flightcontrol.mdx @@ -4,6 +4,7 @@ description: How to deploy your Astro site to AWS with Flightcontrol type: deploy i18nReady: true --- +import { Steps } from '@astrojs/starlight/components'; You can deploy an Astro site using [Flightcontrol](https://www.flightcontrol.dev?ref=astro), which provides fully-automated deployments to your AWS account. @@ -11,15 +12,21 @@ Supports both static and SSR Astro sites. ## How to Deploy + 1. Create a Flightcontrol account at [app.flightcontrol.dev/signup](https://app.flightcontrol.dev/signup?ref=astro) + 2. Go to [app.flightcontrol.dev/projects/new/1](https://app.flightcontrol.dev/projects/new/1) + 3. Connect your GitHub account and select your repo + 4. Select your desired "Config Type": - `GUI` (all config managed through flightcontrol dashboard) where you will select the `Astro Static` or `Astro SSR` preset - `flightcontrol.json` ("infrastructure as code" option where all config is in your repo) where you will select an Astro example config, then add it to your codebase as `flightcontrol.json` + 5. Adjust any configuration as needed -6. Click "Create Project" and complete any required steps (like linking your AWS account). +6. Click "Create Project" and complete any required steps (like linking your AWS account). + ### SSR Setup diff --git a/src/content/docs/en/guides/deploy/flyio.mdx b/src/content/docs/en/guides/deploy/flyio.mdx index 5feb86fb8562d..4b9afb6fbc793 100644 --- a/src/content/docs/en/guides/deploy/flyio.mdx +++ b/src/content/docs/en/guides/deploy/flyio.mdx @@ -5,6 +5,7 @@ type: deploy i18nReady: true stub: true --- +import { Steps } from '@astrojs/starlight/components'; You can deploy your Astro project to [Fly.io](https://fly.io/), a platform for running full stack apps and databases close to your users. @@ -22,8 +23,11 @@ To enable on-demand rendering in your Astro project and deploy on Fly.io, add [t ## How to deploy + 1. [Sign up for Fly.io](https://fly.io/docs/getting-started/log-in-to-fly/#first-time-or-no-fly-account-sign-up-for-fly) if you haven't already. + 2. [Install `flyctl`](https://fly.io/docs/hands-on/install-flyctl/), your Fly.io app command center. + 3. Run the following command in your terminal. ```bash @@ -31,6 +35,7 @@ To enable on-demand rendering in your Astro project and deploy on Fly.io, add [t ``` `flyctl` will automatically detect Astro, configure the correct settings, build your image, and deploy it to the Fly.io platform. + ## Generating your Astro Dockerfile diff --git a/src/content/docs/en/guides/deploy/github.mdx b/src/content/docs/en/guides/deploy/github.mdx index 148bd42d3f090..c39a8fe875068 100644 --- a/src/content/docs/en/guides/deploy/github.mdx +++ b/src/content/docs/en/guides/deploy/github.mdx @@ -4,6 +4,7 @@ description: How to deploy your Astro site to the web using GitHub Pages. type: deploy i18nReady: true --- +import { Steps } from '@astrojs/starlight/components'; You can use [GitHub Pages](https://pages.github.com/) to host an Astro website directly from a repository on [GitHub.com](https://github.com/). @@ -35,7 +36,6 @@ The value for `site` must be one of the following: - The following URL based on your username: `https://.github.io` - The random URL autogenerated for a [GitHub Organization's private page](https://docs.github.com/en/enterprise-cloud@latest/pages/getting-started-with-github-pages/changing-the-visibility-of-your-github-pages-site): `https://.pages.github.io/` - #### `base` A value for `base` may be required so that Astro will treat your repository name (e.g. `/my-repo`) as the root of your website. @@ -83,6 +83,7 @@ export default defineConfig({ ## Configure a GitHub Action + 1. Create a new file in your project at `.github/workflows/deploy.yml` and paste in the YAML below. ```yaml title="deploy.yml" @@ -140,6 +141,6 @@ export default defineConfig({ 3. Choose **GitHub Actions** as the **Source** of your site. 4. Commit the new workflow file and push it to GitHub. - + Your site should now be published! When you push changes to your Astro project’s repository, the GitHub Action will automatically deploy them for you. diff --git a/src/content/docs/en/guides/deploy/gitlab.mdx b/src/content/docs/en/guides/deploy/gitlab.mdx index b37da5c9205b2..94d949c2eb4de 100644 --- a/src/content/docs/en/guides/deploy/gitlab.mdx +++ b/src/content/docs/en/guides/deploy/gitlab.mdx @@ -4,6 +4,7 @@ description: How to deploy your Astro site to the web using GitLab Pages. type: deploy i18nReady: true --- +import { Steps } from '@astrojs/starlight/components'; You can use [GitLab Pages](https://pages.gitlab.io/) to host an Astro site for your [GitLab](https://about.gitlab.com/) projects, groups, or user account. @@ -13,8 +14,11 @@ Check out [the official GitLab Pages Astro example project](https://gitlab.com/p ## How to deploy + 1. Set the correct `site` in `astro.config.mjs`. + 2. Rename the `public/` directory to `static`. + 3. Set `outDir:public` in `astro.config.mjs`. This setting instructs Astro to put the static build output in a folder called `public`, which is the folder required by GitLab Pages for exposed files. If you were using the [`public/` directory](/en/basics/project-structure/#public) as a source of static files in your Astro project, rename it and use that new folder name in `astro.config.mjs` for the value of `publicDir`. @@ -57,3 +61,4 @@ Check out [the official GitLab Pages Astro example project](https://gitlab.com/p # branch(es) below - main ``` + diff --git a/src/content/docs/en/guides/deploy/google-cloud.mdx b/src/content/docs/en/guides/deploy/google-cloud.mdx index 3ec1637c66c8e..71f21ae2487c5 100644 --- a/src/content/docs/en/guides/deploy/google-cloud.mdx +++ b/src/content/docs/en/guides/deploy/google-cloud.mdx @@ -4,6 +4,7 @@ description: How to deploy your Astro site to the web using Google Cloud. type: deploy i18nReady: true --- +import { Steps } from '@astrojs/starlight/components'; [Google Cloud](https://cloud.google.com/) is a full-featured web app hosting platform that can be used to deploy an Astro site. @@ -11,6 +12,7 @@ i18nReady: true ### Cloud Storage (static only) + 1. [Create a new GCP project](https://console.cloud.google.com/projectcreate), or select one you already have. 2. Create a new bucket under [Cloud Storage](https://cloud.google.com/storage). @@ -22,6 +24,7 @@ i18nReady: true 5. Enable public access by adding a new permission to `allUsers` called `Storage Object Viewer`. 6. Edit the website configuration and add `ìndex.html` as the entrypoint and `404.html` as the error page. + ### Cloud Run (SSR and static) @@ -29,12 +32,13 @@ Cloud Run is a serverless platform that allows you to run a container without ha #### Prepare the Service + 1. [Create a new GCP project](https://console.cloud.google.com/projectcreate), or select one you already have. 2. Make sure the [Cloud Run API](https://console.cloud.google.com/apis/library/run.googleapis.com) is enabled. 3. Create a new service. - + #### Create Dockerfile & Build the Container @@ -64,7 +68,6 @@ Change the following values in the commands above to match your project: - `TARGET-IMAGE`: the name for the image when it's stored in the registry. - `TAG` is the version associated with the image. - [Read more in the Google Cloud docs.](https://cloud.google.com/artifact-registry/docs/docker/pushing-and-pulling) **Using another tool**: diff --git a/src/content/docs/en/guides/deploy/google-firebase.mdx b/src/content/docs/en/guides/deploy/google-firebase.mdx index 5a5d571c22be1..ac9830e3362bf 100644 --- a/src/content/docs/en/guides/deploy/google-firebase.mdx +++ b/src/content/docs/en/guides/deploy/google-firebase.mdx @@ -4,7 +4,8 @@ description: How to deploy your Astro site to the web using Google’s Firebase type: deploy i18nReady: true --- -import PackageManagerTabs from '~/components/tabs/PackageManagerTabs.astro' +import { Steps } from '@astrojs/starlight/components'; +import PackageManagerTabs from '~/components/tabs/PackageManagerTabs.astro'; [Firebase Hosting](https://firebase.google.com/products/hosting) is a service provided by Google’s [Firebase](https://firebase.google.com/) app development platform, which can be used to deploy an Astro site. @@ -28,6 +29,7 @@ Deploying an SSR Astro site to Firebase requires the [Blaze plan](https://fireba ## How to deploy + 1. Install the [Firebase CLI](https://github.com/firebase/firebase-tools). This is a command-line tool that allows you to interact with Firebase from the terminal. @@ -127,3 +129,4 @@ Deploying an SSR Astro site to Firebase requires the [Blaze plan](https://fireba ``` + diff --git a/src/content/docs/en/guides/deploy/heroku.mdx b/src/content/docs/en/guides/deploy/heroku.mdx index 9dafb557013ef..1bc705d7cbcc9 100644 --- a/src/content/docs/en/guides/deploy/heroku.mdx +++ b/src/content/docs/en/guides/deploy/heroku.mdx @@ -4,6 +4,8 @@ description: How to deploy your Astro site to the web using Heroku. type: deploy i18nReady: true --- +import { Steps } from '@astrojs/starlight/components'; + [Heroku](https://www.heroku.com/) is a platform-as-a-service for building, running, and managing modern apps in the cloud. You can deploy an Astro site to Heroku using this guide. :::danger @@ -12,6 +14,7 @@ The following instructions use [the deprecated `heroku-static-buildpack`](https: ## How to deploy + 1. Install the [Heroku CLI](https://devcenter.heroku.com/articles/heroku-cli). 2. Create a Heroku account by [signing up](https://signup.heroku.com/). @@ -56,3 +59,4 @@ The following instructions use [the deprecated `heroku-static-buildpack`](https: # opens a browser to view the Dashboard version of Heroku CI $ heroku open ``` + diff --git a/src/content/docs/en/guides/deploy/kinsta.mdx b/src/content/docs/en/guides/deploy/kinsta.mdx index 4cef2f9b7de14..e2981777200f7 100644 --- a/src/content/docs/en/guides/deploy/kinsta.mdx +++ b/src/content/docs/en/guides/deploy/kinsta.mdx @@ -4,12 +4,14 @@ description: How to deploy your Astro site to the web on Kinsta Application Host type: deploy i18nReady: true --- +import { Steps } from '@astrojs/starlight/components'; You can use [Kinsta Application Hosting](https://kinsta.com/application-hosting/) to host an Astro site on their cloud hosting. ## Configuring your Astro project ### Static hosting + :::tip[Looking for an example?] Check out [the official Kinsta Application Hosting Starter project for Astro](https://github.com/kinsta/hello-world-astro)! ::: @@ -38,6 +40,7 @@ Here are the necessary lines in your `package.json` file: ``` ### SSR + :::tip[Looking for an example?] Check out [the official Kinsta Application Hosting Starter project for Astro SSR](https://github.com/kinsta/hello-world-astro-ssr)! ::: @@ -83,12 +86,21 @@ Here are the necessary lines in your `astro.config.mjs` file: ``` ## How to deploy + Once your project's GitHub repository is connected, you can trigger manual deploys to Kinsta Application Hosting in the **MyKinsta Admin Panel**. You can also set up automatic deployments in your admin panel. ### Configuring a new Kinsta application + + 1. Go to the [My Kinsta](https://my.kinsta.com/) admin panel. + 2. Go to the **Applications** tab. + 3. Connect your GitHub repository. + 4. Press the **Add service** > **Application** button. + 5. Follow the wizard steps. + 6. Your application is deployed. + diff --git a/src/content/docs/en/guides/deploy/microsoft-azure.mdx b/src/content/docs/en/guides/deploy/microsoft-azure.mdx index 167531c72aafe..545c39021cc24 100644 --- a/src/content/docs/en/guides/deploy/microsoft-azure.mdx +++ b/src/content/docs/en/guides/deploy/microsoft-azure.mdx @@ -4,12 +4,14 @@ description: How to deploy your Astro site to the web using Microsoft Azure. type: deploy i18nReady: true --- +import { Steps } from '@astrojs/starlight/components'; [Azure](https://azure.microsoft.com/) is a cloud platform from Microsoft. You can deploy your Astro site with Microsoft Azure’s [Static Web Apps](https://aka.ms/staticwebapps) service. This guide takes you through deploying your Astro site stored in GitHub using Visual Studio Code. Please see Microsoft guides for using an [Azure Pipelines Task](https://learn.microsoft.com/en-us/azure/devops/pipelines/tasks/reference/azure-static-web-app-v0?view=azure-pipelines) for other setups. ## Prerequisites + To follow this guide, you will need: - An Azure account and a subscription key. You can create a [free Azure account here](https://azure.microsoft.com/free). @@ -18,15 +20,18 @@ To follow this guide, you will need: ## How to deploy + 1. Open your project in VS Code. 2. Open the Static Web Apps extension, sign in to Azure, and click the **+** button to create a new Static Web App. You will be prompted to designate which subscription key to use. 3. Follow the wizard started by the extension to give your app a name, choose a framework preset, and designate the app root (usually `/`) and built file location (use `/dist`). Astro is not listed in the built-in templates in Azure so you will need to select `custom`. The wizard will run and will create a [GitHub Action](https://github.com/features/actions) in the `.github` folder of your repo. (This folder will be automatically created if it does not already exist.) + The GitHub Action will deploy your app (you can see its progress in your repo’s Actions tab on GitHub). When successfully completed, you can view your app at the address shown in the SWA Extension’s progress window by clicking the **Browse Website** button (this will appear after the GitHub Action has run). ## Known Issues + The GitHub action yaml that is created for you assumes the use of node 14. This means the Astro build fails. To resolve this update your projects package.json file with this snippet. ``` diff --git a/src/content/docs/en/guides/deploy/netlify.mdx b/src/content/docs/en/guides/deploy/netlify.mdx index 400b9b33e0c09..3dac68c1f60bc 100644 --- a/src/content/docs/en/guides/deploy/netlify.mdx +++ b/src/content/docs/en/guides/deploy/netlify.mdx @@ -4,7 +4,8 @@ description: How to deploy your Astro site to the web on Netlify. type: deploy i18nReady: true --- -import ReadMore from '~/components/ReadMore.astro' +import ReadMore from '~/components/ReadMore.astro'; +import { Steps } from '@astrojs/starlight/components'; [Netlify](https://netlify.com) offers hosting and serverless backend services for web applications and static websites. Any Astro site can be hosted on Netlify! @@ -30,13 +31,14 @@ npx astro add netlify If you prefer to install the adapter manually instead, complete the following two steps: + 1. Install [the `@astrojs/netlify` adapter](/en/guides/integrations-guide/netlify/) to your project’s dependencies using your preferred package manager. If you’re using npm or aren’t sure, run this in the terminal: ```bash npm install @astrojs/netlify ``` -1. Add two new lines to your `astro.config.mjs` project configuration file. +2. Add two new lines to your `astro.config.mjs` project configuration file. ```js title="astro.config.mjs" ins={2, 5-6} import { defineConfig } from 'astro/config'; @@ -62,6 +64,7 @@ If you prefer to install the adapter manually instead, complete the following tw }), }); ``` + ## How to deploy @@ -71,6 +74,7 @@ You can deploy to Netlify through the website UI or using Netlify’s CLI (comma If your project is stored in GitHub, GitLab, BitBucket, or Azure DevOps, you can use the Netlify website UI to deploy your Astro site. + 1. Click Add a new site in your [Netlify dashboard](https://app.netlify.com/) 2. Choose Import an existing project @@ -82,7 +86,8 @@ If your project is stored in GitHub, GitLab, BitBucket, or Azure DevOps, you can - **Build Command:** `astro build` or `npm run build` - **Publish directory:** `dist` - After deploying, you will be redirected to the site overview page. There, you can edit the details of your site. + After deploying, you will be redirected to the site overview page. There, you can edit the details of your site. + Any future changes to your source repository will trigger preview and production deploys based on your deployment configuration. @@ -100,12 +105,11 @@ To configure the default settings, create a `netlify.toml` file with the followi More info at [“Deploying an existing Astro Git repository”](https://www.netlify.com/blog/how-to-deploy-astro/#deploy-an-existing-git-repository-to-netlify) on Netlify’s blog - ### CLI Deployment You can also create a new site on Netlify and link up your Git repository by installing and using the [Netlify CLI](https://cli.netlify.com/). - + 1. Install Netlify's CLI globally ```bash @@ -113,7 +117,9 @@ You can also create a new site on Netlify and link up your Git repository by ins ``` 2. Run `netlify login` and follow the instructions to log in and authorize Netlify + 3. Run `netlify init` and follow the instructions + 4. Confirm your build command (`astro build`) The CLI will automatically detect the build settings (`astro build`) and deploy directory (`dist`), and will offer to automatically generate [a `netlify.toml` file](#netlifytoml-file) with those settings. @@ -121,6 +127,7 @@ You can also create a new site on Netlify and link up your Git repository by ins 5. Build and deploy by pushing to Git The CLI will add a deploy key to the repository, which means your site will be automatically rebuilt on Netlify every time you `git push`. + More details from Netlify on [Deploy an Astro site using the Netlify CLI](https://www.netlify.com/blog/how-to-deploy-astro/#link-your-astro-project-and-deploy-using-the-netlify-cli) diff --git a/src/content/docs/en/guides/deploy/render.mdx b/src/content/docs/en/guides/deploy/render.mdx index 08079057533a6..16ef9278afba1 100644 --- a/src/content/docs/en/guides/deploy/render.mdx +++ b/src/content/docs/en/guides/deploy/render.mdx @@ -4,16 +4,23 @@ description: How to deploy your Astro site to the web using Render. type: deploy i18nReady: true --- +import { Steps } from '@astrojs/starlight/components'; You can deploy your Astro project to [Render](https://render.com/), a service to build websites with free TLS certificates, a global CDN, DDoS protection, private networks, and auto deploys from Git. ## How to deploy + 1. Create a [render.com account](https://dashboard.render.com/) and sign in + 2. Click the **New +** button from your dashboard and select **Static Site** + 3. Connect your [GitHub](https://github.com/) or [GitLab](https://about.gitlab.com/) repository or alternatively enter the public URL of a public repository + 4. Give your website a name, select the branch and specify the build command and publish directory - **build command:** `npm run build` - **publish directory:** `dist` - **Environment variables (advanced)**: By default, Render uses Node.js 14.17.0, but Astro [requires a higher version](/en/install/auto/#prerequisites). Add an environment variable with a **Variable key** of `NODE_VERSION` and a **Value** of `18.14.1` or higher to tell Render to use a compatible Node.js version. Alternatively, add a [`.node-version`](https://render.com/docs/node-version) or [`.nvmrc`](https://render.com/docs/node-version) file to your project to specify a Node.js version. + 5. Click the **Create Static Site** button + diff --git a/src/content/docs/en/guides/deploy/space.mdx b/src/content/docs/en/guides/deploy/space.mdx index 91730663f2b3c..961283f469a84 100644 --- a/src/content/docs/en/guides/deploy/space.mdx +++ b/src/content/docs/en/guides/deploy/space.mdx @@ -5,7 +5,8 @@ type: deploy i18nReady: true --- import InstallGuideTabGroup from '~/components/TabGroup/InstallGuideTabGroup.astro'; -import PackageManagerTabs from '~/components/tabs/PackageManagerTabs.astro' +import PackageManagerTabs from '~/components/tabs/PackageManagerTabs.astro'; +import { Steps } from '@astrojs/starlight/components'; [Deta Space](https://deta.space/developers) is a personal computer that lives in the cloud — a ‘personal cloud’. You can build and run apps for yourself in your own "Space". You can publish the apps you've built, and they'll run for people all around the world. @@ -32,16 +33,19 @@ space new The Space CLI will try to auto-detect the configuration for your app. Accept the suggested configuration and then follow the instructions below, depending on the type of Astro app you want to deploy. ::: - ## Project Configuration ### Static site Make the following changes to the `Spacefile` file at the root of your project generated by the Space CLI. - + + 1. Change the engine to `static`. + 2. Add Astro's build command to the list of `commands`. -3. Serve the `dist` directory generated by Astro. + +3. Serve the `dist` directory generated by Astro. + ```yaml title="Spacefile" {6,8,9} # Spacefile Docs: https://deta.space/docs/en/build/reference/spacefile @@ -57,13 +61,17 @@ micros: ### Server-side rendered site - Make the following changes to the `Spacefile` file at the root of your project generated by the Space CLI: + 1. Configure the `nodejs16` engine. + 2. Add the `build` command. -3. Include the `dist` directory generated by Astro. + +3. Include the `dist` directory generated by Astro. + 4. Run the node command. + ```yaml title="Spacefile" {6,8,10,11} # Spacefile Docs: https://deta.space/docs/en/build/reference/spacefile diff --git a/src/content/docs/en/guides/deploy/sst.mdx b/src/content/docs/en/guides/deploy/sst.mdx index 38cdd59d9185b..f9e900866952b 100644 --- a/src/content/docs/en/guides/deploy/sst.mdx +++ b/src/content/docs/en/guides/deploy/sst.mdx @@ -4,6 +4,7 @@ description: How to deploy your Astro site to AWS with SST type: deploy i18nReady: true --- +import { Steps } from '@astrojs/starlight/components'; You can deploy an Astro site using [SST](https://sst.dev), an open-source framework for deploying fully serverless applications to AWS with SSG and SSR support. @@ -11,6 +12,7 @@ You can also use any additional SST constructs like Cron Jobs, Buckets, Queues, ## Quickstart + 1. Create an astro project. 2. Run `npx create-sst`. @@ -18,10 +20,12 @@ You can also use any additional SST constructs like Cron Jobs, Buckets, Queues, 3. It should detect that you are using Astro and ask you to confirm. 4. Once you're ready for deployment you can run `npx sst deploy --stage=production`. + You can also watch [a video walkthrough of this process](https://www.youtube.com/watch?v=AFP3ZHxO7Gg) that will guide you through the steps. ### SST constructs + To use any [additional SST constructs](https://docs.sst.dev/), add them to `sst.config.ts`. ```ts {2} {4} title="sst.config.ts" diff --git a/src/content/docs/en/guides/deploy/stormkit.mdx b/src/content/docs/en/guides/deploy/stormkit.mdx index a4bb8bed7ebbd..d73095b307fb0 100644 --- a/src/content/docs/en/guides/deploy/stormkit.mdx +++ b/src/content/docs/en/guides/deploy/stormkit.mdx @@ -4,13 +4,14 @@ description: Deploy your Astro site to Stormkit type: deploy i18nReady: true --- - import ReadMore from '~/components/ReadMore.astro'; +import { Steps } from '@astrojs/starlight/components'; You can deploy your Astro project to [Stormkit](https://stormkit.io/), a deployment platform for static websites, single-page applications (SPAs), and serverless functions. ## How to deploy + 1. [Log in to Stormkit](https://app.stormkit.io/auth). 2. Using the user interface, import your Astro project from one of the three supported Git providers (GitHub, GitLab, or Bitbucket). @@ -20,5 +21,6 @@ You can deploy your Astro project to [Stormkit](https://stormkit.io/), a deploym 4. Verify the build command in your [Stormkit configuration](https://stormkit.io/docs/deployments/configuration). By default, Stormkit CI will run `npm run build` but you can specify a custom build command on this page. 5. Click the "Deploy Now" button to deploy your site. + Read more in the [Stormkit Documentation](https://stormkit.io/docs). diff --git a/src/content/docs/en/guides/deploy/surge.mdx b/src/content/docs/en/guides/deploy/surge.mdx index d408322bee77e..de65961970e0f 100644 --- a/src/content/docs/en/guides/deploy/surge.mdx +++ b/src/content/docs/en/guides/deploy/surge.mdx @@ -4,11 +4,13 @@ description: How to deploy your Astro site to the web using surge.sh type: deploy i18nReady: true --- +import { Steps } from '@astrojs/starlight/components'; You can deploy your Astro project to [Surge](https://surge.sh/), a single-command web publishing platform designed for front-end developers. ## How to deploy + 1. Install [the Surge CLI](https://www.npmjs.com/package/surge) globally from the Terminal, if you haven't already. ```shell @@ -28,3 +30,4 @@ You can deploy your Astro project to [Surge](https://surge.sh/), a single-comman ``` You can use a [custom domain](http://surge.sh/help/adding-a-custom-domain) when deploying by running `surge dist yourdomain.com`. + diff --git a/src/content/docs/en/guides/deploy/vercel.mdx b/src/content/docs/en/guides/deploy/vercel.mdx index 98b9ed8d8fde2..9bc3f82b38b6a 100644 --- a/src/content/docs/en/guides/deploy/vercel.mdx +++ b/src/content/docs/en/guides/deploy/vercel.mdx @@ -4,7 +4,8 @@ description: How to deploy your Astro site to the web on Vercel. type: deploy i18nReady: true --- -import ReadMore from '~/components/ReadMore.astro' +import ReadMore from '~/components/ReadMore.astro'; +import { Steps } from '@astrojs/starlight/components'; You can use [Vercel](http://vercel.com/) to deploy an Astro site to their global edge network with zero configuration. @@ -30,6 +31,7 @@ npx astro add vercel If you prefer to install the adapter manually instead, complete the following two steps: + 1. Install [the `@astrojs/vercel` adapter](/en/guides/integrations-guide/vercel/) to your project’s dependencies using your preferred package manager. If you’re using npm or aren’t sure, run this in the terminal: ```bash @@ -47,6 +49,7 @@ If you prefer to install the adapter manually instead, complete the following tw adapter: vercel(), }); ``` + ## How to deploy @@ -54,18 +57,23 @@ You can deploy to Vercel through the website UI or using Vercel’s CLI (command ### Website UI Deployment + 1. Push your code to your online Git repository (GitHub, GitLab, BitBucket). + 2. [Import your project](https://vercel.com/new) into Vercel. + 3. Vercel will automatically detect Astro and configure the right settings. + 4. Your application is deployed! (e.g. [astro.vercel.app](https://astro.vercel.app/)) + After your project has been imported and deployed, all subsequent pushes to branches will generate [Preview Deployments](https://vercel.com/docs/concepts/deployments/preview-deployments), and all changes made to the Production Branch (commonly “main”) will result in a [Production Deployment](https://vercel.com/docs/concepts/deployments/environments#production). Learn more about Vercel’s [Git Integration](https://vercel.com/docs/concepts/git). - ### CLI Deployment + 1. Install the [Vercel CLI](https://vercel.com/cli) and run `vercel` to deploy. ```bash @@ -74,9 +82,11 @@ After your project has been imported and deployed, all subsequent pushes to bran ``` 2. Vercel will automatically detect Astro and configure the right settings. + 3. When asked `Want to override the settings? [y/N]`, choose `N`. -4. Your application is deployed! (e.g. [astro.vercel.app](https://astro.vercel.app/)) +4. Your application is deployed! (e.g. [astro.vercel.app](https://astro.vercel.app/)) + ### Project config with vercel.json diff --git a/src/content/docs/en/guides/deploy/zeabur.mdx b/src/content/docs/en/guides/deploy/zeabur.mdx index 264818eae93c2..7df923509a8c9 100644 --- a/src/content/docs/en/guides/deploy/zeabur.mdx +++ b/src/content/docs/en/guides/deploy/zeabur.mdx @@ -4,6 +4,8 @@ description: How to deploy your Astro site to the web on Zeabur. type: deploy i18nReady: true --- +import { Steps } from '@astrojs/starlight/components'; + [Zeabur](https://zeabur.com) offers hosting for full-stack web applications. Astro sites can be hosted as both SSR or static output. This guide includes instructions for deploying to Zeabur through the website UI. @@ -18,6 +20,7 @@ Astro outputs a static site by default. There is no need for any extra configura To enable SSR in your Astro project and deploy on Zeabur: + 1. Install [the `@zeabur/astro-adapter` adapter](https://www.npmjs.com/package/@zeabur/astro-adapter) to your project’s dependencies using your preferred package manager. If you’re using npm or aren’t sure, run this in the terminal: ```bash @@ -35,12 +38,13 @@ To enable SSR in your Astro project and deploy on Zeabur: adapter: zeabur(), }); ``` - + ## How to deploy You can deploy your Astro site to Zeabur if the project is stored in GitHub. + 1. Click Create new project in the [Zeabur dashboard](https://dash.zeabur.com). 2. Configure GitHub installation and import the repository. @@ -48,6 +52,7 @@ You can deploy your Astro site to Zeabur if the project is stored in GitHub. 3. Zeabur will automatically detect that your project is an Astro project and will build it using the `astro build` command. 4. Once the build is complete, you can bind a domain to your site and visit it. + After your project has been imported and deployed, all subsequent pushes to branches will generate new builds. diff --git a/src/content/docs/en/guides/ecommerce.mdx b/src/content/docs/en/guides/ecommerce.mdx index a0a2de20195a6..a43b0e8351488 100644 --- a/src/content/docs/en/guides/ecommerce.mdx +++ b/src/content/docs/en/guides/ecommerce.mdx @@ -3,8 +3,9 @@ title: E-commerce description: An introduction to adding e-commerce options to your Astro site i18nReady: true --- -import PackageManagerTabs from '~/components/tabs/PackageManagerTabs.astro' -import ReadMore from '~/components/ReadMore.astro' +import PackageManagerTabs from '~/components/tabs/PackageManagerTabs.astro'; +import { Steps } from '@astrojs/starlight/components'; +import ReadMore from '~/components/ReadMore.astro'; With Astro, you can build several e-commerce options, from checkout links to hosted payment pages to building an entire storefront using a payment service API. @@ -22,11 +23,13 @@ The basic [Lemon.js JavaScript library](https://docs.lemonsqueezy.com/help/lemon The following is an example of adding a Lemon Squeezy "Buy now" element to an Astro page. Clicking this link will open a checkout and allow the visitor to complete a single purchase. + 1. Add the following ` ``` + 2. Create an anchor tag on the page linking to your product URL. Include the class `lemonsqueezy-button` to open a checkout overlay when clicked. ```html title="src/pages/my-product-page.astro" @@ -34,6 +37,7 @@ The following is an example of adding a Lemon Squeezy "Buy now" element to an As Buy Now ``` + #### Lemon.js @@ -53,6 +57,7 @@ The following is an example of adding a Paddle "Buy Now" element to an Astro pag After your default payment link domain (your own website) is approved by Paddle, you can turn any element on your page into a trigger for a checkout overlay using HTML data attributes. + 1. Add the following two ` ``` + 2. Turn any element on your page into a Paddle Checkout button by adding the `paddle_button` class: ```html title="src/pages/my-product-page.astro" Buy Now ``` + 3. Add a `data-items` attribute to specify your product's Paddle `priceId` and `quantity`. You can also optionally pass additional [supported HTML data attributes](https://developer.paddle.com/paddlejs/html-data-attributes) to prefill data, handle checkout success, or style your button and checkout overlay: ```html title="src/pages/my-product-page.astro" @@ -88,6 +95,7 @@ After your default payment link domain (your own website) is approved by Paddle, Buy now ``` + #### Paddle.js @@ -116,6 +124,7 @@ The following is an example of configuring a Snipcart checkout and adding button For complete instructions, including setting up your Snipcart store, please see [the Snipcart installation documentation](https://docs.snipcart.com/v3/setup/installation). + 1. Add the script [as shown in the Snipcart installation instructions](https://docs.snipcart.com/v3/setup/installation) on your page after the `` element. ```html title="src/pages/my-product-page.astro" @@ -169,6 +178,7 @@ The following is an example of configuring a Snipcart checkout and adding button ```html title="src/pages/my-product-page.astro" ``` + #### Snipcart JavaScript SDK diff --git a/src/content/docs/en/guides/integrations-guide/markdoc.mdx b/src/content/docs/en/guides/integrations-guide/markdoc.mdx index f2eb87a976cdc..cf7e74f8de3d7 100644 --- a/src/content/docs/en/guides/integrations-guide/markdoc.mdx +++ b/src/content/docs/en/guides/integrations-guide/markdoc.mdx @@ -8,6 +8,7 @@ i18nReady: true --- import { FileTree } from '@astrojs/starlight/components'; import PackageManagerTabs from '~/components/tabs/PackageManagerTabs.astro'; +import { Steps } from '@astrojs/starlight/components'; import ReadMore from '~/components/ReadMore.astro'; This **[Astro integration][astro-integration]** enables the usage of [Markdoc](https://markdoc.dev/) to create components, pages, and content collection entries. @@ -411,6 +412,7 @@ Astro's `` component cannot be used directly in Markdoc. However, you c To override the default image node, you can configure an `.astro` component to be rendered in place of a standard ``. + 1. Build a custom `MarkdocImage.astro` component to pass the required `src` and `alt` properties from your image to the `` component: ```astro title="src/components/MarkdocImage.astro" @@ -467,6 +469,7 @@ To override the default image node, you can configure an `.astro` component to b ![A picture of a dog](https://example.com/dog.jpg) ``` + #### Create a custom Markdoc image tag @@ -474,6 +477,7 @@ A Markdoc `image` tag allows you to set additional attributes on your image that The following steps will create a custom Markdoc image tag to display a `
` element with a caption, using the Astro `` component to optimize the image. + 1. Create a `MarkdocFigure.astro` component to receive the necessary props and render an image with a caption: ```astro title="src/components/MarkdocFigure.astro" @@ -517,7 +521,7 @@ The following steps will create a custom Markdoc image tag to display a `
## Advanced Markdoc configuration diff --git a/src/content/docs/en/guides/markdown-content.mdx b/src/content/docs/en/guides/markdown-content.mdx index 794baa1e9da13..051adc85e8bc8 100644 --- a/src/content/docs/en/guides/markdown-content.mdx +++ b/src/content/docs/en/guides/markdown-content.mdx @@ -3,11 +3,11 @@ title: Markdown & MDX description: Learn how to create content using Markdown or MDX with Astro i18nReady: true --- - -import Since from '~/components/Since.astro' +import Since from '~/components/Since.astro'; import { FileTree } from '@astrojs/starlight/components'; -import RecipeLinks from "~/components/RecipeLinks.astro" -import ReadMore from '~/components/ReadMore.astro' +import RecipeLinks from "~/components/RecipeLinks.astro"; +import ReadMore from '~/components/ReadMore.astro'; +import { Steps } from '@astrojs/starlight/components'; [Markdown](https://daringfireball.net/projects/markdown/) is commonly used to author text-heavy content like blog posts and documentation. Astro includes built-in support for standard Markdown files that can also include [frontmatter YAML](https://dev.to/paulasantamaria/introduction-to-yaml-125f) to define custom metadata such as a title, description, and tags. @@ -473,6 +473,7 @@ If you are using [content collections](/en/guides/content-collections/), please You can add frontmatter properties to all of your Markdown and MDX files by using a [remark or rehype plugin](#markdown-plugins). + 1. Append a `customProperty` to the `data.astro.frontmatter` property from your plugin's `file` argument: ```js title="example-remark-plugin.mjs" @@ -517,6 +518,7 @@ You can add frontmatter properties to all of your Markdown and MDX files by usin ], }); ``` + Now, every Markdown or MDX file will have `customProperty` in its frontmatter, making it available when [importing your markdown](#importing-markdown) and from [the `Astro.props.frontmatter` property in your layouts](#frontmatter-layout). @@ -651,9 +653,13 @@ export default defineConfig({ If you opt to use Prism, Astro will apply Prism's CSS classes instead. Note that **you need to bring your own CSS stylesheet** for syntax highlighting to appear! + 1. Choose a premade stylesheet from the available [Prism Themes](https://github.com/PrismJS/prism-themes). + 2. Add this stylesheet to [your project's `public/` directory](/en/basics/project-structure/#public). + 3. Load this into your page's `` in a [layout component](/en/basics/layouts/) via a `` tag. (See [Prism basic usage](https://prismjs.com/#basic-usage).) + You can also visit the [list of languages supported by Prism](https://prismjs.com/#supported-languages) for options and usage. diff --git a/src/content/docs/en/guides/middleware.mdx b/src/content/docs/en/guides/middleware.mdx index dbee71d647f1b..39900199e662f 100644 --- a/src/content/docs/en/guides/middleware.mdx +++ b/src/content/docs/en/guides/middleware.mdx @@ -4,6 +4,7 @@ description: Learn how to use middleware in Astro. i18nReady: true --- import PackageManagerTabs from '~/components/tabs/PackageManagerTabs.astro'; +import { Steps } from '@astrojs/starlight/components'; **Middleware** allows you to intercept requests and responses and inject behaviors dynamically every time a page or endpoint is about to be rendered. This rendering occurs at build time for all prerendered pages, but occurs when the route is requested for pages rendered on demand. @@ -11,6 +12,7 @@ Middleware also allows you to set and share request-specific information across ## Basic Usage + 1. Create `src/middleware.js|ts` (Alternatively, you can create `src/middleware/index.js|ts`.) 2. Inside this file, export an [`onRequest()`](/en/reference/api-reference/#onrequest) function that can be passed a [`context` object](#the-context-object) and `next()` function. This must not be a default export. @@ -35,6 +37,7 @@ Middleware also allows you to set and share request-specific information across

{data.title}

This {data.property} is from middleware.

``` + ### The `context` object diff --git a/src/content/docs/en/guides/migrate-to-astro/from-gatsby.mdx b/src/content/docs/en/guides/migrate-to-astro/from-gatsby.mdx index b2f609e013d61..29f15c2552da6 100644 --- a/src/content/docs/en/guides/migrate-to-astro/from-gatsby.mdx +++ b/src/content/docs/en/guides/migrate-to-astro/from-gatsby.mdx @@ -6,8 +6,9 @@ stub: false framework: Gatsby i18nReady: true --- -import AstroJSXTabs from '~/components/tabs/AstroJSXTabs.astro' -import PackageManagerTabs from '~/components/tabs/PackageManagerTabs.astro' +import { Steps } from '@astrojs/starlight/components'; +import AstroJSXTabs from '~/components/tabs/AstroJSXTabs.astro'; +import PackageManagerTabs from '~/components/tabs/PackageManagerTabs.astro'; Here are some key concepts and migration strategies to help you get started. Use the rest of our docs and our [Discord community](https://astro.build/chat) to keep going! @@ -35,7 +36,6 @@ When you rebuild your Gatsby site in Astro, you will notice some important diffe - [Local file data](/en/guides/imports/): Gatsby uses GraphQL to retrieve data from your project files. Astro uses ESM imports and top-level await functions (e.g. [`Astro.glob()`](/en/guides/imports/#astroglob), [`getCollection()`](/en/guides/content-collections/#querying-collections)) to import data from your project files. You can manually add GraphQL to your Astro project but it is not included by default. - ## Convert your Gatsby Project Each project migration will look different, but there are some common actions you will perform when converting from Gatsby to Astro. @@ -89,11 +89,11 @@ You may find it useful to install some of [Astro's optional integrations](/en/gu - **@astrojs/mdx**: to bring existing MDX files from your Gatsby project, or to use MDX in your new Astro site. - ### Put your code in `src` Following [Astro's project structure](/en/basics/project-structure/): + 1. **Delete** Gatsby's `public/` folder. Gatsby uses the `public/` directory for its build output, so you can safely discard this folder. You will no longer need a built version of your Gatsby site. (Astro uses `dist/` by default for the build output.) @@ -104,9 +104,10 @@ Following [Astro's project structure](/en/basics/project-structure/): 3. **Copy or Move** Gatsby's other files and folders (e.g. `components`, `pages`, etc.) as needed into your Astro `src/` folder as you rebuild your site, following [Astro's project structure](/en/basics/project-structure/). - Astro's `src/pages/` folder is a special folder used for file-based routing to create your site's pages and posts from `.astro`, `.md` and `.mdx` files. You will not have to configure any routing behavior for your Astro, Markdown, and MDX files. + Astro's `src/pages/` folder is a special folder used for file-based routing to create your site's pages and posts from `.astro`, `.md` and `.mdx` files. You will not have to configure any routing behavior for your Astro, Markdown, and MDX files. - All other folders are optional, and you can organize the contents of your `src/` folder any way you like. Other common folders in Astro projects include `src/layouts/`, `src/components`, `src/styles`, and `src/scripts`. + All other folders are optional, and you can organize the contents of your `src/` folder any way you like. Other common folders in Astro projects include `src/layouts/`, `src/components`, `src/styles`, and `src/scripts`. + ### Tips: Convert JSX files to `.astro` files @@ -114,15 +115,15 @@ Here are some tips for converting a Gatsby `.js` component into a `.astro` compo 1. Use only the `return()` of the existing Gatsby component function as your HTML template. -1. Change any [Gatsby or JSX syntax to Astro syntax](#reference-convert-to-astro-syntax) or to HTML web standards. This includes ``, `{children}`, and `className`, for example. +2. Change any [Gatsby or JSX syntax to Astro syntax](#reference-convert-to-astro-syntax) or to HTML web standards. This includes ``, `{children}`, and `className`, for example. -1. Move any necessary JavaScript, including import statements, into a ["code fence" (`---`)](/en/basics/astro-components/#the-component-script). Note: JavaScript to [conditionally render content](/en/basics/astro-syntax/#dynamic-html) is often written inside the HTML template directly in Astro. +3. Move any necessary JavaScript, including import statements, into a ["code fence" (`---`)](/en/basics/astro-components/#the-component-script). Note: JavaScript to [conditionally render content](/en/basics/astro-syntax/#dynamic-html) is often written inside the HTML template directly in Astro. 4. Use [`Astro.props`](/en/reference/api-reference/#astroprops) to access any additional props that were previously passed to your Gatsby function. -4. Decide whether any imported components also need to be converted to Astro. With the official React integration installed, you can [use existing React components in your Astro files](/en/guides/framework-components/). But, you may want to convert them to `.astro` components, especially if they do not need to be interactive! +5. Decide whether any imported components also need to be converted to Astro. With the official React integration installed, you can [use existing React components in your Astro files](/en/guides/framework-components/). But, you may want to convert them to `.astro` components, especially if they do not need to be interactive! -4. Remove any GraphQL queries. Instead, use import and [`Astro.glob()`](/en/reference/api-reference/#astroglob) statements to query your local files. +6. Remove any GraphQL queries. Instead, use import and [`Astro.glob()`](/en/reference/api-reference/#astroglob) statements to query your local files. See [an example from Gatsby's Blog starter template converted step-by-step](#guided-example-gatsby-layout-to-astro) @@ -393,7 +394,8 @@ This example converts the main project layout (`layout.js`) from Gatsby's blog s This page layout shows one header when visiting the home page, and a different header with a link back to Home for all other pages. -1. Identify the return() JSX. + +1. Identify the `return()` JSX. ```jsx {21-29} title="layout.js" import * as React from "react" @@ -559,6 +561,7 @@ This page layout shows one header when visiting the home page, and a different h ``` You should see a link to "Home" only when visiting the About page. + ## Community Resources diff --git a/src/content/docs/en/guides/migrate-to-astro/from-nextjs.mdx b/src/content/docs/en/guides/migrate-to-astro/from-nextjs.mdx index 82632aa88d9aa..86d3612704ad1 100644 --- a/src/content/docs/en/guides/migrate-to-astro/from-nextjs.mdx +++ b/src/content/docs/en/guides/migrate-to-astro/from-nextjs.mdx @@ -6,8 +6,9 @@ stub: false framework: Next.js i18nReady: true --- -import AstroJSXTabs from '~/components/tabs/AstroJSXTabs.astro' -import PackageManagerTabs from '~/components/tabs/PackageManagerTabs.astro' +import { Steps } from '@astrojs/starlight/components'; +import AstroJSXTabs from '~/components/tabs/AstroJSXTabs.astro'; +import PackageManagerTabs from '~/components/tabs/PackageManagerTabs.astro'; Here are some key concepts and migration strategies to help you get started. Use the rest of our docs and our [Discord community](https://astro.build/chat) to keep going! @@ -37,6 +38,7 @@ When you rebuild your Next.js site in Astro, you will notice some important diff Each project migration will look different, but there are some common actions you will perform when converting from Next.js to Astro. ### Create a new Astro project + Use the `create astro` command for your package manager to launch Astro's CLI wizard or choose a community theme from the [Astro Theme Showcase](https://astro.build/themes). You can pass a `--template` argument to the `create astro` command to start a new Astro project with one of our official starters (e.g. `docs`, `blog`, `portfolio`). Or, you can [start a new project from any existing Astro repository on GitHub](/en/install/auto/#starter-templates). @@ -89,6 +91,7 @@ You may find it useful to install some of [Astro's optional integrations](/en/gu Following [Astro's project structure](/en/basics/project-structure/): + 1. **Keep** Next's `public/` folder untouched. Astro uses the `public/` directory for static assets, just like Next. There is no change needed to this folder, nor its contents. @@ -96,7 +99,7 @@ Following [Astro's project structure](/en/basics/project-structure/): 2. **Copy or Move** Next's other files and folders (e.g. `pages`, `styles` etc.) into Astro's `src/` folder as you rebuild your site, following [Astro's project structure](/en/basics/project-structure/). Like Next, Astro's `src/pages/` folder is a special folder used for file-based routing. All other folders are optional, and you can organize the contents of your `src/` folder any way you like. Other common folders in Astro projects include `src/layouts/`, `src/components`, `src/styles`, `src/scripts`. - + ### The Astro config file @@ -110,13 +113,13 @@ Here are some tips for converting a Next `.js` component into a `.astro` compone 2. Change any [Next or JSX syntax to Astro](#reference-convert-nextjs-syntax-to-astro) or to HTML web standards. This includes ``, ` ``` - ## Migrate to v0.23 ### Missing Sass Error @@ -584,7 +577,6 @@ To learn more about Vite plugins, please visit their [plugin guide](https://vite In prior releases, these were configured with `snowpackPlugin` or `snowpackPluginOptions`. ::: - ### Aliasing In Astro v0.21+, import aliases can be added from `tsconfig.json` or `jsconfig.json`. @@ -624,14 +616,15 @@ Previously, you could create mini Astro Components inside of the Astro Frontmatt To migrate to v0.21+, please convert all JSX Astro components (that is, any Astro components created inside of another component’s frontmatter) to standalone components. - ### Styling Changes #### Autoprefixer Autoprefixer is no longer run by default. To enable: + 1. Install the latest version (`npm install autoprefixer`) + 2. Create a `postcss.config.cjs` file at the root of your project with: ```js module.exports = { @@ -640,12 +633,15 @@ Autoprefixer is no longer run by default. To enable: }, }; ``` + #### Tailwind CSS Ensure you have PostCSS installed. This was optional in previous releases, but is required now: + 1. Install the latest version of postcss (`npm install -D postcss`) + 2. Create a `postcss.config.cjs` file at the root of your project with: ```js module.exports = { @@ -655,7 +651,7 @@ Ensure you have PostCSS installed. This was optional in previous releases, but i }; ``` For more information, read the [Tailwind CSS documentation](https://tailwindcss.com/docs/installation#add-tailwind-as-a-post-css-plugin) - + ### Known Issues @@ -670,5 +666,4 @@ const whereShouldIPutMyImports = "on top!" --- ``` - [vite]: https://vitejs.dev diff --git a/src/content/docs/en/guides/upgrade-to/v2.mdx b/src/content/docs/en/guides/upgrade-to/v2.mdx index b5e6fc9daf5fb..d009b82f21ad2 100644 --- a/src/content/docs/en/guides/upgrade-to/v2.mdx +++ b/src/content/docs/en/guides/upgrade-to/v2.mdx @@ -3,9 +3,9 @@ title: Upgrade to Astro v2 description: How to upgrade your project to the latest version of Astro. i18nReady: true --- -import PackageManagerTabs from '~/components/tabs/PackageManagerTabs.astro' +import PackageManagerTabs from '~/components/tabs/PackageManagerTabs.astro'; import { FileTree } from '@astrojs/starlight/components'; - +import { Steps } from '@astrojs/starlight/components'; This guide will help you migrate from Astro v1 to Astro v2. @@ -61,6 +61,7 @@ Astro v2.0 drops Node 14 support entirely, so that all Astro users can take adva Check that both your development environment and your deployment environment are using **Node `16.12.0` or later**. + 1. Check your local version of Node using: ```sh @@ -69,11 +70,10 @@ Astro v2.0 drops Node 14 support entirely, so that all Astro users can take adva ``` If your local development environment needs upgrading, [install Node](https://nodejs.org/en/download/). - 2. Check your [deployment environment's](/en/guides/deploy/) own documentation to verify that they support Node 16. You can specify Node `16.12.0` for your Astro project either in a dashboard configuration setting, or a `.nvmrc` file. - + ### Reserved: `src/content/` @@ -132,7 +132,6 @@ Astro v2.0 removes this configuration option entirely because its behavior is no Applying remark and rehype plugins in your Markdown configuration **no longer disables Astro's default plugins**. GitHub-Flavored Markdown and Smartypants are now applied whether or not custom `remarkPlugins` or `rehypePlugins` are configured. - ##### What should I do? Remove `extendDefaultPlugins` in your configuration. This is now Astro's default behavior in v2.0, and you can delete this line without any replacement. @@ -250,14 +249,12 @@ export default defineConfig({ Revisit your Markdown and MDX configuration and compare your existing config with the new options available. - ### Changed: Plugin access to frontmatter In v1.x, remark and rehype plugins did not have access to user frontmatter. Astro merged plugin frontmatter with your file's frontmatter, without passing the file frontmatter to your plugins. Astro v2.0 gives remark and rehype plugins access to user frontmatter via frontmatter injection. This allows plugin authors to modify a user's existing frontmatter, or compute new properties based on other properties. - #### What should I do? Check any remark and rehype plugins you have written to see whether their behavior has changed. Note that `data.astro.frontmatter` is now the _complete_ Markdown or MDX document's frontmatter, rather than an empty object. @@ -268,7 +265,6 @@ In v1.x, Astro's RSS package allowed you to use `items: import.meta.glob(...)` t Astro v2.0 introduces a `pagesGlobToRssItems()` wrapper to the `items` property. - #### What should I do? Import, then wrap your existing function containing `import.meta.glob()` with the `pagesGlobToRssItems()` helper. @@ -370,7 +366,6 @@ const allPosts = await Astro.glob('./posts/*.md'); In v1.0, Astro deprecated `Astro.canonicalURL` for constructing a canonical URL. - Astro v2.0 removes this option entirely. `Astro.canonicalURL` in your code will cause an error. #### What should I do? diff --git a/src/content/docs/en/guides/upgrade-to/v3.mdx b/src/content/docs/en/guides/upgrade-to/v3.mdx index 4965a22ba9de1..7530a226483ff 100644 --- a/src/content/docs/en/guides/upgrade-to/v3.mdx +++ b/src/content/docs/en/guides/upgrade-to/v3.mdx @@ -3,7 +3,8 @@ title: Upgrade to Astro v3 description: How to upgrade your project to the latest version of Astro (v3.0). i18nReady: true --- -import PackageManagerTabs from '~/components/tabs/PackageManagerTabs.astro' +import { Steps } from '@astrojs/starlight/components'; +import PackageManagerTabs from '~/components/tabs/PackageManagerTabs.astro'; This guide will help you migrate from Astro v2 to Astro v3. @@ -72,8 +73,6 @@ These features are now available by default: Read more about these two exciting features and more in [the 3.0 Blog post](https://astro.build/blog/astro-3/)! - - ## Astro v3.0 Breaking Changes Astro v3.0 includes some breaking changes, as well as the removal of some previously deprecated features. If your project doesn't work as expected after upgrading to v3.0, check this guide for an overview of all breaking changes and instructions on how to update your codebase. @@ -90,14 +89,13 @@ Astro v3.0 drops Node 16 support entirely so that all Astro users can take advan Check that both your development environment and your deployment environment are using **Node `18.14.1` or higher**. + 1. Check your local version of Node using: ```sh node -v ``` - - 2. Check your [deployment environment's](/en/guides/deploy/) own documentation to verify that they support Node 18. You can specify Node `18.14.1` for your Astro project either in a dashboard configuration setting or a `.nvmrc` file. @@ -105,6 +103,7 @@ Astro v3.0 drops Node 16 support entirely so that all Astro users can take advan ```bash title=".nvmrc" 18.14.1 ``` + ### Removed: Support for TypeScript 4 @@ -317,7 +316,6 @@ An [error message indicating that `getStaticPath()`'s return value must be an ar In Astro v2.x, [`astro check`](/en/reference/cli-reference/#astro-check) was included in Astro by default, and its dependencies were bundled in Astro. This meant a larger package whether or not you ever used `astro check`. This also prevented you from having control over the version of TypeScript and the Astro Language Server to use. - Astro v3.0 moves the `astro check` command out of Astro core and now requires an external package `@astrojs/check`. Additionally, you must install `typescript` in your project to use the `astro check` command. #### What should I do? @@ -434,7 +432,6 @@ Astro v3.0 changes the [default port](/en/reference/cli-reference/#--port-number Update any existing references to `localhost:3000`, for example in tests or in your `README`, to reflect the new port `localhost:4321`. - ### Changed default: import.meta.env.BASE_URL `trailingSlash` In Astro v2.x, `import.meta.env.BASE_URL` appended your [`base`](/en/reference/configuration-reference/#base) setting with a [trailingSlash](/en/reference/configuration-reference/#trailingslash) by default. `trailingSlash: "ignore"` also appended a trailing slash. @@ -486,7 +483,6 @@ Astro v3.0 introduces a new, default value: `"attribute"`. By default, styles ar To retain your project's current [style scoping](/en/guides/styling/#scoped-styles), update the configuration file to the previous default value: - ```js title="astro.config.mjs" ins={4} import { defineConfig } from "astro/config"; @@ -504,7 +500,6 @@ Astro v3.0 changes the default value of `inlineStylesheets` to `"auto"`. Stylesh #### What should I do? If you want to keep your project's current behavior, set `build.inlineStylesheets` to the previous default, `"never"`: - ```js title="astro.config.mjs" ins={4-6} import { defineConfig } from "astro/config"; @@ -646,7 +641,6 @@ await devServer.stop(); await build(); ``` - ### Changed: internal Astro API entry point export paths In Astro v2.x, you could import internal Astro APIs from `astro/internal/*` and `astro/runtime/server/*`. diff --git a/src/content/docs/en/recipes/add-yaml-support.mdx b/src/content/docs/en/recipes/add-yaml-support.mdx index d18ea5fae1534..14be1864bf2c0 100644 --- a/src/content/docs/en/recipes/add-yaml-support.mdx +++ b/src/content/docs/en/recipes/add-yaml-support.mdx @@ -4,13 +4,14 @@ description: Learn how you can import YAML data by adding a Rollup plugin to you i18nReady: true type: recipe --- - -import PackageManagerTabs from '~/components/tabs/PackageManagerTabs.astro' +import { Steps } from '@astrojs/starlight/components'; +import PackageManagerTabs from '~/components/tabs/PackageManagerTabs.astro'; Astro builds on top of Vite, and supports both Vite and Rollup plugins. This recipe uses a Rollup plugin to add the ability to import a YAML (`.yml`) file in Astro. ## Recipe + 1. Install `@rollup/plugin-yaml`: @@ -44,7 +45,6 @@ Astro builds on top of Vite, and supports both Vite and Rollup plugins. This rec }); ``` - 3. Finally, you can import YAML data using an `import` statement: ```js @@ -62,3 +62,4 @@ Astro builds on top of Vite, and supports both Vite and Rollup plugins. This rec ``` This will allow your editor to provide type hints for your YAML data. ::: + diff --git a/src/content/docs/en/recipes/build-custom-img-component.mdx b/src/content/docs/en/recipes/build-custom-img-component.mdx index 21dd28e8bc32c..8f7a01e317c17 100644 --- a/src/content/docs/en/recipes/build-custom-img-component.mdx +++ b/src/content/docs/en/recipes/build-custom-img-component.mdx @@ -4,6 +4,7 @@ description: Learn how to build a custom image component that supports media que i18nReady: true type: recipe --- +import { Steps } from '@astrojs/starlight/components'; Astro provides two built-in components that you can use to display and optimize your images. The `` component allows you to display responsive images and work with different formats and sizes. The `` component will optimize your images and allow you to pass in different formats and quality properties. @@ -13,6 +14,7 @@ In this recipe, you will use the [`getImage()` function](/en/guides/images/#gene ## Recipe + 1. Create a new Astro component and import the `getImage()` function ```astro title="src/components/MyCustomImageComponent.astro" @@ -126,3 +128,4 @@ In this recipe, you will use the [`getImage()` function](/en/guides/images/#gene /> ``` + diff --git a/src/content/docs/en/recipes/build-forms-api.mdx b/src/content/docs/en/recipes/build-forms-api.mdx index 6e798ce02d6fa..a788f425942ae 100644 --- a/src/content/docs/en/recipes/build-forms-api.mdx +++ b/src/content/docs/en/recipes/build-forms-api.mdx @@ -4,8 +4,9 @@ description: Learn how to use JavaScript to send form submissions to an API Rout i18nReady: true type: recipe --- +import { Steps } from '@astrojs/starlight/components'; import UIFrameworkTabs from "~/components/tabs/UIFrameworkTabs.astro"; -import PackageManagerTabs from "~/components/tabs/PackageManagerTabs.astro" +import PackageManagerTabs from "~/components/tabs/PackageManagerTabs.astro"; An HTML form causes the browser to refresh the page or navigate to a new one. To send form data to an API endpoint instead, you must intercept the form submission using JavaScript. @@ -17,6 +18,7 @@ This recipe shows you how to send form data to an API endpoint and handle that d ## Recipe + 1. Create a `POST` API endpoint at `/api/feedback` that will receive the form data. Use `request.formData()` to process it. Be sure to validate the form values before you use them. This example sends a JSON object with a message back to the client. @@ -165,7 +167,6 @@ This recipe shows you how to send form data to an API endpoint and handle that d - 3. Create a function that accepts a submit event, then pass it as a `submit` handler to your form. In the function: @@ -424,6 +425,7 @@ This recipe shows you how to send form data to an API endpoint and handle that d ``` + {/* ## Extension: Use Zod to validate your form diff --git a/src/content/docs/en/recipes/build-forms.mdx b/src/content/docs/en/recipes/build-forms.mdx index 408df1244bf39..e5f58523bc1c6 100644 --- a/src/content/docs/en/recipes/build-forms.mdx +++ b/src/content/docs/en/recipes/build-forms.mdx @@ -4,15 +4,16 @@ description: Learn how to build HTML forms and handle submissions in your frontm i18nReady: true type: recipe --- +import { Steps } from '@astrojs/starlight/components'; In SSR mode, Astro pages can both display and handle forms. In this recipe, you'll use a standard HTML form to submit data to the server. Your frontmatter script will handle the data on the server, sending no JavaScript to the client. - ## Prerequisites - A project with [SSR](/en/guides/server-side-rendering/) (`output: 'server'`) enabled ## Recipe + 1. Create or identify a `.astro` page which will contain your form and your handling code. For example, you could add a registration page: ```astro title="src/pages/register.astro" @@ -139,7 +140,7 @@ In SSR mode, Astro pages can both display and handle forms. In this recipe, you' ``` -5. Validate the form data on the server. This should include the same validation done on the client to prevent malicious submissions to your endpoint and to support the rare legacy browser that doesn't have form validation. +6. Validate the form data on the server. This should include the same validation done on the client to prevent malicious submissions to your endpoint and to support the rare legacy browser that doesn't have form validation. It can also include validation that can't be done on the client. For example, this example checks if the email is already in the database. @@ -201,5 +202,4 @@ In SSR mode, Astro pages can both display and handle forms. In this recipe, you' ``` - - + diff --git a/src/content/docs/en/recipes/call-endpoints.mdx b/src/content/docs/en/recipes/call-endpoints.mdx index cbd498869139a..d7d689b04cc96 100644 --- a/src/content/docs/en/recipes/call-endpoints.mdx +++ b/src/content/docs/en/recipes/call-endpoints.mdx @@ -4,6 +4,7 @@ description: Learn how to call endpoints from the server in Astro. i18nReady: true type: recipe --- +import { Steps } from '@astrojs/starlight/components'; Endpoints can be used to serve many kinds of data. This recipe calls a server endpoint from a page's component script to display a greeting, without requiring an additional fetch request. @@ -13,6 +14,7 @@ Endpoints can be used to serve many kinds of data. This recipe calls a server en ## Recipe + 1. Create an endpoint in a new file `src/pages/api/hello.ts` that returns some data: ```ts title="src/pages/api/hello.ts" @@ -39,3 +41,4 @@ Endpoints can be used to serve many kinds of data. This recipe calls a server en

{data.greeting} world!

``` + diff --git a/src/content/docs/en/recipes/captcha.mdx b/src/content/docs/en/recipes/captcha.mdx index 5e910e75d2d12..e5ce38aa00b2f 100644 --- a/src/content/docs/en/recipes/captcha.mdx +++ b/src/content/docs/en/recipes/captcha.mdx @@ -4,16 +4,19 @@ description: Learn how to create an API route and fetch it from the client. i18nReady: true type: recipe --- +import { Steps } from '@astrojs/starlight/components'; [Server endpoints](/en/guides/endpoints/#server-endpoints-api-routes) can be used as REST API endpoints to run functions such as authentications, database access, and verifications without exposing sensitive data to the client. In this recipe, an API route is used to verify Google reCAPTCHA v3 without exposing the secret to clients. ## Prerequisites + - A project with [SSR](/en/guides/server-side-rendering/) (`output: 'server'`) enabled ## Recipe + 1. Create a `POST` endpoint that accepts recaptcha data, then verifies it with reCAPTCHA's API. Here, you can safely define secret values or read environment variables. ```js title="src/pages/recaptcha.js" @@ -74,3 +77,4 @@ In this recipe, an API route is used to verify Google reCAPTCHA v3 without expos ``` + diff --git a/src/content/docs/en/recipes/docker.mdx b/src/content/docs/en/recipes/docker.mdx index 66bfe62492078..26ba8b844faf9 100644 --- a/src/content/docs/en/recipes/docker.mdx +++ b/src/content/docs/en/recipes/docker.mdx @@ -4,6 +4,7 @@ description: Learn how to build your Astro site using Docker. type: recipe i18nReady: true --- +import { Steps } from '@astrojs/starlight/components'; [Docker](https://docker.com) is a tool to build, deploy, and run applications using containers. @@ -168,23 +169,24 @@ CMD node ./dist/server/entry.mjs ## Recipe + 1. Build your container by running the following command in your project's root directory. Use any name for ``: -```bash -docker build -t . -``` + ```bash + docker build -t . + ``` -This will output an image, which you can run locally or deploy to a platform of your choice. + This will output an image, which you can run locally or deploy to a platform of your choice. 2. To run your image as a local container, use the following command. -Replace `` with an open port on your machine. Replace `` with the port exposed by your Docker container (`4321`, `80`, or `8080` in the above examples.) + Replace `` with an open port on your machine. Replace `` with the port exposed by your Docker container (`4321`, `80`, or `8080` in the above examples.) -```bash -docker run -p : -``` + ```bash + docker run -p : + ``` -You should be able to access your site at `http://localhost:`. + You should be able to access your site at `http://localhost:`. 3. Now that your website is successfully built and packaged in a container, you can deploy it to a cloud provider. See the [Google Cloud](/en/guides/deploy/google-cloud/#cloud-run-ssr-and-static) deployment guide for one example, and the [Deploy your app](https://docs.docker.com/language/nodejs/deploy/) page in the Docker docs. - + diff --git a/src/content/docs/en/recipes/dynamically-importing-images.mdx b/src/content/docs/en/recipes/dynamically-importing-images.mdx index e703557e87bcb..c08d179f8fef3 100644 --- a/src/content/docs/en/recipes/dynamically-importing-images.mdx +++ b/src/content/docs/en/recipes/dynamically-importing-images.mdx @@ -4,6 +4,7 @@ description: Learn how to dynamically import images using Vite's import.meta.glo i18nReady: true type: recipe --- +import { Steps } from '@astrojs/starlight/components'; import { FileTree } from '@astrojs/starlight/components'; Local [images](/en/guides/images/) must be imported into `.astro` files in order to display them. There will be times where you will want or need to dynamically import the image paths of your images instead of explicitly importing each individual image. @@ -12,6 +13,7 @@ In this recipe, you will learn how to dynamically import your images using Vite' ## Recipe + 1. Create a new `assets` folder under the `src` directory and add your images inside that new folder. @@ -150,5 +152,4 @@ In this recipe, you will learn how to dynamically import your images using Vite' age={25} /> ``` - - + diff --git a/src/content/docs/en/recipes/external-links.mdx b/src/content/docs/en/recipes/external-links.mdx index 77369e197fb21..678869369b3d5 100644 --- a/src/content/docs/en/recipes/external-links.mdx +++ b/src/content/docs/en/recipes/external-links.mdx @@ -4,16 +4,18 @@ description: Learn how to install a rehype plugin to add icons to external links i18nReady: true type: recipe --- - -import PackageManagerTabs from '~/components/tabs/PackageManagerTabs.astro' +import { Steps } from '@astrojs/starlight/components'; +import PackageManagerTabs from '~/components/tabs/PackageManagerTabs.astro'; Using a rehype plugin, you can identify and modify links in your Markdown files that point to external sites. This example adds icons to the end of each external link, so that visitors will know they are leaving your site. ## Prerequisites + - An Astro project using Markdown for content pages. ## Recipe + 1. Install the `rehype-external-links` plugin. @@ -56,10 +58,12 @@ Using a rehype plugin, you can identify and modify links in your Markdown files }, }); ``` + + :::note + The value of the `content` property is [not represented in the accessibility tree](https://developer.mozilla.org/en-US/docs/Web/CSS/content#accessibility_concerns). As such, it's best to make clear that the link is external in the surrounding content, rather than relying on the icon alone. + ::: + -:::note - The value of the `content` property is [not represented in the accessibility tree](https://developer.mozilla.org/en-US/docs/Web/CSS/content#accessibility_concerns). As such, it's best to make clear that the link is external in the surrounding content, rather than relying on the icon alone. -::: ## Resources - [rehype-external-links](https://www.npmjs.com/package/rehype-external-links) diff --git a/src/content/docs/en/recipes/i18n.mdx b/src/content/docs/en/recipes/i18n.mdx index a62bda51b2a74..c143440b14fa6 100644 --- a/src/content/docs/en/recipes/i18n.mdx +++ b/src/content/docs/en/recipes/i18n.mdx @@ -5,8 +5,9 @@ type: recipe i18nReady: true --- import { FileTree } from '@astrojs/starlight/components'; -import ReadMore from '~/components/ReadMore.astro' -import StaticSsrTabs from '~/components/tabs/StaticSsrTabs.astro' +import ReadMore from '~/components/ReadMore.astro'; +import { Steps } from '@astrojs/starlight/components'; +import StaticSsrTabs from '~/components/tabs/StaticSsrTabs.astro'; In this recipe, you will learn how to use content collections and dynamic routing to build your own internationalization (i18n) solution and serve your content in different languages. @@ -21,6 +22,7 @@ If you prefer the default language to not be visible in the URL unlike other lan ### Set up pages for each language + 1. Create a directory for each language you want to support. For example, `en/` and `fr/` if you are supporting English and French: @@ -34,7 +36,6 @@ If you prefer the default language to not be visible in the URL unlike other lan - index.astro - index.astro - 2. Set up `src/pages/index.astro` to redirect to your default language. @@ -61,9 +62,11 @@ If you prefer the default language to not be visible in the URL unlike other lan ``` + ### Use collections for translated content + 1. Create a folder in `src/content/` for each type of content you want to include and add subdirectories for each supported language. For example, to support English and French blog posts: @@ -165,11 +168,13 @@ If you prefer the default language to not be visible in the URL unlike other lan The example above uses the built-in [`toLocaleString()` date-formatting method](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/toLocaleString) to create a human-readable string from the frontmatter date. This ensures the date and time are formatted to match the user’s language. ::: + ### Translate UI strings Create dictionaries of terms to translate the labels for UI elements around your site. This allows your visitors to experience your site fully in their language. + 1. Create a `src/i18n/ui.ts` file to store your translation strings: ```ts @@ -281,11 +286,13 @@ Create dictionaries of terms to translate the labels for UI elements around your ... ``` + ### Let users switch between languages Create links to the different languages you support so users can choose the language they want to read your site in. + 1. Create a component to show a link for each language: ```astro @@ -327,9 +334,11 @@ Create links to the different languages you support so users can choose the lang ``` + ### Hide default language in the URL + 1. Create a directory for each language except the default language. For example, store your default language pages directly in `pages/`, and your translated pages in `fr/`: @@ -349,7 +358,6 @@ Create links to the different languages you support so users can choose the lang export const showDefaultLang = false; ``` - 3. Add a helper function to `src/i18n/utils.ts`, to translate paths based on the current language: ```js @@ -408,11 +416,13 @@ Create links to the different languages you support so users can choose the lang ))} ``` + ### Translate Routes Translate the routes of your pages for each language. + 1. Add route mappings to `src/i18n/ui.ts`: ```ts @@ -498,6 +508,7 @@ Translate the routes of your pages for each language. ))} ``` + ## Resources - [Choosing a Language Tag](https://www.w3.org/International/questions/qa-choosing-language-tags) diff --git a/src/content/docs/en/recipes/modified-time.mdx b/src/content/docs/en/recipes/modified-time.mdx index ebbc2946d2a05..9a79e086dc7ad 100644 --- a/src/content/docs/en/recipes/modified-time.mdx +++ b/src/content/docs/en/recipes/modified-time.mdx @@ -4,13 +4,14 @@ description: Build a remark plugin to add the last modified time to your Markdow i18nReady: true type: recipe --- - -import PackageManagerTabs from '~/components/tabs/PackageManagerTabs.astro' +import { Steps } from '@astrojs/starlight/components'; +import PackageManagerTabs from '~/components/tabs/PackageManagerTabs.astro'; Learn how to build a [remark plugin](https://github.com/remarkjs/remark) that adds the last modified time to the frontmatter of your Markdown and MDX files. Use this property to display the modified time in your pages. ## Recipe + 1. Install Helper Packages Install [`Day.js`](https://www.npmjs.com/package/dayjs) to modify and format times: @@ -35,7 +36,7 @@ Learn how to build a [remark plugin](https://github.com/remarkjs/remark) that ad 2. Create a Remark Plugin - This plugin uses `execSync` to run a Git command that returns the timestamp of the latest commit in ISO 8601 format. The timestamp is then added to the frontmatter of the file. + This plugin uses `execSync` to run a Git command that returns the timestamp of the latest commit in ISO 8601 format. The timestamp is then added to the frontmatter of the file. ```js title="remark-modified-time.mjs" import { execSync } from "child_process"; @@ -142,3 +143,4 @@ Learn how to build a [remark plugin](https://github.com/remarkjs/remark) that ad ``` + diff --git a/src/content/docs/en/recipes/reading-time.mdx b/src/content/docs/en/recipes/reading-time.mdx index 6bda4d396c9b6..004af5fb9a2d6 100644 --- a/src/content/docs/en/recipes/reading-time.mdx +++ b/src/content/docs/en/recipes/reading-time.mdx @@ -4,113 +4,115 @@ description: Build a remark plugin to add reading time to your Markdown or MDX f i18nReady: true type: recipe --- - -import PackageManagerTabs from '~/components/tabs/PackageManagerTabs.astro' +import { Steps } from '@astrojs/starlight/components'; +import PackageManagerTabs from '~/components/tabs/PackageManagerTabs.astro'; Create a [remark plugin](https://github.com/remarkjs/remark) which adds a reading time property to the frontmatter of your Markdown or MDX files. Use this property to display the reading time for each page. ## Recipe + 1. Install Helper Packages - Install these two helper packages: - - [`reading-time`](https://www.npmjs.com/package/reading-time) to calculate minutes read - - [`mdast-util-to-string`](https://www.npmjs.com/package/mdast-util-to-string) to extract all text from your markdown - - - - ```shell - npm install reading-time mdast-util-to-string - ``` - - - ```shell - pnpm add reading-time mdast-util-to-string - ``` - - - ```shell - yarn add reading-time mdast-util-to-string - ``` - - + Install these two helper packages: + - [`reading-time`](https://www.npmjs.com/package/reading-time) to calculate minutes read + - [`mdast-util-to-string`](https://www.npmjs.com/package/mdast-util-to-string) to extract all text from your markdown + + + + ```shell + npm install reading-time mdast-util-to-string + ``` + + + ```shell + pnpm add reading-time mdast-util-to-string + ``` + + + ```shell + yarn add reading-time mdast-util-to-string + ``` + + 2. Create a remark plugin. - This plugin uses the `mdast-util-to-string` package to get the Markdown file's text. This text is then passed to the `reading-time` package to calculate the reading time in minutes. - - ```js title="remark-reading-time.mjs" - import getReadingTime from 'reading-time'; - import { toString } from 'mdast-util-to-string'; - - export function remarkReadingTime() { - return function (tree, { data }) { - const textOnPage = toString(tree); - const readingTime = getReadingTime(textOnPage); - // readingTime.text will give us minutes read as a friendly string, - // i.e. "3 min read" - data.astro.frontmatter.minutesRead = readingTime.text; - }; - } - ``` + This plugin uses the `mdast-util-to-string` package to get the Markdown file's text. This text is then passed to the `reading-time` package to calculate the reading time in minutes. + + ```js title="remark-reading-time.mjs" + import getReadingTime from 'reading-time'; + import { toString } from 'mdast-util-to-string'; + + export function remarkReadingTime() { + return function (tree, { data }) { + const textOnPage = toString(tree); + const readingTime = getReadingTime(textOnPage); + // readingTime.text will give us minutes read as a friendly string, + // i.e. "3 min read" + data.astro.frontmatter.minutesRead = readingTime.text; + }; + } + ``` 3. Add the plugin to your config: - ```js title="astro.config.mjs" "import { remarkReadingTime } from './remark-reading-time.mjs';" "remarkPlugins: [remarkReadingTime]," - import { defineConfig } from 'astro/config'; - import { remarkReadingTime } from './remark-reading-time.mjs'; + ```js title="astro.config.mjs" "import { remarkReadingTime } from './remark-reading-time.mjs';" "remarkPlugins: [remarkReadingTime]," + import { defineConfig } from 'astro/config'; + import { remarkReadingTime } from './remark-reading-time.mjs'; - export default defineConfig({ - markdown: { - remarkPlugins: [remarkReadingTime], - }, - }); - ``` + export default defineConfig({ + markdown: { + remarkPlugins: [remarkReadingTime], + }, + }); + ``` - Now all Markdown documents will have a calculated `minutesRead` property in their frontmatter. + Now all Markdown documents will have a calculated `minutesRead` property in their frontmatter. 4. Display Reading Time - If your blog posts are stored in a [content collection](/en/guides/content-collections/), access the `remarkPluginFrontmatter` from the `entry.render()` function. Then, render `minutesRead` in your template wherever you would like it to appear. - - ```astro title="src/pages/posts/[slug].astro" "const { Content, remarkPluginFrontmatter } = await entry.render();" "

{remarkPluginFrontmatter.minutesRead}

" - --- - import { CollectionEntry, getCollection } from 'astro:content'; - - export async function getStaticPaths() { - const blog = await getCollection('blog'); - return blog.map(entry => ({ - params: { slug: entry.slug }, - props: { entry }, - })); - } - - const { entry } = Astro.props; - const { Content, remarkPluginFrontmatter } = await entry.render(); - --- - - - ... - - ... -

{remarkPluginFrontmatter.minutesRead}

- ... - - - ``` - - If you're using a [Markdown layout](/en/guides/markdown-content/#markdown-and-mdx-pages), use the `minutesRead` frontmatter property from `Astro.props` in your layout template. - - ```astro title="src/layouts/BlogLayout.astro" "const { minutesRead } = Astro.props.frontmatter;" "

{minutesRead}

" - --- - const { minutesRead } = Astro.props.frontmatter; - --- - - - ... - -

{minutesRead}

- - - - ``` + If your blog posts are stored in a [content collection](/en/guides/content-collections/), access the `remarkPluginFrontmatter` from the `entry.render()` function. Then, render `minutesRead` in your template wherever you would like it to appear. + + ```astro title="src/pages/posts/[slug].astro" "const { Content, remarkPluginFrontmatter } = await entry.render();" "

{remarkPluginFrontmatter.minutesRead}

" + --- + import { CollectionEntry, getCollection } from 'astro:content'; + + export async function getStaticPaths() { + const blog = await getCollection('blog'); + return blog.map(entry => ({ + params: { slug: entry.slug }, + props: { entry }, + })); + } + + const { entry } = Astro.props; + const { Content, remarkPluginFrontmatter } = await entry.render(); + --- + + + ... + + ... +

{remarkPluginFrontmatter.minutesRead}

+ ... + + + ``` + + If you're using a [Markdown layout](/en/guides/markdown-content/#markdown-and-mdx-pages), use the `minutesRead` frontmatter property from `Astro.props` in your layout template. + + ```astro title="src/layouts/BlogLayout.astro" "const { minutesRead } = Astro.props.frontmatter;" "

{minutesRead}

" + --- + const { minutesRead } = Astro.props.frontmatter; + --- + + + ... + +

{minutesRead}

+ + + + ``` + diff --git a/src/content/docs/en/recipes/sharing-state.mdx b/src/content/docs/en/recipes/sharing-state.mdx index f3e1aa881307d..7654fbeeee96a 100644 --- a/src/content/docs/en/recipes/sharing-state.mdx +++ b/src/content/docs/en/recipes/sharing-state.mdx @@ -4,8 +4,8 @@ description: Learn how to share state across Astro components with Nano Stores. i18nReady: true type: recipe --- - -import PackageManagerTabs from '~/components/tabs/PackageManagerTabs.astro' +import { Steps } from '@astrojs/starlight/components'; +import PackageManagerTabs from '~/components/tabs/PackageManagerTabs.astro'; :::tip Using framework components? See [how to share state between Islands](/en/recipes/sharing-state-islands/)! @@ -15,70 +15,72 @@ When building an Astro website, you may need to share state across components. A ## Recipe + 1. Install Nano Stores: - - - ```shell - npm install nanostores - ``` - - - ```shell - pnpm add nanostores - ``` - - - ```shell - yarn add nanostores - ``` - - + + + ```shell + npm install nanostores + ``` + + + ```shell + pnpm add nanostores + ``` + + + ```shell + yarn add nanostores + ``` + + 2. Create a store. In this example, the store tracks whether a dialog is open or not: - ```ts title="src/store.js" - import { atom } from 'nanostores'; + ```ts title="src/store.js" + import { atom } from 'nanostores'; - export const isOpen = atom(false); - ``` + export const isOpen = atom(false); + ``` 3. Import and use the store in a ` - ``` - - ```astro title="src/components/Dialog.astro" - + + ``` - // Listen to changes in the store, and show/hide the dialog accordingly - isOpen.subscribe(open => { - if (open) { - document.getElementById('dialog').style.display = 'block'; - } else { - document.getElementById('dialog').style.display = 'none'; - } - }) - - ``` + ```astro title="src/components/Dialog.astro" + + + + ``` + ## Resources diff --git a/src/content/docs/en/recipes/tailwind-rendered-markdown.mdx b/src/content/docs/en/recipes/tailwind-rendered-markdown.mdx index f4eda932ed568..ff1049bf4a240 100644 --- a/src/content/docs/en/recipes/tailwind-rendered-markdown.mdx +++ b/src/content/docs/en/recipes/tailwind-rendered-markdown.mdx @@ -4,7 +4,7 @@ description: Learn how to use @tailwind/typography to style your rendered Markdo i18nReady: true type: recipe --- - +import { Steps } from '@astrojs/starlight/components'; import PackageManagerTabs from '~/components/tabs/PackageManagerTabs.astro'; You can use [Tailwind](https://tailwindcss.com)'s Typography plugin to style rendered Markdown from sources such as Astro's [**content collections**](/en/guides/content-collections/). @@ -58,7 +58,8 @@ export default { ## Recipe -1. Create a ` ` component to provide a wrapping `
` with a `` for your rendered Markdown. Add the style class `prose` alongside any desired [Tailwind element modifiers](https://tailwindcss.com/docs/typography-plugin#element-modifiers) in the parent element. + +1. Create a `` component to provide a wrapping `
` with a `` for your rendered Markdown. Add the style class `prose` alongside any desired [Tailwind element modifiers](https://tailwindcss.com/docs/typography-plugin#element-modifiers) in the parent element. ```astro title="src/components/Prose.astro" --- @@ -100,6 +101,7 @@ export default { ``` + ## Resources diff --git a/src/content/docs/en/reference/publish-to-npm.mdx b/src/content/docs/en/reference/publish-to-npm.mdx index 45d877209d65d..1da709523cfae 100644 --- a/src/content/docs/en/reference/publish-to-npm.mdx +++ b/src/content/docs/en/reference/publish-to-npm.mdx @@ -3,6 +3,7 @@ title: Publish to NPM description: Learn how to publish Astro components to NPM i18nReady: true --- +import { Steps } from '@astrojs/starlight/components'; import { FileTree } from '@astrojs/starlight/components'; Building a new Astro component? **Publish it to [npm!](https://npmjs.com/)** @@ -233,17 +234,22 @@ Astro does not currently ship a test runner. _(If you are interested in helping In the meantime, our current recommendation for testing is: + 1. Add a test `fixtures` directory to your `demo/src/pages` directory. + 2. Add a new page for every test that you'd like to run. + 3. Each page should include some different component usage that you'd like to test. + 4. Run `astro build` to build your fixtures, then compare the output of the `dist/__fixtures__/` directory to what you expected. + + - my-project/demo/src/pages/\_\_fixtures\_\_/ + - test-name-01.astro + - test-name-02.astro + - test-name-03.astro + + - -- my-project/demo/src/pages/\_\_fixtures\_\_/ - - test-name-01.astro - - test-name-02.astro - - test-name-03.astro - ## Publishing your component