New config documentation

scripts/docgen.mjs

@@ -3,7 +3,7 @@ import fetch from 'node-fetch';
 import jsdoc from 'jsdoc-api';
 
 // Fill this in to test a response locally, with fetching.
-const STUB = ``;
+const STUB = ``; // fs.readFileSync('/PATH/TO/MONOREPO/astro/packages/astro/src/@types/astro.ts', {encoding: 'utf-8'});
 
 const HEADER = `---
 # NOTE: This file is auto-generated from 'scripts/docgen.mjs'
@@ -15,10 +15,10 @@ setup: |
   import Since from '../../../components/Since.astro';
 ---
 
-The following reference covers all supported configuration options in Astro. To learn more configuring Astro, read our guide on [Configuring Astro](/en/guides/configuring-astro/).
+The following reference covers all supported configuration options in Astro. To learn more about configuring Astro, read our guide on [Configuring Astro](/en/guides/configuring-astro/).
 
 \`\`\`js
-// astro.config.js
+// astro.config.mjs
 import { defineConfig } from 'astro/config'
 
 export default defineConfig({
@@ -51,6 +51,9 @@ export async function run() {
     for (const comment of allParsedComments) {
         if (comment.kind === 'heading') {
             result += (`## ${comment.name}\n\n`);
+            if (comment.description) {
+                result += comment.description.trim() + '\n\n';
+            }
             continue;
         }
         const cliFlag = comment.tags.find(f => f.title === 'cli');
