diff --git a/src/pages/en/guides/environment-variables.md b/src/pages/en/guides/environment-variables.md index 565ed18dba51e..062e44e18f6dc 100644 --- a/src/pages/en/guides/environment-variables.md +++ b/src/pages/en/guides/environment-variables.md @@ -6,7 +6,7 @@ setup: | import ImportMetaEnv from '~/components/ImportMetaEnv.astro'; --- -Astro uses Vite for environment variables, and allows you to use any of its methods to get and set environment variables. +Astro uses Vite for environment variables, and allows you to [use any of its methods](https://vitejs.dev/guide/env-and-mode.html) to get and set environment variables. Note that while _all_ environment variables are available in server-side code, only environment variables prefixed with `PUBLIC_` are available in client-side code for security purposes. @@ -17,7 +17,20 @@ SECRET_PASSWORD=password123 PUBLIC_ANYBODY=there ``` -In this example, `PUBLIC_ANYBODY` will be available in server or client code, while `SECRET_PASSWORD` will not. +In this example, `PUBLIC_ANYBODY` (accessible via ``) will be available in server or client code, while `SECRET_PASSWORD` (accessible via ``) will be server-side only. + +## Default environment Variables + +Astro includes a few environment variables out-of-the-box: + +- ` ('development' | 'production')`: the mode your site is running in. This is `development` when running `astro dev` and `production` when running `astro build`. + +- ` (string)`: the base url your site is being served from. This is determined by the [base config option](/en/reference/configuration-reference/#base). + +- ` (boolean)`: whether your site is running in production. + +- ` (boolean)`: whether your site is running in development (always the opposite of ``). +- ` (string)`: [The `site` option](/en/reference/configuration-reference/#site) specified in your project's `astro.config`. ## Setting environment variables diff --git a/src/pages/en/guides/rss.md b/src/pages/en/guides/rss.md index e2b77679d0d2c..84f218347f7c7 100644 --- a/src/pages/en/guides/rss.md +++ b/src/pages/en/guides/rss.md @@ -6,11 +6,117 @@ description: An intro to RSS in Astro Astro supports fast, automatic RSS feed generation for blogs and other content websites. For more information about RSS feeds in general, see [aboutfeeds.com](https://aboutfeeds.com/). -You can create an RSS feed from any Astro page that uses a `getStaticPaths()` function for routing. Only dynamic routes can use `getStaticPaths()` today (see [Routing](/en/core-concepts/routing)). +## Using `@astrojs/rss` (recommended) -> We hope to make this feature available to all other pages before v1.0. As a workaround, you can convert a static route to a dynamic route that only generates a single page. See [Routing](/en/core-concepts/routing) for more information about dynamic routes. +The `@astrojs/rss` package provides helpers for generating RSS feeds using [API endpoints](/en/core-concepts/astro-pages/#non-html-pages). This unlocks both static builds _and_ on-demand generation when using an [SSR adapter](/en/guides/server-side-rendering/#enabling-ssr-in-your-project). -Create an RSS Feed by calling the `rss()` function that is passed as an argument to `getStaticPaths()`. This will create an `rss.xml` file in your final build based on the data that you provide using the `items` array. +First, install `@astrojs/rss` using your preferred package manager: + +```bash +# npm +npm i @astrojs/rss +# yarn +yarn add @astrojs/rss +# pnpm +pnpm i @astrojs/rss +``` + +Then, ensure you've [configured a `site`](/en/reference/configuration-reference/#site) in your project's `astro.config`. We will use this to generate links in your RSS feed. + +Now, let's generate our first RSS feed! Create an `rss.xml.js` file under your `src/pages/` directory. `rss.xml` will be the output URL, so feel free to rename this if you prefer. + +Now, import the `rss` helper from the `@astrojs/rss` package and call with the following parameters: + +```js +// src/pages/rss.xml.js +import rss from '@astrojs/rss'; + +export const get = () => rss({ + // `` field in output xml + title: 'Buzz’s Blog', + // `<description>` field in output xml + description: 'A humble Astronaut’s guide to the stars', + // list of `<item>`s in output xml + // simple example: generate items for every md file in /src/pages + // see "Generating items" section for required frontmatter and advanced use cases + items: import.meta.glob('./**/*.md'), + // (optional) inject custom xml + customData: `<language>en-us</language>`, + }); +``` + +### Generating `items` + +The `items` field accepts either: +1. [An `import.meta.glob(...)` result](#2-importmetaglob-result) **(only use this for `.md` files within the `src/pages/` directory!)** +2. [A list of RSS feed objects](#1-list-of-rss-feed-objects), each with a `link`, `title`, `pubDate`, and optional `description` and `customData` fields. + +#### 1. `import.meta.glob` result + +We recommend this option as a convenient shorthand for `.md` files under `src/pages/`. Each post should have a `title`, `pubDate`, and optional `description` and `customData` fields in its frontmatter. If this isn't possible, or you'd prefer to generate this frontmatter in code, [see option 2](#2-list-of-rss-feed-objects). + +Say your blog posts are stored under the `src/pages/blog/` directory. You can generate an RSS feed like so: + +```js +// src/pages/rss.xml.js +import rss from '@astrojs/rss'; + +export const get = () => rss({ + title: 'Buzz’s Blog', + description: 'A humble Astronaut’s guide to the stars', + items: import.meta.glob('./blog/**/*.md'), + }); +``` + +See [Vite's glob import documentation](https://vitejs.dev/guide/features.html#glob-import) for more on this import syntax. + +#### 2. List of RSS feed objects + +We recommend this option for `.md` files outside of the `pages` directory. This is common when generating routes [via `getStaticPaths`](/en/reference/api-reference/#getstaticpaths). + +For instance, say your `.md` posts are stored under a `src/posts/` directory. Each post has a `title`, `pubDate`, and `slug` in its frontmatter, where `slug` corresponds to the output URL on your site. We can generate an RSS feed using [Vite's `import.meta.globEager` helper](https://vitejs.dev/guide/features.html#glob-import) like so: + +```js +// src/pages/rss.xml.js +import rss from '@astrojs/rss'; + +const postImportResult = import.meta.globEager('../posts/**/*.md'); +const posts = Object.values(postImportResult); + +export const get = () => rss({ + title: 'Buzz’s Blog', + description: 'A humble Astronaut’s guide to the stars', + items: posts.map((post) => ({ + link: post.frontmatter.slug, + title: post.frontmatter.title, + pubDate: post.frontmatter.pubDate, + })) + }); +``` + +### Adding a stylesheet + +You can style your RSS feed for a more pleasant user experience when viewing the file in your browser. + +Use the `rss` function's `stylesheet` option to specify an absolute path to your stylesheet. + +```js +rss({ + // ex. use your stylesheet from "public/rss/styles.xsl" + stylesheet: '/rss/styles.xsl', + // ... +}); +``` + +If you don't have an RSS stylesheet in mind, we recommend the [Pretty Feed v3 default stylesheet](https://github.com/genmon/aboutfeeds/blob/main/tools/pretty-feed-v3.xsl), which you can download from GitHub and save into your project's `public/` directory. + +## Using `getStaticPaths()` + +> **Note:** This method has been deprecated, and will be removed before the official `v1.0.0` release. Please use `@astrojs/rss` instead. + +You can also create an RSS feed from any Astro page that uses a `getStaticPaths()` function for routing. Only dynamic routes can use `getStaticPaths()` today (see [Routing](/en/core-concepts/routing)). + +Create an RSS Feed by calling the `rss()` function that is passed as an argument to `getStaticPaths()`. This will create an `rss.xml` file in your final build (or whatever you specify using `dest`) based on the data that you provide using the `items` array. ```js // Example: /src/pages/posts/[...page].astro @@ -35,19 +141,17 @@ export async function getStaticPaths({rss}) { })), // Optional: Customize where the file is written to. // Otherwise, defaults to "/rss.xml" - dest: "/my/custom/feed.xml", + dest: '/my/custom/feed.xml', }); // Return your paths return [...]; } ``` -Note: RSS feeds will **not** be built during development. Currently, RSS feeds are only generated during your final build. - -### Styling +Note: RSS feeds will **not** be built during development when using this method. -RSS Feeds can be styled with an XSL stylesheet for a more pleasant user experience when they are opened directly in a browser. By default, Astro does not set a stylesheet for RSS feeds, but it can be enabled by setting the `stylesheet` option. +### Adding a stylesheet -Astro can automatically use [Pretty Feed](https://github.com/genmon/aboutfeeds/blob/main/tools/pretty-feed-v3.xsl), a popular open-source XSL stylesheet. To enable this behavior, pass `stylesheet: true`. +When using the `getStaticPaths` method to RSS, we will optionally generate a stylesheet for you. Pass `stylesheet: true` as an option to pull in the [Pretty Feed](https://github.com/genmon/aboutfeeds/blob/main/tools/pretty-feed-v3.xsl) XSL stylesheet. -If you'd like to use a custom XSL stylesheet, you can pass a string value like `stylesheet: '/my-custom-stylesheet.xsl'`. This file should be in your `public/` directory (in this case, `public/my-custom-stylesheet.xsl`). +If you'd like to use a custom XSL stylesheet, you can pass a string value like `stylesheet: '/my-custom-stylesheet.xsl'`. This file should be in your `public/` directory (in this case, `/public/my-custom-stylesheet.xsl`).