diff options
Diffstat (limited to 'docs/core-concepts')
| -rw-r--r-- | docs/core-concepts/astro-components.md | 4 | ||||
| -rw-r--r-- | docs/core-concepts/astro-pages.md | 10 | ||||
| -rw-r--r-- | docs/core-concepts/collections.md | 2 | ||||
| -rw-r--r-- | docs/core-concepts/component-hydration.md | 3 | ||||
| -rw-r--r-- | docs/core-concepts/layouts.md | 19 | ||||
| -rw-r--r-- | docs/core-concepts/project-structure.md | 5 |
6 files changed, 19 insertions, 24 deletions
diff --git a/docs/core-concepts/astro-components.md b/docs/core-concepts/astro-components.md index e6d80f976..5cf9f4911 100644 --- a/docs/core-concepts/astro-components.md +++ b/docs/core-concepts/astro-components.md @@ -3,8 +3,6 @@ layout: ~/layouts/Main.astro title: Astro Components --- - - ## ✨ `.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. @@ -204,5 +202,3 @@ If you’d prefer to organize assets alongside Astro components, you may import ### TODO: Composition (Slots) [code-ext]: https://marketplace.visualstudio.com/items?itemName=astro-build.astro-vscode - - diff --git a/docs/core-concepts/astro-pages.md b/docs/core-concepts/astro-pages.md index 283cd8867..1f63ea98b 100644 --- a/docs/core-concepts/astro-pages.md +++ b/docs/core-concepts/astro-pages.md @@ -5,7 +5,7 @@ title: Astro Pages **Pages** are a special type of [Astro Component](./astro-components) that handle routing, data loading, and templating for each page of your website. You can think of them like any other Astro component, just with extra responsibilities. -Astro also supports Markdown for content-heavy pages, like blog posts and documentation. See [Markdown Content](./markdown-content.md) for more information on writing pages with Markdown. +Astro also supports Markdown for content-heavy pages, like blog posts and documentation. See [Markdown Content](./markdown-content.md) for more information on writing pages with Markdown. ## File-based Routing @@ -37,9 +37,10 @@ console.log(data); <!-- Output the result to the page --> <div>{JSON.stringify(data)}</div> ``` + ### `fetch()` -Astro pages have access to the global `fetch()` function in their setup script. `fetch()` is a native JavaScript API ([MDN](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API/Using_Fetch)) that lets you make HTTP requests for things like APIs and resources. +Astro pages have access to the global `fetch()` function in their setup script. `fetch()` is a native JavaScript API ([MDN](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API/Using_Fetch)) that lets you make HTTP requests for things like APIs and resources. Even though Astro component scripts run inside of Node.js (and not in the browser) Astro provides this native API so that you can fetch data at page build time. @@ -49,7 +50,7 @@ Even though Astro component scripts run inside of Node.js (and not in the browse ## Page Templating -All Astro components are responsible for returning HTML. Astro Pages return HTML as well, but have the unique responsibility of returning a full `<html>...</html>` page response, including `<head>` ([MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/head)) and `<body>` ([MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/body)). +All Astro components are responsible for returning HTML. Astro Pages return HTML as well, but have the unique responsibility of returning a full `<html>...</html>` page response, including `<head>` ([MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/head)) and `<body>` ([MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/body)). `<!doctype html>` is optional, and will be added automatically. @@ -67,6 +68,3 @@ All Astro components are responsible for returning HTML. Astro Pages return HTML </body> </html> ``` - - - diff --git a/docs/core-concepts/collections.md b/docs/core-concepts/collections.md index 3bdf5c098..edebca3d7 100644 --- a/docs/core-concepts/collections.md +++ b/docs/core-concepts/collections.md @@ -11,7 +11,7 @@ title: Collections - Working with remote data - Mixing remote and local data -**Use a Collection when you need to generate multiple pages from a single template.** If you just want to generate a single page (ex: a long list of every post on your site) then you can just fetch that data on a normal Astro page without using the Collection API. +**Use a Collection when you need to generate multiple pages from a single template.** If you just want to generate a single page (ex: a long list of every post on your site) then you can just fetch that data on a normal Astro page without using the Collection API. ## Using Collections diff --git a/docs/core-concepts/component-hydration.md b/docs/core-concepts/component-hydration.md index b1dc6c8ad..ee1bdd777 100644 --- a/docs/core-concepts/component-hydration.md +++ b/docs/core-concepts/component-hydration.md @@ -22,6 +22,7 @@ However, there are plenty of cases where you might like to include an interactiv - A "Buy Now" button With Astro, you can hydrate these components individually, without forcing the rest of the page to ship any other unnecesary JavaScript. This technique is called **partial hydration.** + ## Hydrate Frontend Components To hydrate your components in the client, you may use any of the following techniques: @@ -34,4 +35,4 @@ To hydrate your components in the client, you may use any of the following techn Astro components (`.astro`) are HTML-only templating languages with no client-side runtime. You cannot hydrate an Astro component to run on the client (because the JavaScript front-matter only ever runs at build time). -If you want to make your Astro component interactive on the client, you should convert it to React, Svelte, or Vue. Otherwise, you can consider adding a `<script>` tag to your Astro component that will run JavaScript on the page. +If you want to make your Astro component interactive on the client, you should convert it to React, Svelte, or Vue. Otherwise, you can consider adding a `<script>` tag to your Astro component that will run JavaScript on the page. diff --git a/docs/core-concepts/layouts.md b/docs/core-concepts/layouts.md index 3c24373b5..73d9994fa 100644 --- a/docs/core-concepts/layouts.md +++ b/docs/core-concepts/layouts.md @@ -3,17 +3,17 @@ layout: ~/layouts/Main.astro title: Layouts --- -**Layouts** are a special type of [Component](./astro-components) that help you share and reuse common page layouts within your project. +**Layouts** are a special type of [Component](./astro-components) that help you share and reuse common page layouts within your project. Layouts are just like any other reusable Astro component. There's no new syntax or APIs to learn. However, reusable page layouts are such a common pattern in web development that we created this guide to help you use them. ## Usage -Astro layouts support props, slots, and all of the other features of Astro components. Layouts are just normal components, after all! +Astro layouts support props, slots, and all of the other features of Astro components. Layouts are just normal components, after all! Unlike other components, layouts will often contain the full page `<html>`, `<head>` and `<body>` (often referred to as the **page shell**). -It's a common pattern to put all of your layout components in a single `src/layouts` directory. +It's a common pattern to put all of your layout components in a single `src/layouts` directory. ## Example @@ -54,12 +54,10 @@ import BaseLayout from '../layouts/BaseLayout.astro' </BaseLayout> ``` - ## Nesting Layouts You can nest layouts when you want to create more specific page types without copy-pasting. It is common in Astro to have one generic `BaseLayout` and then many more specific layouts (`PostLayout`, `ProductLayout`, etc.) that reuse and build on top of it. - ```astro --- // src/layouts/PostLayout.astro @@ -93,7 +91,7 @@ const {title, description} = Astro.props; <link href="https://fonts.googleapis.com/css2?family=Spectral:ital,wght@0,400;0,700;1,400;1,700&display=swap" rel="stylesheet"> ``` -Notice how this layout doesn't include your page shell, and only includes some generic elements that should go in your `<head>`. This lets you combine multiple layout components together, to include things +Notice how this layout doesn't include your page shell, and only includes some generic elements that should go in your `<head>`. This lets you combine multiple layout components together, to include things ```astro --- @@ -119,15 +117,16 @@ The one downside to this approach is that you'll need to define the `<html>`, `< ## Markdown Layouts -Layouts are essential for Markdown files. Markdown files can declare a layout in the file frontmatter. Each Markdown file will be rendered to HTML and then injected into the layout's `<slot />` location. +Layouts are essential for Markdown files. Markdown files can declare a layout in the file frontmatter. Each Markdown file will be rendered to HTML and then injected into the layout's `<slot />` location. -````markdown +```markdown --- title: Blog Post layout: ../layouts/PostLayout.astro --- + This blog post will be **rendered** inside of the `<PostLayout />` layout. -```` +``` Markdown pages always pass a `content` prop to their layout, which is useful to grab information about the page, title, metadata, table of contents headers, and more. @@ -152,4 +151,4 @@ const { content } = Astro.props; </html> ``` -📚 Learn more about Astro's markdown support in our [Markdown guide](/docs/guides/markdown-content.md). +📚 Learn more about Astro's markdown support in our [Markdown guide](/docs/guides/markdown-content.md). diff --git a/docs/core-concepts/project-structure.md b/docs/core-concepts/project-structure.md index 28adca041..08a9b8f60 100644 --- a/docs/core-concepts/project-structure.md +++ b/docs/core-concepts/project-structure.md @@ -10,6 +10,7 @@ Astro includes an opinionated folder layout for your project. Every Astro projec - `package.json` - A project manifest. The easiest way to set up your new project is with `npm init astro`. Check out our [Installation Guide](/docs/quick-start.md) for a walkthrough of how to set up your project automatically (with `npm init astro`) or manually. + ## Project Structure ``` @@ -48,9 +49,9 @@ Your non-Astro UI components (React, Preact, Svelte, Vue, etc.) can also live in ### `src/pages` [Pages](/docs/core-concepts/astro-pages.md) contain all pages (`.astro` and `.md` supported) for your website. It is **required** that you put your pages in this directory. - + ### `public/` For most users, the majority of your files will live inside of the `src/` directory so that Astro can properly handle and optimize them in your final build. By contrast, the `public/` directory is the place for any files to live outside of the Astro build process. -If you put a file into the public folder, it will not be processed by Astro. Instead it will be copied into the build folder untouched. This can be useful for assets like images and fonts, or when you need to include a specific file like `robots.txt` or `manifest.webmanifest`.
\ No newline at end of file +If you put a file into the public folder, it will not be processed by Astro. Instead it will be copied into the build folder untouched. This can be useful for assets like images and fonts, or when you need to include a specific file like `robots.txt` or `manifest.webmanifest`. |