@@ -65,7 +68,7 @@ export async function run() {
             ? typerawFlag.text.replace(/\{(.*)\}/, '$1')
             : comment.type.names.join(' | ');
         result += [
-            `### ${comment.name}`,
+            `### ${comment.longname}`,
             ``,
             `<p>`,
             ``,

src/pages/en/guides/configuring-astro.md

@@ -3,15 +3,15 @@ layout: ~/layouts/MainLayout.astro
 title: Configuring Astro
 ---
 
-Customize how Astro works by adding an `astro.config.js` file in your project. This is a common file in Astro projects, and all official example templates and themes ship with one by default.
+Customize how Astro works by adding an `astro.config.mjs` file in your project. This is a common file in Astro projects, and all official example templates and themes ship with one by default.
 
 📚 Read Astro's [API configuration reference](/en/reference/configuration-reference/) for a full overview of all supported configuration options.
 ## The Astro Config File
 
 A valid Astro config file exports its configuration using the `default` export, using the recommended `defineConfig` helper:
 
 ```js
-// astro.config.js
+// astro.config.mjs
 import { defineConfig } from 'astro/config'
 
 export default defineConfig({
@@ -34,10 +34,10 @@ Astro supports several file formats for its JavaScript configuration file: `astr
 TypeScript config file loading is handled using [`tsm`](https://github.com/lukeed/tsm) and will respect your project tsconfig options.
 ## Config File Resolving
 
-Astro will automatically try to resolve a config file named `astro.config.js` inside [project root](/guide/#index-html-and-project-root). If no config file is found in your project root, Astro's default options will be used.
+Astro will automatically try to resolve a config file named `astro.config.mjs` inside [project root](/guide/#index-html-and-project-root). If no config file is found in your project root, Astro's default options will be used.
 
 ```bash
-# Example: Reads your configuration from ./astro.config.js
+# Example: Reads your configuration from ./astro.config.mjs
 astro build
 ```
 
@@ -53,7 +53,7 @@ astro build --config my-config-file.js
 Astro recommends using the `defineConfig()` helper in your configuration file. `defineConfig()` provides automatic IntelliSense in your IDE. Editors like VSCode are able to read Astro's TypeScript type definitions and provide automatic jsdoc type hints, even if your configuration file isn't written in TypeScript.
 
 ```js
-// astro.config.js
+// astro.config.mjs
 import { defineConfig } from 'astro/config'
 
 export default defineConfig({
@@ -65,7 +65,7 @@ export default defineConfig({
 You can also provide type definitions manually to VSCode, using this JSDoc notation:
 
 ```js
-// astro.config.js
+// astro.config.mjs
  export default /** @type {import('astro').AstroUserConfig} */ ({
   // your configuration options here...
   // https://docs.astro.build/en/reference/configuration-reference/

src/pages/en/guides/environment-variables.md

@@ -19,9 +19,6 @@ PUBLIC_ANYBODY=there
 
 In this example, `PUBLIC_ANYBODY` will be available as `import.meta.env.PUBLIC_ANYBODY` in server or client code, while `SECRET_PASSWORD` will not.
 
-> In prior releases, these variables were prefixed with `SNOWPACK_PUBLIC_` and required the `@snowpack/plugin-env` plugin.
-
-
 ## Setting environment variables
 
 In Astro v0.21+, environment variables can be loaded from `.env` files in your project directory.
@@ -47,7 +44,9 @@ PUBLIC_POKEAPI="https://pokeapi.co/api/v2"
 
 ## Getting environment variables
 
-Instead of using `process.env`, with Vite you use `import.meta.env`, which uses the `import.meta` feature added in ES2020 (don't worry about browser support though, Vite replaces all `import.meta.env` mentions with static values). For example, to get the `PUBLIC_POKEAPI` environment variable, you could use `import.meta.env.PUBLIC_POKEAPI`.
+> In this section we use `[dot]` to mean `.`. This is because of a bug in our build engine that is rewriting `import[dot]meta[dot]env` if we use `.` instead of `[dot]`.
+
+Instead of using `process.env`, with Vite you use `import[dot]meta[dot]env`, which uses the `import.meta` feature added in ES2020 (don't worry about browser support though, Vite replaces all `import[dot]meta[dot]env` mentions with static values). For example, to get the `PUBLIC_POKEAPI` environment variable, you could use `import.meta.env.PUBLIC_POKEAPI`.
 
 ```js
 // When import.meta.env.SSR === true
@@ -58,13 +57,13 @@ const data = fetch(`${import.meta.env.PUBLIC_POKEAPI}/pokemon/squirtle`);
 ```
 
 > ⚠️WARNING⚠️:
-> Because Vite statically replaces `import.meta.env`, you cannot access it with dynamic keys like `import.meta.env[key]`.
+> Because Vite statically replaces `import[dot]meta[dot]env`, you cannot access it with dynamic keys like `import[dot]meta[dot]env[key]`.
 
 
 
 ## IntelliSense for TypeScript
 
-By default, Vite provides type definition for `import.meta.env` in `vite/client.d.ts`. While you can define more custom env variables in `.env.[mode]` files, you may want to get TypeScript IntelliSense for user-defined env variables which prefixed with `PUBLIC_`.
+By default, Vite provides type definition for `import[dot]meta[dot]env` in `vite/client.d.ts`. While you can define more custom env variables in `.env.[mode]` files, you may want to get TypeScript IntelliSense for user-defined env variables which prefixed with `PUBLIC_`.
 
 To achieve, you can create an `env.d.ts` in `src` directory, then augment `ImportMetaEnv` like this:
 

src/pages/en/migrate.md

@@ -27,7 +27,7 @@ Read our [step-by-step walkthrough](/en/guides/integrations-guide) to learn how
 
 The new integration system replaces the previous `renderers` system, including the published `@astrojs/renderer-*` packages on npm. Going forward, `@astrojs/renderer-react` becomes `@astrojs/react`, `@astrojs/renderer-vue` becomes `@astrojs/vue`, and so on. 
 
-**To migrate:** update Astro to `v0.25.0` and then run `astro dev` or `astro build` with your old configuration file containing the outdated `"renderers"` config. You will immediately see a notice telling you the exact changes you need to make to your `astro.config.js` file, based on your current config. You can also update your packages yourself, using the table below. 
+**To migrate:** update Astro to `v0.25.0` and then run `astro dev` or `astro build` with your old configuration file containing the outdated `"renderers"` config. You will immediately see a notice telling you the exact changes you need to make to your `astro.config.mjs` file, based on your current config. You can also update your packages yourself, using the table below. 
 
 For a deeper walkthrough, read our [step-by-step guide](/en/guides/integrations-guide) to learn how to replace existing renderers with a new Astro framework integration.
 
@@ -38,7 +38,7 @@ For a deeper walkthrough, read our [step-by-step guide](/en/guides/integrations-
 + npm install @astrojs/react react react-dom
 ```
 ```diff
-# Then, update your `astro.config.js` file:
+# Then, update your `astro.config.mjs` file:
 # (Read the full walkthrough: https://docs.astro.build/en/guides/integrations-guide)
 + import lit from '@astrojs/lit';
 + import react from '@astrojs/react';