astro/docs/syntax.md

## ✨ `.astro` Syntax

Astro comes with its own server-side, component-based templating language. Think of it as HTML enhanced with the full power of JavaScript.

Learning a new syntax can be intimidating, but the `.astro` format has been carefully designed with familiarity in mind. It borrows heavily from patterns you likely already know—components, Frontmatter, and JSX-like expressions. We're confident that this guide will help you feel comfortable writing `.astro` files in no time.

---

### The `.astro` format

If you're already familiar with **HTML or JavaScript**, you'll likely feel comfortable with `.astro` files right away.

Think of `.astro` as **component-oriented HTML**. Components are reusable, self-contained blocks of HTML and CSS that belong together.

```html
<!-- This is a valid Astro component -->
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>Document</title>
  </head>
  <body>
    <main>
      <h1>Hello world!</h1>
    </main>
  </body>
</html>
```

```html
<!-- This is also a valid Astro component! -->
<main>
  <h1>Hello world!</h1>
</main>
```

Developers have come up with a myriad of different techniques for composing blocks of HTML over the years, but far and away the most successful has been [JSX](https://reactjs.org/docs/introducing-jsx.html).

We love JSX! In fact, `.astro` files borrow the highly-expressive expression syntax directly from JSX.

```jsx
<!-- This is an Astro component with expressions! -->
<main>
  <h1>Hello {name}!</h1>
  <ul>
    {items.map((item) => (
      <li>{item}</li>
    ))}
  </ul>
  <h2 data-hint={`Use JS template strings when you need to mix-in ${"variables"}.`}>So good!</h2>
</main>
```

`.astro` files also borrow the concept of [Frontmatter](https://jekyllrb.com/docs/front-matter/) from Markdown. Instead of introducing a new HTML-oriented `import` and `export` syntax, `.astro` just uses JavaScript.

```jsx
---
// This area is TypeScript (and therefore JavaScript)!
import MyComponent from './MyComponent.astro'
---

<html lang="en">
  <head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>Document</title>
  </head>
  <body>
    <MyComponent></MyComponent>
  </body>
</html>
```

### Data and Props

`.astro` components can define local variables inside of the Frontmatter script. These are automatically exposed to the content below.

```jsx
---
let name = 'world';
---

<main>
    <h1>Hello {name}!</h1>
</main>
```

`.astro` components can also accept props when they are rendered. Public props can be marked using the `export` keyword.

Local values are overwritten when props are passed, otherwise they are considered the default value.

```jsx
---
export let greeting = 'Hello';
export let name;
---

<main>
    <h1>{greeting} {name}!</h1>
</main>
```

### Fragments

At the top-level of an `.astro` file, you may render any number of elements.

```html
<!-- Look, no Fragment! -->
<div id="a" />
<div id="b" />
<div id="c" />
```

Inside of an expression, you must wrap multiple elements in a Fragment. Fragments must open with `<>` and close with `</>`.

```jsx
<div>
  {[0, 1, 2].map((id) => (
    <>
      <div id={`a-${id}`} />
      <div id={`b-${id}`} />
      <div id={`c-${id}`} />
    </>
  ))}
</div>
```

### `.astro` versus `.jsx`

`.astro` files can end up looking very similar to `.jsx` files, but there are a few key differences. Here's a comparison between the two formats.

| Feature                      | Astro                                      | JSX                                                |
| ---------------------------- | ------------------------------------------ | -------------------------------------------------- |
| File extension               | `.astro`                                   | `.jsx` or `.tsx`                                   |
| User-Defined Components      | `<Capitalized>`                            | `<Capitalized>`                                    |
| Expression Syntax            | `{}`                                       | `{}`                                               |
| Spread Attributes            | `{...props}`                               | `{...props}`                                       |
| Boolean Attributes           | `autocomplete` === `autocomplete={true}`   | `autocomplete` === `autocomplete={true}`           |
| Inline Functions             | `{items.map(item => <li>{item}</li>)}`     | `{items.map(item => <li>{item}</li>)}`             |
| IDE Support                  | WIP - [VS Code][code-ext]                  | Phenomenal                                         |
| Requires JS import           | No                                         | Yes, `jsxPragma` (`React` or `h`) must be in scope |
| Fragments                    | Automatic top-level, `<>` inside functions | Wrap with `<Fragment>` or `<>`                     |
| Multiple frameworks per-file | Yes                                        | No                                                 |
| Modifying `<head>`           | Just use `<head>`                          | Per-framework (`<Head>`, `<svelte:head>`, etc)     |
| Comment Style                | `<!-- HTML -->`                            | `{/* JavaScript */}`                               |
| Special Characters           | `&nbsp;`                                   | `{'\xa0'}` or `{String.fromCharCode(160)}`         |
| Attributes                   | `dash-case`                                | `camelCase`                                        |

### URL resolution

It’s important to note that Astro **won’t** transform HTML references for you. For example, consider an `<img>` tag with a relative `src` attribute inside `src/pages/about.astro`:

```html
<!-- ❌ Incorrect: will try and load `/about/thumbnail.png` -->
<img src="./thumbnail.png" />
```

Since `src/pages/about.astro` will build to `/about/index.html`, you may not have expected that image to live at `/about/thumbnail.png`. So to fix this, choose either of two options:

#### Option 1: Absolute URLs

```html
<!-- ✅ Correct: references public/thumbnail.png -->
<img src="/thumbnail.png" />
```

The recommended approach is to place files within `public/*`. This references a file it `public/thumbnail.png`, which will resolve to `/thumbnail.png` at the final build (since `public/` ends up at `/`).

#### Option 2: Asset import references

```jsx
---
//  ✅ Correct: references src/thumbnail.png
import thumbnailSrc from './thumbnail.png';
---

<img src={thumbnailSrc} />
```

If you’d prefer to organize assets alongside Astro components, you may import the file in JavaScript inside the component script. This works as intended but this makes `thumbnail.png` harder to reference in other parts of your app, as its final URL isn’t easily-predictable (unlike assets in `public/*`, where the final URL is guaranteed to never change).

### TODO: Composition (Slots)

[code-ext]: https://marketplace.visualstudio.com/items?itemName=astro-build.astro-vscode
-												Docs: add `.astro` Syntax guide (#137)

* wip: astro syntax docs

* docs: update syntax guide

* docs: add IDE note

* chore: beautify file

* docs: edits

* Update docs/syntax.md

Co-authored-by: Drew Powers <1369770+drwpow@users.noreply.github.com>

* docs: be kinder to JSX :)

* fix: spelling

* docs: clarify some code comments

Co-authored-by: Drew Powers <1369770+drwpow@users.noreply.github.com>
											
										
										
											2021-04-28 19:55:25 +00:00
+								## ✨ `.astro` Syntax
-												docs: update syntax docs (#449)


											
										
										
											2021-06-15 19:32:32 +00:00
+								Astro comes with its own server-side, component-based templating language. Think of it as HTML enhanced with the full power of JavaScript.
-												Docs: add `.astro` Syntax guide (#137)

* wip: astro syntax docs

* docs: update syntax guide

* docs: add IDE note

* chore: beautify file

* docs: edits

* Update docs/syntax.md

Co-authored-by: Drew Powers <1369770+drwpow@users.noreply.github.com>

* docs: be kinder to JSX :)

* fix: spelling

* docs: clarify some code comments

Co-authored-by: Drew Powers <1369770+drwpow@users.noreply.github.com>
											
										
										
											2021-04-28 19:55:25 +00:00
-												docs: update syntax docs (#449)


											
										
										
											2021-06-15 19:32:32 +00:00
+								Learning a new syntax can be intimidating, but the `.astro` format has been carefully designed with familiarity in mind. It borrows heavily from patterns you likely already know—components, Frontmatter, and JSX-like expressions. We're confident that this guide will help you feel comfortable writing `.astro` files in no time.
-												Docs: add `.astro` Syntax guide (#137)

* wip: astro syntax docs

* docs: update syntax guide

* docs: add IDE note

* chore: beautify file

* docs: edits

* Update docs/syntax.md

Co-authored-by: Drew Powers <1369770+drwpow@users.noreply.github.com>

* docs: be kinder to JSX :)

* fix: spelling

* docs: clarify some code comments

Co-authored-by: Drew Powers <1369770+drwpow@users.noreply.github.com>
											
										
										
											2021-04-28 19:55:25 +00:00
 								---
-												docs: update syntax docs (#449)


											
										
										
											2021-06-15 19:32:32 +00:00
+								### The `.astro` format
-												Docs: add `.astro` Syntax guide (#137)

* wip: astro syntax docs

* docs: update syntax guide

* docs: add IDE note

* chore: beautify file

* docs: edits

* Update docs/syntax.md

Co-authored-by: Drew Powers <1369770+drwpow@users.noreply.github.com>

* docs: be kinder to JSX :)

* fix: spelling

* docs: clarify some code comments

Co-authored-by: Drew Powers <1369770+drwpow@users.noreply.github.com>
											
										
										
											2021-04-28 19:55:25 +00:00
-												docs: update syntax docs (#449)


											
										
										
											2021-06-15 19:32:32 +00:00
+								If you're already familiar with **HTML or JavaScript**, you'll likely feel comfortable with `.astro` files right away.
-												Docs: add `.astro` Syntax guide (#137)

* wip: astro syntax docs

* docs: update syntax guide

* docs: add IDE note

* chore: beautify file

* docs: edits

* Update docs/syntax.md

Co-authored-by: Drew Powers <1369770+drwpow@users.noreply.github.com>

* docs: be kinder to JSX :)

* fix: spelling

* docs: clarify some code comments

Co-authored-by: Drew Powers <1369770+drwpow@users.noreply.github.com>
											
										
										
											2021-04-28 19:55:25 +00:00
 								Think of `.astro` as **component-oriented HTML**. Components are reusable, self-contained blocks of HTML and CSS that belong together.
 								```html
 								<!-- This is a valid Astro component -->
 								<html lang="en">
 								  <head>
 								    <meta charset="UTF-8" />
 								    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
 								    <title>Document</title>
 								  </head>
 								  <body>
 								    <main>
 								      <h1>Hello world!</h1>
 								    </main>
 								  </body>
 								</html>
 								```
 								```html
 								<!-- This is also a valid Astro component! -->
 								<main>
 								  <h1>Hello world!</h1>
 								</main>
 								```
 								Developers have come up with a myriad of different techniques for composing blocks of HTML over the years, but far and away the most successful has been [JSX](https://reactjs.org/docs/introducing-jsx.html).
-												docs: update syntax docs (#449)


											
										
										
											2021-06-15 19:32:32 +00:00
+								We love JSX! In fact, `.astro` files borrow the highly-expressive expression syntax directly from JSX.
-												Docs: add `.astro` Syntax guide (#137)

* wip: astro syntax docs

* docs: update syntax guide

* docs: add IDE note

* chore: beautify file

* docs: edits

* Update docs/syntax.md

Co-authored-by: Drew Powers <1369770+drwpow@users.noreply.github.com>

* docs: be kinder to JSX :)

* fix: spelling

* docs: clarify some code comments

Co-authored-by: Drew Powers <1369770+drwpow@users.noreply.github.com>
											
										
										
											2021-04-28 19:55:25 +00:00
 								```jsx
 								<!-- This is an Astro component with expressions! -->
 								<main>
 								  <h1>Hello {name}!</h1>
 								  <ul>
 								    {items.map((item) => (
 								      <li>{item}</li>
 								    ))}
 								  </ul>
-												docs: update syntax docs (#449)


											
										
										
											2021-06-15 19:32:32 +00:00
+								  <h2 data-hint={`Use JS template strings when you need to mix-in ${"variables"}.`}>So good!</h2>
-												Docs: add `.astro` Syntax guide (#137)

* wip: astro syntax docs

* docs: update syntax guide

* docs: add IDE note

* chore: beautify file

* docs: edits

* Update docs/syntax.md

Co-authored-by: Drew Powers <1369770+drwpow@users.noreply.github.com>

* docs: be kinder to JSX :)

* fix: spelling

* docs: clarify some code comments

Co-authored-by: Drew Powers <1369770+drwpow@users.noreply.github.com>
											
										
										
											2021-04-28 19:55:25 +00:00
+								</main>
 								```
-												docs: update syntax docs (#449)


											
										
										
											2021-06-15 19:32:32 +00:00
+								`.astro` files also borrow the concept of [Frontmatter](https://jekyllrb.com/docs/front-matter/) from Markdown. Instead of introducing a new HTML-oriented `import` and `export` syntax, `.astro` just uses JavaScript.
-												Docs: add `.astro` Syntax guide (#137)

* wip: astro syntax docs

* docs: update syntax guide

* docs: add IDE note

* chore: beautify file

* docs: edits

* Update docs/syntax.md

Co-authored-by: Drew Powers <1369770+drwpow@users.noreply.github.com>

* docs: be kinder to JSX :)

* fix: spelling

* docs: clarify some code comments

Co-authored-by: Drew Powers <1369770+drwpow@users.noreply.github.com>
											
										
										
											2021-04-28 19:55:25 +00:00
 								```jsx
 								---
 								// This area is TypeScript (and therefore JavaScript)!
 								import MyComponent from './MyComponent.astro'
 								---
 								<html lang="en">
 								  <head>
 								    <meta charset="UTF-8">
 								    <meta name="viewport" content="width=device-width, initial-scale=1.0">
 								    <title>Document</title>
 								  </head>
 								  <body>
 								    <MyComponent></MyComponent>
 								  </body>
 								</html>
 								```
 								### Data and Props
 								`.astro` components can define local variables inside of the Frontmatter script. These are automatically exposed to the content below.
 								```jsx
 								---
 								let name = 'world';
 								---
 								<main>
 								    <h1>Hello {name}!</h1>
 								</main>
 								```
 								`.astro` components can also accept props when they are rendered. Public props can be marked using the `export` keyword.
 								Local values are overwritten when props are passed, otherwise they are considered the default value.
 								```jsx
 								---
 								export let greeting = 'Hello';
 								export let name;
 								---
 								<main>
 								    <h1>{greeting} {name}!</h1>
 								</main>
 								```
-												Add `<>` fragment support for expressions (#433)

* feat: add support for `<>` and `</>` Fragments

* docs: explain Fragments

* test: add fragment test
											
										
										
											2021-06-15 16:33:27 +00:00
+								### Fragments
 								At the top-level of an `.astro` file, you may render any number of elements.
 								```html
 								<!-- Look, no Fragment! -->
 								<div id="a" />
 								<div id="b" />
 								<div id="c" />
 								```
 								Inside of an expression, you must wrap multiple elements in a Fragment. Fragments must open with `<>` and close with `</>`.
 								```jsx
 								<div>
-												[ci] yarn format

											
										
										
											2021-06-15 16:34:46 +00:00
+								  {[0, 1, 2].map((id) => (
 								    <>
 								      <div id={`a-${id}`} />
 								      <div id={`b-${id}`} />
 								      <div id={`c-${id}`} />
 								    </>
 								  ))}
-												Add `<>` fragment support for expressions (#433)

* feat: add support for `<>` and `</>` Fragments

* docs: explain Fragments

* test: add fragment test
											
										
										
											2021-06-15 16:33:27 +00:00
+								</div>
 								```
-												Docs: add `.astro` Syntax guide (#137)

* wip: astro syntax docs

* docs: update syntax guide

* docs: add IDE note

* chore: beautify file

* docs: edits

* Update docs/syntax.md

Co-authored-by: Drew Powers <1369770+drwpow@users.noreply.github.com>

* docs: be kinder to JSX :)

* fix: spelling

* docs: clarify some code comments

Co-authored-by: Drew Powers <1369770+drwpow@users.noreply.github.com>
											
										
										
											2021-04-28 19:55:25 +00:00
+								### `.astro` versus `.jsx`
 								`.astro` files can end up looking very similar to `.jsx` files, but there are a few key differences. Here's a comparison between the two formats.
-												[ci] yarn format

											
										
										
											2021-06-15 16:34:46 +00:00
+								| Feature                      | Astro                                      | JSX                                                |
 								| ---------------------------- | ------------------------------------------ | -------------------------------------------------- |
 								| File extension               | `.astro`                                   | `.jsx` or `.tsx`                                   |
 								| User-Defined Components      | `<Capitalized>`                            | `<Capitalized>`                                    |
 								| Expression Syntax            | `{}`                                       | `{}`                                               |
 								| Spread Attributes            | `{...props}`                               | `{...props}`                                       |
 								| Boolean Attributes           | `autocomplete` === `autocomplete={true}`   | `autocomplete` === `autocomplete={true}`           |
 								| Inline Functions             | `{items.map(item => <li>{item}</li>)}`     | `{items.map(item => <li>{item}</li>)}`             |
 								| IDE Support                  | WIP - [VS Code][code-ext]                  | Phenomenal                                         |
 								| Requires JS import           | No                                         | Yes, `jsxPragma` (`React` or `h`) must be in scope |
 								| Fragments                    | Automatic top-level, `<>` inside functions | Wrap with `<Fragment>` or `<>`                     |
 								| Multiple frameworks per-file | Yes                                        | No                                                 |
 								| Modifying `<head>`           | Just use `<head>`                          | Per-framework (`<Head>`, `<svelte:head>`, etc)     |
 								| Comment Style                | `<!-- HTML -->`                            | `{/* JavaScript */}`                               |
 								| Special Characters           | `&nbsp;`                                   | `{'\xa0'}` or `{String.fromCharCode(160)}`         |
 								| Attributes                   | `dash-case`                                | `camelCase`                                        |
-												Docs: add `.astro` Syntax guide (#137)

* wip: astro syntax docs

* docs: update syntax guide

* docs: add IDE note

* chore: beautify file

* docs: edits

* Update docs/syntax.md

Co-authored-by: Drew Powers <1369770+drwpow@users.noreply.github.com>

* docs: be kinder to JSX :)

* fix: spelling

* docs: clarify some code comments

Co-authored-by: Drew Powers <1369770+drwpow@users.noreply.github.com>
											
										
										
											2021-04-28 19:55:25 +00:00
-												Improve asset resolution in Astro (#437)

* Improve asset resolution in Astro

Fixes #96

* Add docs, changeset

* Fix collection resolution
											
										
										
											2021-06-15 20:53:16 +00:00
+								### URL resolution
 								It’s important to note that Astro **won’t** transform HTML references for you. For example, consider an `<img>` tag with a relative `src` attribute inside `src/pages/about.astro`:
 								```html
 								<!-- ❌ Incorrect: will try and load `/about/thumbnail.png` -->
 								<img src="./thumbnail.png" />
 								```
 								Since `src/pages/about.astro` will build to `/about/index.html`, you may not have expected that image to live at `/about/thumbnail.png`. So to fix this, choose either of two options:
 								#### Option 1: Absolute URLs
 								```html
 								<!-- ✅ Correct: references public/thumbnail.png -->
 								<img src="/thumbnail.png" />
 								```
 								The recommended approach is to place files within `public/*`. This references a file it `public/thumbnail.png`, which will resolve to `/thumbnail.png` at the final build (since `public/` ends up at `/`).
 								#### Option 2: Asset import references
 								```jsx
 								---
 								//  ✅ Correct: references src/thumbnail.png
 								import thumbnailSrc from './thumbnail.png';
 								---
 								<img src={thumbnailSrc} />
 								```
 								If you’d prefer to organize assets alongside Astro components, you may import the file in JavaScript inside the component script. This works as intended but this makes `thumbnail.png` harder to reference in other parts of your app, as its final URL isn’t easily-predictable (unlike assets in `public/*`, where the final URL is guaranteed to never change).
-												Docs: add `.astro` Syntax guide (#137)

* wip: astro syntax docs

* docs: update syntax guide

* docs: add IDE note

* chore: beautify file

* docs: edits

* Update docs/syntax.md

Co-authored-by: Drew Powers <1369770+drwpow@users.noreply.github.com>

* docs: be kinder to JSX :)

* fix: spelling

* docs: clarify some code comments

Co-authored-by: Drew Powers <1369770+drwpow@users.noreply.github.com>
											
										
										
											2021-04-28 19:55:25 +00:00
+								### TODO: Composition (Slots)
-												Update vs code link (#366)

I think this is the link you wanted for the extension
											
										
										
											2021-06-09 20:10:06 +00:00
+								[code-ext]: https://marketplace.visualstudio.com/items?itemName=astro-build.astro-vscode