diff options
| author |  FredKSchott <FredKSchott@users.noreply.github.com>
| 2021-07-14 17:43:06 +0000 |
|---|---|---|
| committer |  GitHub Actions <actions@github.com>
| 2021-07-14 17:43:06 +0000 |
| commit | 1583ef173ae36eb9f325c2d163df17ea49e244a9 (patch) | |
| tree | b97a58f9e0004ffb208c4cf5db31d0c4215f9418 /docs/core-concepts | |
| parent | d40edb0b673f380c9eb9c07add3e0cd2371d9623 (diff) | |
| download | astro-1583ef173ae36eb9f325c2d163df17ea49e244a9.tar.gz astro-1583ef173ae36eb9f325c2d163df17ea49e244a9.tar.zst astro-1583ef173ae36eb9f325c2d163df17ea49e244a9.zip | |
[ci] yarn format
Diffstat (limited to 'docs/core-concepts')
| -rw-r--r-- | docs/core-concepts/astro-components.md | 23 | ||||
| -rw-r--r-- | docs/core-concepts/astro-pages.md | 8 | ||||
| -rw-r--r-- | docs/core-concepts/collections.md | 1 | ||||
| -rw-r--r-- | docs/core-concepts/component-hydration.md | 12 | ||||
| -rw-r--r-- | docs/core-concepts/layouts.md | 13 | ||||
| -rw-r--r-- | docs/core-concepts/project-structure.md | 5 |
6 files changed, 31 insertions, 31 deletions
diff --git a/docs/core-concepts/astro-components.md b/docs/core-concepts/astro-components.md index 701a27466..6b33a2cf4 100644 --- a/docs/core-concepts/astro-components.md +++ b/docs/core-concepts/astro-components.md @@ -36,7 +36,6 @@ CSS rules inside of a `<style>` tag are automatically scoped to that component. For best results, you should only have one `<style>` tag per-Astro component. This isnβt necessarily a limitation, but it will often result in better-optimized CSS in your final build. When you're working with pages, the `<style>` tag can go nested inside of your page `<head>`. For standalone components, the `<style>` tag can go at the top-level of your template. - ```html <!-- Astro Component CSS example --> <style> @@ -53,9 +52,13 @@ For best results, you should only have one `<style>` tag per-Astro component. Th <!-- Astro Page CSS example --> <html> <head> - <style>...</style> + <style> + ... + </style> </head> - <body>...</body> + <body> + ... + </body> </html> ``` @@ -102,7 +105,7 @@ import SomeComponent from './SomeComponent.astro'; </div> ``` -π You can also import and use components from other frontend frameworks like React, Svelte, and Vue. Read our guide on [Component Hydration](/core-concepts/component-hydration) to learn more. +π You can also import and use components from other frontend frameworks like React, Svelte, and Vue. Read our guide on [Component Hydration](/core-concepts/component-hydration) to learn more. ### Dynamic JSX Expressions @@ -120,6 +123,7 @@ const name = "Your name here"; <h1>Hello {name}!</h1> </div> ``` + #### Dynamic Attributes ```astro @@ -145,7 +149,6 @@ const items = ["Dog", "Cat", "Platipus"]; </ul> ``` - ### Component Props An Astro component can define and accept props. Props are available on the `Astro.props` global in your frontmatter script. @@ -201,7 +204,7 @@ Slots become even more powerful when using **named slots**. Rather than a single <div id="my-component"> <header> <!-- children with the `slot="header"` attribute will go here --> - <slot name="header" /> + <slot name="header" /> </header> <main> <!-- children without a `slot` (or with the `slot="default"`) attribute will go here --> @@ -209,7 +212,7 @@ Slots become even more powerful when using **named slots**. Rather than a single </main> <footer> <!-- children with the `slot="footer"` attribute will go here --> - <slot name="footer"> + <slot name="footer"> </footer> </div> @@ -285,7 +288,7 @@ Astro provides a `<slot />` component so that you can control where any children --- <h1>Begin</h1> <!-- slot: any given children are injected here --> -<slot /> +<slot /> <h1>End</h1> ``` @@ -294,7 +297,6 @@ Astro provides a `<slot />` component so that you can control where any children <!-- TODO: https://github.com/snowpackjs/astro/issues/360 Document Named Slots --> - ## Comparing `.astro` versus `.jsx` @@ -351,7 +353,4 @@ import thumbnailSrc from './thumbnail.png'; 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). - [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 9d6c5d9db..0aedca4bf 100644 --- a/docs/core-concepts/astro-pages.md +++ b/docs/core-concepts/astro-pages.md @@ -5,7 +5,7 @@ title: Pages **Pages** are a special type of [Astro Component](/core-concepts/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](/guides/markdown-content) for more information on writing pages with Markdown. +Astro also supports Markdown for content-heavy pages, like blog posts and documentation. See [Markdown Content](/guides/markdown-content) for more information on writing pages with Markdown. ## File-based Routing @@ -23,7 +23,7 @@ src/pages/posts/1.md -> mysite.com/posts/1 ## 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. @@ -44,7 +44,7 @@ All Astro components are responsible for returning HTML. Astro Pages return HTML ## Data Loading -Astro pages can fetch data to help generate your pages. Astro provides two different tools to pages to help you do this: **fetch()** and **top-level await.** +Astro pages can fetch data to help generate your pages. Astro provides two different tools to pages to help you do this: **fetch()** and **top-level await.** π Read our [full guide](/guides/data-fetching) on data-fetching to learn more. @@ -57,4 +57,4 @@ console.log(data); --- <!-- Output the result to the page --> <div>{JSON.stringify(data)}</div> -```
\ No newline at end of file +``` diff --git a/docs/core-concepts/collections.md b/docs/core-concepts/collections.md index d7efe509c..96da0b6a5 100644 --- a/docs/core-concepts/collections.md +++ b/docs/core-concepts/collections.md @@ -208,4 +208,3 @@ export async function createCollection() { - API Reference: [collection](/reference/api-reference#collections-api) - API Reference: [createCollection()](/reference/api-reference#createcollection) - API Reference: [Creating an RSS feed](/reference/api-reference#rss-feed) - diff --git a/docs/core-concepts/component-hydration.md b/docs/core-concepts/component-hydration.md index 4371583a1..e4d217b76 100644 --- a/docs/core-concepts/component-hydration.md +++ b/docs/core-concepts/component-hydration.md @@ -38,9 +38,9 @@ _Note: Partial hydration is sometimes called "progressive enhancement" or "progr ## Concept: Island Architecture -**Island architecture** is the idea of using partial hydration to build entire websites. Island architecture is an alternative to the popular idea of building your website into a client-side JavaScript bundle that must be shipped to the user. +**Island architecture** is the idea of using partial hydration to build entire websites. Island architecture is an alternative to the popular idea of building your website into a client-side JavaScript bundle that must be shipped to the user. -To quote Jason Miller, who [coined the phrase](https://jasonformat.com/islands-architecture/): +To quote Jason Miller, who [coined the phrase](https://jasonformat.com/islands-architecture/): > In an "islands" model, server rendering is not a bolt-on optimization aimed at improving SEO or UX. Instead, it is a fundamental part of how pages are delivered to the browser. The HTML returned in response to navigation contains a meaningful and immediately renderable representation of the content the user requested. @@ -51,8 +51,6 @@ Besides the obvious performance benefits of sending less JavaScript down to the  - - ## Hydrate Interactive Components Astro renders every component on the server **at build time**. To hydrate components on the client **at runtime**, you may use any of the following `client:*` directives. A directive is a component attribute (always with a `:`) which tells Astro how your component should be rendered. @@ -68,15 +66,19 @@ import MyReactComponent from '../components/MyReactComponent.jsx'; ``` ### `<MyComponent client:load />` + Hydrate the component on page load. ### `<MyComponent client:idle />` + Hydrate the component as soon as main thread is free (uses [requestIdleCallback()][mdn-ric]). ### `<MyComponent client:visible />` + Hydrate the component as soon as the element enters the viewport (uses [IntersectionObserver][mdn-io]). Useful for content lower down on the page. -### `<MyComponent client:media={QUERY} />` +### `<MyComponent client:media={QUERY} />` + Hydrate the component as soon as the browser matches the given media query (uses [matchMedia][mdn-mm]). Useful for sidebar toggles, or other elements that should only display on mobile or desktop devices. ## Can I Hydrate Astro Components? diff --git a/docs/core-concepts/layouts.md b/docs/core-concepts/layouts.md index 5a403b615..28bc53cf3 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](/core-concepts/astro-components) that help you share and reuse common page layouts within your project. +**Layouts** are a special type of [Component](/core-concepts/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 @@ -119,13 +117,14 @@ 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 --- title: Blog Post layout: ../layouts/PostLayout.astro --- + This blog post will be **rendered** inside of the `<PostLayout />` layout. ``` @@ -152,4 +151,4 @@ const { content } = Astro.props; </html> ``` -π Learn more about Astro's markdown support in our [Markdown guide](/guides/markdown-content). +π Learn more about Astro's markdown support in our [Markdown guide](/guides/markdown-content). diff --git a/docs/core-concepts/project-structure.md b/docs/core-concepts/project-structure.md index 4d2cd4d80..8220acf74 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](/quick-start) 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](/core-concepts/astro-pages) 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`. |