Doc improvements (#1929)

* Update astro & markdown code blocks for consistency

* Add 'JSX in Frontmatter' note to Migration Guide

docs/src/pages/core-concepts/routing.md

@@ -37,7 +37,7 @@ Dynamic parameters are encoded into the filename using `[bracket]` notation:
 
 Consider the following page `pages/post/[pid].astro`:
 
-```jsx
+```astro
 ---
 // Example: src/pages/post/[pid].astro
 const {pid} = Astro.request.params;

docs/src/pages/es/core-concepts/routing.md

@@ -37,7 +37,7 @@ Los parámetros dinámicos se codifican en el nombre del archivo usando la notac
 
 Considera la siguiente página `pages/post/[pid].astro`:
 
-```jsx
+```astro
 ---
 // Example: src/pages/post/[pid].astro
 const {pid} = Astro.request.params;

docs/src/pages/es/guides/imports.md

@@ -126,7 +126,7 @@ Recomendamos a los usuarios de Astro que eviten los archivos incorporados en Nod
 
 Nuestro objetivo es proporcionar alternativas de Astro a las incorporaciones comunes de Node.js. Sin embargo, hoy en día no existen tales alternativas. Entonces, si _realmente_ necesitas usar estos módulos incorporados, no queremos detenerte. Astro soporta incorporaciones de Node.js usando el prefijo `node:` más nuevo de Node. Si deseas leer un archivo, por ejemplo, puedes hacerlo así:
 
-```jsx
+```astro
 ---
 // Ejemplo: importar el "fs/promises" incorporado desde Node.js
 import fs from 'node:fs/promises';

docs/src/pages/es/reference/api-reference.md

@@ -104,7 +104,7 @@ If a page uses dynamic params in the filename, that component will need to expor
 
 This function is required because Astro is a static site builder. That means that your entire site is built ahead of time. If Astro doesn't know to generate a page at build time, your users won't see it when they visit your site.
 
-```jsx
+```astro
 ---
 export async function getStaticPaths() {
   return [
@@ -130,7 +130,7 @@ The `params` key of every returned object tells Astro what routes to build. The
 
 For example, suppose that you have a page at `src/pages/posts/[id].astro`. If you export `getStaticPaths` from this page and return the following for paths:
 
-```js
+```astro
 ---
 export async function getStaticPaths() {
   return [
@@ -151,7 +151,7 @@ To pass additional data to each generated page, you can also set a `props` value
 
 For example, suppose that you generate pages based off of data fetched from a remote API. You can pass the full data object to the page component inside of `getStaticPaths`:
 
-```js
+```astro
 ---
 export async function getStaticPaths() {
   const data = await fetch('...').then(response => response.json());

docs/src/pages/guides/imports.md

@@ -128,7 +128,7 @@ We encourage Astro users to avoid Node.js builtins (`fs`, `path`, etc) whenever
 
 Our aim is to provide Astro alternatives to common Node.js builtins. However, no such alternatives exist today. So, if you _really_ need to use these builtin modules we don't want to stop you. Astro supports Node.js builtins using Node's newer `node:` prefix. If you want to read a file, for example, you can do so like this:
 
-```jsx
+```astro
 ---
 // Example: import the "fs/promises" builtin from Node.js
 import fs from 'node:fs/promises';

docs/src/pages/guides/markdown-content.md

@@ -128,7 +128,7 @@ Using images or videos follows Astro's normal import rules:
 
 Astro has a dedicated component used to let you render your markdown as HTML components. This is a special component that is only exposed to `.astro` files. To use the `<Markdown>` component, within your frontmatter block use the following import statement:
 
-```jsx
+```astro
 ---
 import { Markdown } from 'astro/components';
 ---
@@ -136,7 +136,7 @@ import { Markdown } from 'astro/components';
 
 You can utilize this within your `.astro` file by doing the following:
 
-```jsx
+```astro
 ---
 import { Markdown } from 'astro/components';
 ---
@@ -152,7 +152,7 @@ import { Markdown } from 'astro/components';
 
 `<Markdown>` components provide more flexibility and allow you to use plain HTML or custom components. For example:
 
-````jsx
+````astro
 ---
 // For now, this import _must_ be named "Markdown" and _must not_ be wrapped with a custom component
 // We're working on easing these restrictions!
@@ -197,7 +197,7 @@ const expressions = 'Lorem ipsum';
 
 If you have Markdown in a remote source, you may pass it directly to the Markdown component through the `content` attribute. For example, the example below fetches the README from Snowpack's GitHub repository and renders it as HTML.
 
-```jsx
+```astro
 ---
 import { Markdown } from 'astro/components';
 
@@ -211,7 +211,7 @@ const content = await fetch('https://raw.githubusercontent.com/snowpackjs/snowpa
 
 There might be times when you want to combine both dynamic, and static markdown. If that is the case, you can nest `<Markdown>` components with each other to get the best of both worlds.
 
-```jsx
+```astro
 ---
 import { Markdown } from 'astro/components';
 

docs/src/pages/guides/pagination.md

@@ -86,7 +86,7 @@ For example, if you want to group your paginated markdown posts by some tag, you
 
 Nested pagination works by returning an array of `paginate()` results from `getStaticPaths()`, one for each grouping. In the following example, we will implement nested pagination to build the URLs listed above:
 
-```js
+```astro
 ---
 // Example: /src/pages/[tag]/[page].astro
 export function getStaticPaths({paginate}) {

docs/src/pages/guides/styling.md

@@ -303,7 +303,7 @@ Read on if you're looking for some strong opinions 🙂. We'll describe the appr
 
 You don't need an explanation on component-based design. You already know that reusing components is a good idea. And it's this idea that got people used to concepts like [Styled Components][styled-components] and [Styled JSX][styled-jsx]. But rather than burden your users with slow load times of CSS-in-JS, Astro has something better: **built-in scoped styles.**
 
-```jsx
+```astro
 ---
 // src/components/Button.astro -->
 ---
@@ -326,7 +326,7 @@ That `.btn` class is scoped within that component, and won't leak out. It means
 
 By contrast, Astro does allow global styles via the `:global()` and `<style global>` escape hatches. However, this should be avoided if possible. To illustrate this: say you used your button in a `<Nav />` component, and you wanted to style it differently there. You might be tempted to have something like:
 
-```jsx
+```astro
 ---
 // src/components/Nav.astro
 import Button from './Button.astro';
@@ -347,7 +347,7 @@ This is undesirable because now `<Nav>` and `<Button>` fight over what the final
 
 Instead, let `<Button>` control its own styles, and try a prop:
 
-```jsx
+```astro
 ---
 // src/components/Button.astro
 const { theme } = Astro.props;
@@ -437,7 +437,7 @@ While this guide will never be long enough to answer the question _"How should a
 
 The layout consists of a big, giant, full-width post at top, followed by two half-width posts below it. And below that, we want a bunch of smaller posts to fill out the rest of the page. For simplicity, we'll just call these `<BigPost>` (1), `<MediumPost>` (2), and `<SmallPost>` (3). We add them to our page like so:
 
-```jsx
+```astro
 ---
 // src/pages/index.astro
 
@@ -467,7 +467,7 @@ This _looks_ clean, but looks can be deceiving. At first glance, we may think th
 
 This is actually the **Global CSS Problem** in disguise—multiple components fight over how they all lay out together, without layout being one, central responsibility (kinda like global CSS)! Now that we identified the problem, one way to fix this is to hoist the entire layout to the top level, and load all components there, too:
 
-```jsx
+```astro
 ---
 // src/pages/index.astro
 

docs/src/pages/migration/0.21.0.md

@@ -65,7 +65,7 @@ const colors = { foregroundColor: "rgb(221 243 228)", backgroundColor: "rgb(24 1
 
 In Astro v0.21, Components from any framework can be used within Markdown files.
 
-```md
+```markdown
 ---
 Layout: '...'
 setup: |
@@ -81,6 +81,10 @@ setup: |
 </MyReactComponent>
 ```
 
+## JSX in Frontmatter
+
+In Astro v0.21, JSX cannot be used within Frontmatter.
+
 ## Environment Variables
 
 In Astro v0.21, environment variables can be loaded from `.env` files in your project directory.

docs/src/pages/reference/api-reference.md

@@ -103,7 +103,7 @@ If a page uses dynamic params in the filename, that component will need to expor
 
 This function is required because Astro is a static site builder. That means that your entire site is built ahead of time. If Astro doesn't know to generate a page at build time, your users won't see it when they visit your site.
 
-```jsx
+```astro
 ---
 export async function getStaticPaths() {
   return [
@@ -129,7 +129,7 @@ The `params` key of every returned object tells Astro what routes to build. The
 
 For example, suppose that you have a page at `src/pages/posts/[id].astro`. If you export `getStaticPaths` from this page and return the following for paths:
 
-```js
+```astro
 ---
 export async function getStaticPaths() {
   return [
@@ -150,7 +150,7 @@ To pass additional data to each generated page, you can also set a `props` value
 
 For example, suppose that you generate pages based off of data fetched from a remote API. You can pass the full data object to the page component inside of `getStaticPaths`:
 
-```js
+```astro
 ---
 export async function getStaticPaths() {
   const data = await fetch('...').then(response => response.json());

examples/docs/README.md

@@ -60,7 +60,7 @@ This theme uses a "cool blue" accent color by default. To customize this for you
 
 Astro uses frontmatter in Markdown pages to choose layouts and pass properties to those layouts. If you are using the default layout, you can customize the page in many different ways to optimize SEO and other things. For example, you can use the `title` and `description` properties to set the document title, meta title, meta description, and Open Graph description.
 
-```md
+```markdown
 ---
 title: Example title
 description: Really cool docs example that uses Astro

packages/renderers/renderer-lit/readme.md

@@ -53,7 +53,7 @@ In your Astro template import this component as a side-effect and use the elemen
 
 __src/pages/index.astro__
 
-```jsx
+```astro
 ---
 import '../components/my-element.js';
 ---
@@ -69,7 +69,7 @@ The renderer automatically handles adding appropriate polyfills for support in b
 
 Hydration is also handled automatically. You can use the same hydration directives such as `client:load`, `client:idle` and `client:visible` as you can with other libraries that Astro supports.
 
-```jsx
+```astro
 ---
 import '../components/my-element.js';
 ---