From f8ead78a429e80e99e6fd21535542530b2ebf772 Mon Sep 17 00:00:00 2001 From: Sarah Rainsberger Date: Thu, 2 Feb 2023 20:54:51 +0000 Subject: [PATCH 01/90] initial sidebar reorg --- src/i18n/en/nav.ts | 222 ++++++++++++++++++++++++--------------------- 1 file changed, 118 insertions(+), 104 deletions(-) diff --git a/src/i18n/en/nav.ts b/src/i18n/en/nav.ts index e01a1b58ca198..b849ea0bd47a4 100644 --- a/src/i18n/en/nav.ts +++ b/src/i18n/en/nav.ts @@ -8,114 +8,128 @@ * - Link entries MUST include `slug` (which excludes the language code) */ export default [ - { text: 'Start Here', header: true, type: 'learn', key: 'startHere' }, - { text: 'Getting Started', slug: 'getting-started', key: 'getting-started' }, - { text: 'Installation', slug: 'install/auto', key: 'install' }, - { text: 'Editor Setup', slug: 'editor-setup', key: 'editor-setup' }, - { text: 'Upgrade to v2', slug: 'guides/upgrade-to/v2', key: 'guides/upgrade-to/v2' }, - { text: 'Migrate to Astro', slug: 'guides/migrate-to-astro', key: 'guides/migrate-to-astro' }, +{ text: 'Start Here', header: true, type: 'learn', key: 'startHere' }, +{ text: 'Getting Started', slug: 'getting-started', key: 'getting-started' }, +{ text: 'Installation', slug: 'install/auto', key: 'install' }, +{ text: 'Editor Setup', slug: 'editor-setup', key: 'editor-setup' }, +{ text: 'Upgrade to v2', slug: 'guides/upgrade-to/v2', key: 'guides/upgrade-to/v2' }, - { text: 'Tutorials', header: true, type: 'learn', key: 'tutorials' }, - { text: 'Build a Blog', slug: 'tutorial/0-introduction', key: 'blog-tutorial' }, +{ text: 'Core Concepts', header: true, type: 'learn', key: 'coreConcepts' }, +{ text: 'Why Astro', slug: 'concepts/why-astro', key: 'concepts/why-astro' }, +{ text: 'MPA vs. SPA', slug: 'concepts/mpa-vs-spa', key: 'concepts/mpa-vs-spa' }, +{ text: 'Astro Islands', slug: 'concepts/islands', key: 'concepts/islands' }, - { text: 'Core Concepts', header: true, type: 'learn', key: 'coreConcepts' }, - { text: 'Why Astro', slug: 'concepts/why-astro', key: 'concepts/why-astro' }, - { text: 'MPA vs. SPA', slug: 'concepts/mpa-vs-spa', key: 'concepts/mpa-vs-spa' }, - { text: 'Astro Islands', slug: 'concepts/islands', key: 'concepts/islands' }, +{ text: 'Tutorials', header: true, type: 'learn', key: 'startHere' }, +{ text: 'Build a Blog', slug: 'tutorial/0-introduction', key: 'blog-tutorial' }, +// { text: 'Thinking with Islands', slug: 'tutorial/0-introduction', key: 'blog-tutorial' }, - { text: 'Basics', header: true, type: 'learn', key: 'basics' }, - { - text: 'Project Structure', - slug: 'core-concepts/project-structure', - key: 'core-concepts/project-structure', - }, - { - text: 'Astro Components', - slug: 'core-concepts/astro-components', - key: 'core-concepts/astro-components', - }, - { text: 'Pages', slug: 'core-concepts/astro-pages', key: 'core-concepts/astro-pages' }, - { text: 'Layouts', slug: 'core-concepts/layouts', key: 'core-concepts/layouts' }, - { text: 'Markdown & MDX', slug: 'guides/markdown-content', key: 'guides/markdown-content' }, - { text: 'Routing', slug: 'core-concepts/routing', key: 'core-concepts/routing' }, - { text: 'Imports', slug: 'guides/imports', key: 'guides/imports' }, - { text: 'Endpoints', slug: 'core-concepts/endpoints', key: 'core-concepts/endpoints' }, - { text: 'Data Fetching', slug: 'guides/data-fetching', key: 'guides/data-fetching' }, - { text: 'Deploy', slug: 'guides/deploy', key: 'guides/deploy' }, - { text: 'Troubleshooting', slug: 'guides/troubleshooting', key: 'guides/troubleshooting' }, +{ text: 'Basics', header: true, type: 'learn', key: 'basics' }, +// { text: 'The Astro CLI', slug: 'core-concepts/astro-pages', key: 'core-concepts/astro-pages' }, +{ + text: 'Project Structure', + slug: 'core-concepts/project-structure', + key: 'core-concepts/project-structure', +}, +{ + text: 'Components', + slug: 'core-concepts/astro-components', + key: 'core-concepts/astro-components', +}, +{ text: 'Pages', slug: 'core-concepts/astro-pages', key: 'core-concepts/astro-pages' }, +{ text: 'Layouts', slug: 'core-concepts/layouts', key: 'core-concepts/layouts' }, +{ text: 'Markdown & MDX', slug: 'guides/markdown-content', key: 'guides/markdown-content' }, +{ text: 'Routing', slug: 'core-concepts/routing', key: 'core-concepts/routing' }, - { text: 'Guides', header: true, type: 'learn', key: 'features' }, - { text: 'Integrations', slug: 'guides/integrations-guide', key: 'guides/integrations-guide' }, - { - text: 'UI Frameworks', - slug: 'core-concepts/framework-components', - key: 'core-concepts/framework-components', - }, - { - text: 'Scripts & Event Handling', - slug: 'guides/client-side-scripts', - key: 'guides/client-side-scripts', - }, - { text: 'CSS & Styling', slug: 'guides/styling', key: 'guides/styling' }, - { - text: 'Server-side Rendering (SSR)', - slug: 'guides/server-side-rendering', - key: 'guides/server-side-rendering', - }, - { text: 'Authoring Content', slug: 'guides/content', key: 'guides/content' }, - { - text: 'Content Collections', - slug: 'guides/content-collections', - key: 'guides/content-collections', - }, - { text: 'Connecting a CMS', slug: 'guides/cms', key: 'guides/cms' }, - { text: 'Images', slug: 'guides/images', key: 'guides/images' }, - { text: 'Fonts', slug: 'guides/fonts', key: 'guides/fonts' }, - { - text: 'Sharing State', - slug: 'core-concepts/sharing-state', - key: 'core-concepts/sharing-state', - }, - { text: 'RSS', slug: 'guides/rss', key: 'guides/rss' }, - { text: 'Testing', slug: 'guides/testing', key: 'guides/testing' }, +{ text: 'Recipes', header: true, type: 'learn', key: 'startHere' }, +{ text: 'Migrate to Astro', slug: 'guides/migrate-to-astro', key: 'guides/migrate-to-astro' }, +{ text: 'Connect a CMS', slug: 'guides/cms', key: 'guides/cms' }, +{ text: 'Add integrations', slug: 'guides/integrations-guide', key: 'guides/integrations-guide' }, +{ + text: 'Use UI frameworks', + slug: 'core-concepts/framework-components', + key: 'core-concepts/framework-components', +}, +{ text: 'Deploy your site', slug: 'guides/deploy', key: 'guides/deploy' }, +// { text: 'Test', slug: 'guides/testing', key: 'guides/testing' }, +// { text: 'All Recipes', slug: 'guides/deploy', key: 'guides/deploy' }, - { text: 'Configuration', header: true, type: 'learn', key: 'configuration' }, - { - text: 'The Astro Config File', - slug: 'guides/configuring-astro', - key: 'guides/configuring-astro', - }, - { text: 'TypeScript', slug: 'guides/typescript', key: 'guides/typescript' }, - { text: 'Import Aliases', slug: 'guides/aliases', key: 'guides/aliases' }, - { - text: 'Environment Variables', - slug: 'guides/environment-variables', - key: 'guides/environment-variables', - }, +// TODO: Can some of these be removed, merged, or pulled entirely into Recipes? (ex: RSS as recipe) +{ text: 'Guides', header: true, type: 'learn', key: 'features' }, +// { +// text: 'Astro Component Syntax', +// slug: 'core-concepts/astro-syntax', +// key: 'core-concepts/astro-syntax', +// }, - { text: 'Reference', header: true, type: 'api', key: 'reference' }, - { - text: 'Configuration', - slug: 'reference/configuration-reference', - key: 'reference/configuration-reference', - }, - { text: 'CLI', slug: 'reference/cli-reference', key: 'reference/cli-reference' }, - { text: 'Runtime API', slug: 'reference/api-reference', key: 'reference/api-reference' }, - { - text: 'Integrations API', - slug: 'reference/integrations-reference', - key: 'reference/integrations-reference', - }, - { text: 'Adapter API', slug: 'reference/adapter-reference', key: 'reference/adapter-reference' }, - { - text: 'Template Directives', - slug: 'reference/directives-reference', - key: 'reference/directives-reference', - }, - { - text: 'Error Reference', - slug: 'reference/error-reference', - key: 'reference/error-reference', - }, - { text: 'NPM Package Format', slug: 'reference/publish-to-npm', key: 'guides/publish-to-npm' }, +{ text: 'Imports', slug: 'guides/imports', key: 'guides/imports' }, +{ text: 'Endpoints', slug: 'core-concepts/endpoints', key: 'core-concepts/endpoints' }, +{ text: 'Data Fetching', slug: 'guides/data-fetching', key: 'guides/data-fetching' }, +{ + text: 'Scripts & Event Handling', + slug: 'guides/client-side-scripts', + key: 'guides/client-side-scripts', +}, +{ text: 'CSS & Styling', slug: 'guides/styling', key: 'guides/styling' }, +{ + text: 'Server-side Rendering (SSR)', + slug: 'guides/server-side-rendering', + key: 'guides/server-side-rendering', +}, +{ text: 'Authoring Content', slug: 'guides/content', key: 'guides/content' }, +{ + text: 'Content Collections', + slug: 'guides/content-collections', + key: 'guides/content-collections', +}, +// { text: 'MDX', slug: 'guides/markdown-content', key: 'guides/markdown-content' }, +{ text: 'Images', slug: 'guides/images', key: 'guides/images' }, +{ text: 'Fonts', slug: 'guides/fonts', key: 'guides/fonts' }, +{ + text: 'Sharing State', + slug: 'core-concepts/sharing-state', + key: 'core-concepts/sharing-state', +}, +{ text: 'RSS', slug: 'guides/rss', key: 'guides/rss' }, +{ text: 'Testing', slug: 'guides/testing', key: 'guides/testing' }, +{ text: 'Troubleshooting', slug: 'guides/troubleshooting', key: 'guides/troubleshooting' }, + +{ text: 'Configuration', header: true, type: 'learn', key: 'configuration' }, +{ + text: 'The Astro Config File', + slug: 'guides/configuring-astro', + key: 'guides/configuring-astro', +}, +{ text: 'TypeScript', slug: 'guides/typescript', key: 'guides/typescript' }, +{ text: 'Import Aliases', slug: 'guides/aliases', key: 'guides/aliases' }, +{ + text: 'Environment Variables', + slug: 'guides/environment-variables', + key: 'guides/environment-variables', +}, + +{ text: 'Reference', header: true, type: 'api', key: 'reference' }, +{ + text: 'Configuration', + slug: 'reference/configuration-reference', + key: 'reference/configuration-reference', +}, +{ text: 'CLI', slug: 'reference/cli-reference', key: 'reference/cli-reference' }, +{ text: 'Runtime API', slug: 'reference/api-reference', key: 'reference/api-reference' }, +{ + text: 'Integrations API', + slug: 'reference/integrations-reference', + key: 'reference/integrations-reference', +}, +{ text: 'Adapter API', slug: 'reference/adapter-reference', key: 'reference/adapter-reference' }, +{ + text: 'Template Directives', + slug: 'reference/directives-reference', + key: 'reference/directives-reference', +}, +{ + text: 'Error Reference', + slug: 'reference/error-reference', + key: 'reference/error-reference', +}, +{ text: 'NPM Package Format', slug: 'reference/publish-to-npm', key: 'guides/publish-to-npm' }, ] as const; From 596f8dbe73b022895afa557283f586fd02534a64 Mon Sep 17 00:00:00 2001 From: Sarah Rainsberger Date: Thu, 2 Feb 2023 21:09:09 +0000 Subject: [PATCH 02/90] tutorials key --- src/i18n/en/nav.ts | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/i18n/en/nav.ts b/src/i18n/en/nav.ts index b849ea0bd47a4..ae9599526fd0d 100644 --- a/src/i18n/en/nav.ts +++ b/src/i18n/en/nav.ts @@ -19,7 +19,7 @@ export default [ { text: 'MPA vs. SPA', slug: 'concepts/mpa-vs-spa', key: 'concepts/mpa-vs-spa' }, { text: 'Astro Islands', slug: 'concepts/islands', key: 'concepts/islands' }, -{ text: 'Tutorials', header: true, type: 'learn', key: 'startHere' }, +{ text: 'Tutorials', header: true, type: 'learn', key: 'tutorials' }, { text: 'Build a Blog', slug: 'tutorial/0-introduction', key: 'blog-tutorial' }, // { text: 'Thinking with Islands', slug: 'tutorial/0-introduction', key: 'blog-tutorial' }, From 66c64c3303e9eab44c63d50b8a6f3c4b0679a574 Mon Sep 17 00:00:00 2001 From: Sarah Rainsberger Date: Thu, 2 Feb 2023 23:04:32 +0000 Subject: [PATCH 03/90] new (hidden) recipes page --- src/pages/en/guides/recipes.mdx | 31 +++++++++++++++++++++++++++++++ 1 file changed, 31 insertions(+) create mode 100644 src/pages/en/guides/recipes.mdx diff --git a/src/pages/en/guides/recipes.mdx b/src/pages/en/guides/recipes.mdx new file mode 100644 index 0000000000000..76e0125fd0cfa --- /dev/null +++ b/src/pages/en/guides/recipes.mdx @@ -0,0 +1,31 @@ +--- +layout: ~/layouts/MainLayout.astro +title: All Recipes +description: See guided examples of building features in Astro. +i18nReady: false +--- +import Since from '../../../components/Since.astro'; + + +See guided examples of adding features to your Astro project. + + +## Curated Recipes + +[Add an RSS feed](/en/guides/rss/) + +[eCommerce cart flyout](/en/core-concepts/sharing-state/) + +[Use fontsource](/en/guides/fonts/#using-fontsource) + +[Add fonts with Tailwind](/en/guides/fonts/#add-fonts-with-tailwind) + +[Add a local font](/en/guides/fonts/#example) + +[Verifying a Captcha](/en/core-concepts/endpoints/#example-verifying-a-captcha) + +[Add support for importing YAML](/en/guides/imports/#example-yaml-support) + +[Create a single layout for `.md`, `.mdx` and `.astro` files](/en/core-concepts/layouts/#using-one-layout-for-md-mdx-and-astro) + +## Community Resources \ No newline at end of file From 0a85c2c1c9ff82553f86a9893da30083e966647b Mon Sep 17 00:00:00 2001 From: Sarah Rainsberger Date: Mon, 6 Feb 2023 12:00:28 +0000 Subject: [PATCH 04/90] move ui frameworks back to guides --- src/i18n/en/nav.ts | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/src/i18n/en/nav.ts b/src/i18n/en/nav.ts index ae9599526fd0d..311a6f0dfb3d0 100644 --- a/src/i18n/en/nav.ts +++ b/src/i18n/en/nav.ts @@ -44,11 +44,7 @@ export default [ { text: 'Migrate to Astro', slug: 'guides/migrate-to-astro', key: 'guides/migrate-to-astro' }, { text: 'Connect a CMS', slug: 'guides/cms', key: 'guides/cms' }, { text: 'Add integrations', slug: 'guides/integrations-guide', key: 'guides/integrations-guide' }, -{ - text: 'Use UI frameworks', - slug: 'core-concepts/framework-components', - key: 'core-concepts/framework-components', -}, + { text: 'Deploy your site', slug: 'guides/deploy', key: 'guides/deploy' }, // { text: 'Test', slug: 'guides/testing', key: 'guides/testing' }, // { text: 'All Recipes', slug: 'guides/deploy', key: 'guides/deploy' }, @@ -60,7 +56,11 @@ export default [ // slug: 'core-concepts/astro-syntax', // key: 'core-concepts/astro-syntax', // }, - +{ + text: 'UI frameworks', + slug: 'core-concepts/framework-components', + key: 'core-concepts/framework-components', +}, { text: 'Imports', slug: 'guides/imports', key: 'guides/imports' }, { text: 'Endpoints', slug: 'core-concepts/endpoints', key: 'core-concepts/endpoints' }, { text: 'Data Fetching', slug: 'guides/data-fetching', key: 'guides/data-fetching' }, From 8aba8260e460b14c35a61b2162bc6bff920eecef Mon Sep 17 00:00:00 2001 From: Sarah Rainsberger Date: Mon, 6 Feb 2023 12:33:54 +0000 Subject: [PATCH 05/90] add astro syntax hidden page --- src/i18n/en/nav.ts | 2 + src/pages/en/core-concepts/astro-syntax.mdx | 192 ++++++++++++++++++++ 2 files changed, 194 insertions(+) create mode 100644 src/pages/en/core-concepts/astro-syntax.mdx diff --git a/src/i18n/en/nav.ts b/src/i18n/en/nav.ts index 311a6f0dfb3d0..04e41310f0e8a 100644 --- a/src/i18n/en/nav.ts +++ b/src/i18n/en/nav.ts @@ -30,6 +30,7 @@ export default [ slug: 'core-concepts/project-structure', key: 'core-concepts/project-structure', }, +//This will have some content removed to go into astro syntax page { text: 'Components', slug: 'core-concepts/astro-components', @@ -51,6 +52,7 @@ export default [ // TODO: Can some of these be removed, merged, or pulled entirely into Recipes? (ex: RSS as recipe) { text: 'Guides', header: true, type: 'learn', key: 'features' }, +//This will include some stuff from current Compontents page // { // text: 'Astro Component Syntax', // slug: 'core-concepts/astro-syntax', diff --git a/src/pages/en/core-concepts/astro-syntax.mdx b/src/pages/en/core-concepts/astro-syntax.mdx new file mode 100644 index 0000000000000..10ec7edf80c75 --- /dev/null +++ b/src/pages/en/core-concepts/astro-syntax.mdx @@ -0,0 +1,192 @@ +--- +layout: ~/layouts/MainLayout.astro +title: Astro Syntax +description: An intro to the .astro component syntax. +i18nReady: false +--- + +**If you know HTML, you already know enough to write your first Astro component.** + +Astro component syntax is a superset of HTML. The syntax was [designed to feel familiar to anyone with experience writing HTML or JSX](#differences-between-astro-and-jsx), and adds support for including components and JavaScript expressions. You can spot an Astro component by its file extension: `.astro`. + + +## JSX-like Expressions + +You can define local JavaScript variables inside of the frontmatter component script within an Astro component. You can then inject these variables into the component's HTML template using JSX-like expressions! + +:::note[dynamic vs reactive] +Using this approach, you can include **dynamic** values that are calculated in the frontmatter. But once included, these values are not **reactive** and will never change. Astro components are templates that only run once, at build time. + +See below for more examples of [differences between Astro and JSX](#differences-between-astro-and-jsx). +::: + +### Variables + +Local variables can be added into the HTML using the curly braces syntax: + +```astro title="src/components/Variables.astro" "{name}" +--- +const name = "Astro"; +--- +
+

Hello {name}!

+
+``` + +### Dynamic Attributes + +Local variables can be used in curly braces to pass attribute values to both HTML elements and components: + +```astro title="src/components/DynamicAttributes.astro" "{name}" "${name}" +--- +const name = "Astro"; +--- +

Attribute expressions are supported

+ + +``` + +:::caution +HTML attributes will be converted to strings, so it is not possible to pass functions and objects to HTML elements. +For example, you can't assign an event handler to an HTML element in an Astro component: + +```astro +--- +// dont-do-this.astro +function handleClick () { + console.log("button clicked!"); +} +--- + + +``` + +Instead, use a client-side script to add the event handler, like you would in vanilla JavaScript: + +```astro +--- +// do-this-instead.astro +--- + + +``` +::: + +### Dynamic HTML + +Local variables can be used in JSX-like functions to produce dynamically-generated HTML elements: + +```astro title="src/components/DynamicHtml.astro" "{item}" +--- +const items = ["Dog", "Cat", "Platypus"]; +--- +
    + {items.map((item) => ( +
  • {item}
    • + ))} +
+``` + +Astro can conditionally display HTML using JSX logical operators and ternary expressions. + +```astro title="src/components/ConditionalHtml.astro" "visible" +--- +const visible = true; +--- +{visible &&

Show me!

} + +{visible ?

Show me!

:

Else show me!

} +``` + +### Dynamic Tags + +You can also use dynamic tags by setting a variable to an HTML tag name or a component import: + +```astro title="src/components/DynamicTags.astro" /Element|(?Hello! + +``` + +When using dynamic tags: + +- **Variable names must be capitalized.** For example, use `Element`, not `element`. Otherwise, Astro will try to render your variable name as a literal HTML tag. + +- **Hydration directives are not supported.** When using [`client:*` hydration directives](/en/core-concepts/framework-components/#hydrating-interactive-components), Astro needs to know which components to bundle for production, and the dynamic tag pattern prevents this from working. + +### Fragments & Multiple Elements + +An Astro component template can render multiple elements with no need to wrap everything in a single `
` or `<>`, unlike JavaScript or JSX. + +```astro title="src/components/RootElements.astro" +--- +// Template with multiple elements +--- +

No need to wrap elements in a single containing element.

+

Astro supports multiple root elements in a template.

+``` + +However, when using an expression to dynamically create multiple elements, you should wrap these elements inside a **fragment** as you would in JavaScript or JSX. Astro supports using either ` ` or the shorthand `<> `. + +```astro title="src/components/FragmentWrapper.astro" "<>" "" +--- +const items = ["Dog", "Cat", "Platypus"]; +--- +
    + {items.map((item) => ( + <> +
  • Red {item}
    • +
  • Blue {item}
    • +
  • Green {item}
    • + + ))} +
+``` + +Fragments can also be useful to avoid wrapper elements when adding [`set:*` directives](/en/reference/directives-reference/#sethtml), as in the following example: + +```astro title="src/components/SetHtml.astro" "Fragment" +--- +const htmlString = '

Raw HTML content

'; +--- + +``` + +### Differences between Astro and JSX + +Astro component syntax is a superset of HTML. It was designed to feel familiar to anyone with HTML or JSX experience, but there are a couple of key differences between `.astro` files and JSX. + +#### Attributes + +In Astro, you use the standard `kebab-case` format for all HTML attributes instead of the `camelCase` used in JSX. This even works for `class`, which is not supported by React. + +```jsx del={1} ins={2} title="example.astro" +
+
+``` + +#### Comments + +In Astro, you can use standard HTML comments or JavaScript-style comments. + +```astro title="example.astro" +--- +--- + +{/* JS comment syntax is also valid */} +``` + +:::caution +HTML-style comments will be included in browser DOM, while JS ones will be skipped. To leave TODO messages or other development-only explanations, you may wish to use JavaScript-style comments instead. +::: + + From 3aab63e5d7f4fa0b0743551ab3c8b12cfff14a7c Mon Sep 17 00:00:00 2001 From: Sarah Rainsberger Date: Tue, 7 Feb 2023 15:20:09 +0000 Subject: [PATCH 06/90] update recipes page --- src/pages/en/guides/recipes.mdx | 18 ++++++++++++------ 1 file changed, 12 insertions(+), 6 deletions(-) diff --git a/src/pages/en/guides/recipes.mdx b/src/pages/en/guides/recipes.mdx index 76e0125fd0cfa..9562a5bb87a19 100644 --- a/src/pages/en/guides/recipes.mdx +++ b/src/pages/en/guides/recipes.mdx @@ -12,15 +12,17 @@ See guided examples of adding features to your Astro project. ## Curated Recipes -[Add an RSS feed](/en/guides/rss/) -[eCommerce cart flyout](/en/core-concepts/sharing-state/) +{/* Existing guide pages that are to be removed from sidebar and be accessible via recipes */} + + +[Add an RSS feed](/en/guides/rss/) -[Use fontsource](/en/guides/fonts/#using-fontsource) +[Add custom fonts](/en/guides/fonts/) -[Add fonts with Tailwind](/en/guides/fonts/#add-fonts-with-tailwind) +{/* Examples taken from other larger pages; new pages to be created */ } -[Add a local font](/en/guides/fonts/#example) +[eCommerce cart flyout](/en/core-concepts/sharing-state/) [Verifying a Captcha](/en/core-concepts/endpoints/#example-verifying-a-captcha) @@ -28,4 +30,8 @@ See guided examples of adding features to your Astro project. [Create a single layout for `.md`, `.mdx` and `.astro` files](/en/core-concepts/layouts/#using-one-layout-for-md-mdx-and-astro) -## Community Resources \ No newline at end of file +[Convert an existing project to content collections](/en/guides/content-collections/#migrating-from-file-based-routing) + +## Community Resources + +Add your own here! \ No newline at end of file From dc4da7b4349b63685fd58d1cf972dfcb1e07cfa3 Mon Sep 17 00:00:00 2001 From: Sarah Rainsberger Date: Tue, 7 Feb 2023 15:31:59 +0000 Subject: [PATCH 07/90] create initial nanostores recipe page from sharing state --- src/pages/en/guides/recipes/nanostores.mdx | 693 +++++++++++++++++++++ 1 file changed, 693 insertions(+) create mode 100644 src/pages/en/guides/recipes/nanostores.mdx diff --git a/src/pages/en/guides/recipes/nanostores.mdx b/src/pages/en/guides/recipes/nanostores.mdx new file mode 100644 index 0000000000000..c173fe5ac5e73 --- /dev/null +++ b/src/pages/en/guides/recipes/nanostores.mdx @@ -0,0 +1,693 @@ +--- +layout: ~/layouts/MainLayout.astro +title: Add an eCommerce cart using Nano Stores +i18nReady: falso +--- + +import UIFrameworkTabs from '~/components/tabs/UIFrameworkTabs.astro' +import LoopingVideo from '~/components/LoopingVideo.astro' +import JavascriptFlavorTabs from '~/components/tabs/JavascriptFlavorTabs.astro' + +When building an Astro website with [islands architecture / partial hydration](/en/concepts/islands/), you may have run into this problem: **I want to share state between my components.** + +UI frameworks like React or Vue may encourage ["context" providers](https://reactjs.org/docs/context.html) for other components to consume. But when [partially hydrating components](/en/core-concepts/framework-components/#hydrating-interactive-components) within Astro or Markdown, you can't use these context wrappers. + +Astro recommends a different solution for shared client-side storage: [**Nano Stores**](https://github.com/nanostores/nanostores). + +## Why Nano Stores? + +The [Nano Stores](https://github.com/nanostores/nanostores) library allows you to author stores that any component can interact with. We recommend Nano Stores because: +- **They're lightweight.** Nano Stores ship the bare minimum JS you'll need (less than 1 KB) with zero dependencies. +- **They're framework-agnostic.** This means sharing state between frameworks will be seamless! Astro is built on flexibility, so we love solutions that offer a similar developer experience no matter your preference. + +Still, there are a number of alternatives you can explore. These include: +- [Svelte's built-in stores](https://svelte.dev/tutorial/writable-stores) +- [Solid signals](https://www.solidjs.com/docs/latest) outside of a component context +- [Vue's reactivity API](https://vuejs.org/guide/scaling-up/state-management.html#simple-state-management-with-reactivity-api) +- [Sending custom browser events](https://developer.mozilla.org/en-US/docs/Web/Events/Creating_and_triggering_events) between components + +:::note[FAQ] + +
+**🙋 Can I use Nano Stores in `.astro` files or other server-side components?** + +Nano Stores _can_ be imported, written to, and read from in server-side components, **but we don't recommend it!** This is due to a few restrictions: +- Writing to a store from a `.astro` file or [non-hydrated component](/en/core-concepts/framework-components/#hydrating-interactive-components) will _not_ affect the value received by [client-side components](/en/reference/directives-reference/#client-directives). +- You cannot pass a Nano Store as a "prop" to client-side components. +- You cannot subscribe to store changes from a `.astro` file, since Astro components do not re-render. + +If you understand these restrictions and still find a use case, you can give Nano Stores a try! Just remember that Nano Stores are built for reactivity to changes on the **client** specifically. + +
+ +
+**🙋 How do Svelte stores compare to Nano Stores?** + +**Nano Stores and [Svelte stores](https://svelte.dev/tutorial/writable-stores) are very similar!** In fact, [nanostores allow you to use the same `$` shortcut](https://github.com/nanostores/nanostores#svelte) for subscriptions that you might use with Svelte stores. + +If you want to avoid third-party libraries, [Svelte stores](https://svelte.dev/tutorial/writable-stores) are a great cross-island communication tool on their own. Still, you might prefer Nano Stores if a) you like their add-ons for ["objects"](https://github.com/nanostores/nanostores#maps) and [async state](https://github.com/nanostores/nanostores#lazy-stores), or b) you want to communicate between Svelte and other UI frameworks like Preact or Vue. +
+ +
+**🙋 How do Solid signals compare to Nano Stores?** + +If you've used Solid for a while, you may have tried moving [signals](https://www.solidjs.com/docs/latest#createsignal) or [stores](https://www.solidjs.com/docs/latest#createstore) outside of your components. This is a great way to share state between Solid islands! Try exporting signals from a shared file: + +```js +// sharedStore.js +import { createSignal } from 'solid-js'; + +export const sharedCount = createSignal(0); +``` +...and all components importing `sharedCount` will share the same state. Though this works well, you might prefer Nano Stores if a) you like their add-ons for ["objects"](https://github.com/nanostores/nanostores#maps) and [async state](https://github.com/nanostores/nanostores#lazy-stores), or b) you want to communicate between Solid and other UI frameworks like Preact or Vue. +
+::: + +## Installing Nano Stores + +To get started, install Nano Stores alongside their helper package for your favorite UI framework: + + + + ```shell + npm install nanostores @nanostores/preact + ``` + + + ```shell + npm install nanostores @nanostores/react + ``` + + + ```shell + npm install nanostores @nanostores/solid + ``` + + + ```shell + npm install nanostores + ``` + :::note + No helper package here! Nano Stores can be used like standard Svelte stores. + ::: + + + ```shell + npm install nanostores @nanostores/vue + ``` + + + +You can jump into the [Nano Stores usage guide](https://github.com/nanostores/nanostores#guide) from here, or follow along with our example below! + +## Usage example - ecommerce cart flyout + +Let's say we're building a simple ecommerce interface with three interactive elements: +- An "add to cart" submission form +- A cart flyout to display those added items +- A cart flyout toggle + + + +_[**Try the completed example**](https://github.com/withastro/astro/tree/main/examples/with-nanostores) on your machine or online via Stackblitz._ + +Your base Astro file may look like this: + +```astro +--- +// Example: src/pages/index.astro +import CartFlyoutToggle from '../components/CartFlyoutToggle'; +import CartFlyout from '../components/CartFlyout'; +import AddToCartForm from '../components/AddToCartForm'; +--- + + + +... + +
+ +
+
+ + + +
+ + + +``` + +### Using "atoms" + +Let's start by opening our `CartFlyout` whenever `CartFlyoutToggle` is clicked. + +First, create a new JS or TS file to contain our store. We'll use an ["atom"](https://github.com/nanostores/nanostores#atoms) for this: + +```js +// src/cartStore.js +import { atom } from 'nanostores'; + +export const isCartOpen = atom(false); +``` + +Now, we can import this store into any file that needs to read or write. We'll start by wiring up our `CartFlyoutToggle`: + + + +```jsx +// src/components/CartFlyoutToggle.jsx +import { useStore } from '@nanostores/preact'; +import { isCartOpen } from '../cartStore'; + +export default function CartButton() { + // read the store value with the `useStore` hook + const $isCartOpen = useStore(isCartOpen); + // write to the imported store using `.set` + return ( + + ) +} +``` + + +```jsx +// src/components/CartFlyoutToggle.jsx +import { useStore } from '@nanostores/react'; +import { isCartOpen } from '../cartStore'; + +export default function CartButton() { + // read the store value with the `useStore` hook + const $isCartOpen = useStore(isCartOpen); + // write to the imported store using `.set` + return ( + + ) +} +``` + + +```jsx +// src/components/CartFlyoutToggle.jsx +import { useStore } from '@nanostores/solid'; +import { isCartOpen } from '../cartStore'; + +export default function CartButton() { + // read the store value with the `useStore` hook + const $isCartOpen = useStore(isCartOpen); + // write to the imported store using `.set` + return ( + + ) +} +``` + + +```svelte + + + + + +``` + + +```vue + + + + +``` + + + +Then, we can read `isCartOpen` from our `CartFlyout` component: + + + +```jsx +// src/components/CartFlyout.jsx +import { useStore } from '@nanostores/preact'; +import { isCartOpen } from '../cartStore'; + +export default function CartFlyout() { + const $isCartOpen = useStore(isCartOpen); + + return $isCartOpen ? : null; +} +``` + + +```jsx +// src/components/CartFlyout.jsx +import { useStore } from '@nanostores/react'; +import { isCartOpen } from '../cartStore'; + +export default function CartFlyout() { + const $isCartOpen = useStore(isCartOpen); + + return $isCartOpen ? : null; +} +``` + + +```jsx +// src/components/CartFlyout.jsx +import { useStore } from '@nanostores/solid'; +import { isCartOpen } from '../cartStore'; + +export default function CartFlyout() { + const $isCartOpen = useStore(isCartOpen); + + return $isCartOpen() ? : null; +} +``` + + +```svelte + + + +{#if $isCartOpen} + +{/if} +``` + + +```vue + + + + +``` + + + +### Using "maps" + +:::tip +**[Maps](https://github.com/nanostores/nanostores#maps) are a great choice for objects you write to regularly!** Alongside the standard `get()` and `set()` helpers an `atom` provides, you'll also have a `.setKey()` function to efficiently update individual object keys. +::: + +Now, let's keep track of the items inside your cart. To avoid duplicates and keep track of "quantity," we can store your cart as an object with the item's ID as a key. We'll use a [Map](https://github.com/nanostores/nanostores#maps) for this. + +Let's add a `cartItem` store to our `cartStore.js` from earlier. You can also switch to a TypeScript file to define the shape if you're so inclined. + + + + ```js + // src/cartStore.js + import { atom, map } from 'nanostores'; + + export const isCartOpen = atom(false); + + /** + * @typedef {Object} CartItem + * @property {string} id + * @property {string} name + * @property {string} imageSrc + * @property {number} quantity + */ + + /** @type {import('nanostores').MapStore>} */ + export const cartItems = map({}); + + ``` + + + ```ts + // src/cartStore.ts + import { atom, map } from 'nanostores'; + + export const isCartOpen = atom(false); + + export type CartItem = { + id: string; + name: string; + imageSrc: string; + quantity: number; + } + + export const cartItems = map>({}); + ``` + + + +Now, let's export an `addCartItem` helper for our components to use. +- **If that item doesn't exist in your cart**, add the item with a starting quantity of 1. +- **If that item _does_ already exist**, bump the quantity by 1. + + + + ```js + // src/cartStore.js + ... + export function addCartItem({ id, name, imageSrc }) { + const existingEntry = cartItems.get()[id]; + if (existingEntry) { + cartItems.setKey(id, { + ...existingEntry, + quantity: existingEntry.quantity + 1, + }) + } else { + cartItems.setKey( + id, + { id, name, imageSrc, quantity: 1 } + ); + } + } + ``` + + + ```ts + // src/cartStore.ts + ... + type ItemDisplayInfo = Pick; + export function addCartItem({ id, name, imageSrc }: ItemDisplayInfo) { + const existingEntry = cartItems.get()[id]; + if (existingEntry) { + cartItems.setKey(id, { + ...existingEntry, + quantity: existingEntry.quantity + 1, + }); + } else { + cartItems.setKey( + id, + { id, name, imageSrc, quantity: 1 } + ); + } + } + ``` + + + +:::note +
+ +**🙋 Why use `.get()` here instead of a `useStore` helper?** + +You may have noticed we're calling `cartItems.get()` here, instead of grabbing that `useStore` helper from our React / Preact / Solid / Vue examples. This is because **useStore is meant to trigger component re-renders.** In other words, `useStore` should be used whenever the store value is being rendered to the UI. Since we're reading the value when an **event** is triggered (`addToCart` in this case), and we aren't trying to render that value, we don't need `useStore` here. +
+::: + +With our store in place, we can call this function inside our `AddToCartForm` whenever that form is submitted. We'll also open the cart flyout so you can see a full cart summary. + + + +```jsx +// src/components/AddToCartForm.jsx +import { addCartItem, isCartOpen } from '../cartStore'; + +export default function AddToCartForm({ children }) { + // we'll hardcode the item info for simplicity! + const hardcodedItemInfo = { + id: 'astronaut-figurine', + name: 'Astronaut Figurine', + imageSrc: '/images/astronaut-figurine.png', + } + + function addToCart(e) { + e.preventDefault(); + isCartOpen.set(true); + addCartItem(hardcodedItemInfo); + } + + return ( +
+ {children} +
+ ) +} +``` + + +```jsx +// src/components/AddToCartForm.jsx +import { addCartItem, isCartOpen } from '../cartStore'; + +export default function AddToCartForm({ children }) { + // we'll hardcode the item info for simplicity! + const hardcodedItemInfo = { + id: 'astronaut-figurine', + name: 'Astronaut Figurine', + imageSrc: '/images/astronaut-figurine.png', + } + + function addToCart(e) { + e.preventDefault(); + isCartOpen.set(true); + addCartItem(hardcodedItemInfo); + } + + return ( +
+ {children} +
+ ) +} +``` + + +```jsx +// src/components/AddToCartForm.jsx +import { addCartItem, isCartOpen } from '../cartStore'; + +export default function AddToCartForm({ children }) { + // we'll hardcode the item info for simplicity! + const hardcodedItemInfo = { + id: 'astronaut-figurine', + name: 'Astronaut Figurine', + imageSrc: '/images/astronaut-figurine.png', + } + + function addToCart(e) { + e.preventDefault(); + isCartOpen.set(true); + addCartItem(hardcodedItemInfo); + } + + return ( +
+ {children} +
+ ) +} +``` + + +```svelte + +
+ +
+ + +``` + + +```vue + + + + +``` + + + +Finally, we'll render those cart items inside our `CartFlyout`: + + + +```jsx +// src/components/CartFlyout.jsx +import { useStore } from '@nanostores/preact'; +import { isCartOpen, cartItems } from '../cartStore'; + +export default function CartFlyout() { + const $isCartOpen = useStore(isCartOpen); + const $cartItems = useStore(cartItems); + + return $isCartOpen ? ( + + ) : null; +} +``` + + +```jsx +// src/components/CartFlyout.jsx +import { useStore } from '@nanostores/react'; +import { isCartOpen, cartItems } from '../cartStore'; + +export default function CartFlyout() { + const $isCartOpen = useStore(isCartOpen); + const $cartItems = useStore(cartItems); + + return $isCartOpen ? ( + + ) : null; +} +``` + + +```jsx +// src/components/CartFlyout.jsx +import { useStore } from '@nanostores/solid'; +import { isCartOpen, cartItems } from '../cartStore'; + +export default function CartFlyout() { + const $isCartOpen = useStore(isCartOpen); + const $cartItems = useStore(cartItems); + + return $isCartOpen() ? ( + + ) : null; +} +``` + + +```svelte + + + +{#if $isCartOpen} + {#if Object.values($cartItems).length} + + {#else} +

Your cart is empty!

+ {/if} +{/if} +``` + + +```vue + + + + +``` + + + +Now, you should have a fully interactive ecommerce example with the smallest JS bundle in the galaxy 🚀 + +[**Try the completed example**](https://github.com/withastro/astro/tree/main/examples/with-nanostores) on your machine or online via Stackblitz! From 3620c7d366e814bbbc64065a59c8144c139ec6dc Mon Sep 17 00:00:00 2001 From: Chris Swithinbank Date: Fri, 17 Feb 2023 00:11:23 +0100 Subject: [PATCH 08/90] Update pages for content collections --- src/{pages => content/docs}/en/core-concepts/astro-syntax.mdx | 1 - src/{pages => content/docs}/en/guides/recipes.mdx | 4 +--- src/{pages => content/docs}/en/guides/recipes/nanostores.mdx | 1 - 3 files changed, 1 insertion(+), 5 deletions(-) rename src/{pages => content/docs}/en/core-concepts/astro-syntax.mdx (99%) rename src/{pages => content/docs}/en/guides/recipes.mdx (89%) rename src/{pages => content/docs}/en/guides/recipes/nanostores.mdx (99%) diff --git a/src/pages/en/core-concepts/astro-syntax.mdx b/src/content/docs/en/core-concepts/astro-syntax.mdx similarity index 99% rename from src/pages/en/core-concepts/astro-syntax.mdx rename to src/content/docs/en/core-concepts/astro-syntax.mdx index 10ec7edf80c75..a3ff231038d7a 100644 --- a/src/pages/en/core-concepts/astro-syntax.mdx +++ b/src/content/docs/en/core-concepts/astro-syntax.mdx @@ -1,5 +1,4 @@ --- -layout: ~/layouts/MainLayout.astro title: Astro Syntax description: An intro to the .astro component syntax. i18nReady: false diff --git a/src/pages/en/guides/recipes.mdx b/src/content/docs/en/guides/recipes.mdx similarity index 89% rename from src/pages/en/guides/recipes.mdx rename to src/content/docs/en/guides/recipes.mdx index 9562a5bb87a19..b0967d86a3381 100644 --- a/src/pages/en/guides/recipes.mdx +++ b/src/content/docs/en/guides/recipes.mdx @@ -1,10 +1,8 @@ --- -layout: ~/layouts/MainLayout.astro title: All Recipes description: See guided examples of building features in Astro. i18nReady: false --- -import Since from '../../../components/Since.astro'; See guided examples of adding features to your Astro project. @@ -34,4 +32,4 @@ See guided examples of adding features to your Astro project. ## Community Resources -Add your own here! \ No newline at end of file +Add your own here! diff --git a/src/pages/en/guides/recipes/nanostores.mdx b/src/content/docs/en/guides/recipes/nanostores.mdx similarity index 99% rename from src/pages/en/guides/recipes/nanostores.mdx rename to src/content/docs/en/guides/recipes/nanostores.mdx index c173fe5ac5e73..7087f6cc03ddd 100644 --- a/src/pages/en/guides/recipes/nanostores.mdx +++ b/src/content/docs/en/guides/recipes/nanostores.mdx @@ -1,5 +1,4 @@ --- -layout: ~/layouts/MainLayout.astro title: Add an eCommerce cart using Nano Stores i18nReady: falso --- From 238d15282aaef6e0517c5f555e6fb18a6ec3b989 Mon Sep 17 00:00:00 2001 From: Sarah Rainsberger Date: Fri, 17 Feb 2023 02:33:12 +0000 Subject: [PATCH 09/90] falso -> false --- src/content/docs/en/guides/recipes/nanostores.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/content/docs/en/guides/recipes/nanostores.mdx b/src/content/docs/en/guides/recipes/nanostores.mdx index 7087f6cc03ddd..64225ca690a82 100644 --- a/src/content/docs/en/guides/recipes/nanostores.mdx +++ b/src/content/docs/en/guides/recipes/nanostores.mdx @@ -1,6 +1,6 @@ --- title: Add an eCommerce cart using Nano Stores -i18nReady: falso +i18nReady: false --- import UIFrameworkTabs from '~/components/tabs/UIFrameworkTabs.astro' From 73cf55da9207b745366f1e1104bdc373a7b1f05a Mon Sep 17 00:00:00 2001 From: Sarah Rainsberger Date: Fri, 17 Feb 2023 22:43:15 +0000 Subject: [PATCH 10/90] new captcha recipe pulled from endpoints --- .../docs/en/core-concepts/endpoints.mdx | 62 +----------------- src/content/docs/en/guides/recipes.mdx | 2 +- .../docs/en/guides/recipes/captcha.mdx | 65 +++++++++++++++++++ src/i18n/en/nav.ts | 12 ++-- 4 files changed, 72 insertions(+), 69 deletions(-) create mode 100644 src/content/docs/en/guides/recipes/captcha.mdx diff --git a/src/content/docs/en/core-concepts/endpoints.mdx b/src/content/docs/en/core-concepts/endpoints.mdx index a184c183ae475..70d93c2f6ba1b 100644 --- a/src/content/docs/en/core-concepts/endpoints.mdx +++ b/src/content/docs/en/core-concepts/endpoints.mdx @@ -210,64 +210,4 @@ export async function get({ params, redirect }) { } ``` -### Example: Verifying a captcha -Server endpoints can be used as REST API endpoints to run functions such as authentications, database access, and verifications without exposing sensitive data to the client. - -In the example below, an API route is used to verify Google reCAPTCHA v3 without exposing the secret to clients. - -On the server, we define a post method that accepts recaptcha data, then verifies it with reCAPTCHA's API. Here, we can safely define secret values or read environment variables. - -```js title="src/pages/recaptcha.js" -export async function post({ request }) { - const data = await request.json(); - - const recaptchaURL = 'https://www.google.com/recaptcha/api/siteverify'; - const requestBody = { - secret: "YOUR_SITE_SECRET_KEY", // This can be an environment variable - response: data.recaptcha // The token passed in from the client - }; - - const response = await fetch(recaptchaURL, { - method: "POST", - body: JSON.stringify(requestBody) - }); - - const responseData = await response.json(); - - return new Response(JSON.stringify(responseData), { status: 200 }); -} -``` - -Then, we access our endpoint using `fetch` from a client script: - -```astro title="src/pages/index.astro" - - - - - - - - - - - -``` +See an example of [verifying a captcha](/en/guides/recipes/captcha/) diff --git a/src/content/docs/en/guides/recipes.mdx b/src/content/docs/en/guides/recipes.mdx index b0967d86a3381..d94946dc879e7 100644 --- a/src/content/docs/en/guides/recipes.mdx +++ b/src/content/docs/en/guides/recipes.mdx @@ -22,7 +22,7 @@ See guided examples of adding features to your Astro project. [eCommerce cart flyout](/en/core-concepts/sharing-state/) -[Verifying a Captcha](/en/core-concepts/endpoints/#example-verifying-a-captcha) +[Verify a Captcha](/en/guides/recipes/captcha/) [Add support for importing YAML](/en/guides/imports/#example-yaml-support) diff --git a/src/content/docs/en/guides/recipes/captcha.mdx b/src/content/docs/en/guides/recipes/captcha.mdx new file mode 100644 index 0000000000000..425c16fb4a74f --- /dev/null +++ b/src/content/docs/en/guides/recipes/captcha.mdx @@ -0,0 +1,65 @@ +--- +title: Verifying a Captcha +i18nReady: false +--- + +[Server endpoints](/en/core-concepts/endpoints/#server-endpoints-api-routes) can be used as REST API endpoints to run functions such as authentications, database access, and verifications without exposing sensitive data to the client. + +In the example below, an API route is used to verify Google reCAPTCHA v3 without exposing the secret to clients. + +On the server, we define a post method that accepts recaptcha data, then verifies it with reCAPTCHA's API. Here, we can safely define secret values or read environment variables. + +```js title="src/pages/recaptcha.js" +export async function post({ request }) { + const data = await request.json(); + + const recaptchaURL = 'https://www.google.com/recaptcha/api/siteverify'; + const requestBody = { + secret: "YOUR_SITE_SECRET_KEY", // This can be an environment variable + response: data.recaptcha // The token passed in from the client + }; + + const response = await fetch(recaptchaURL, { + method: "POST", + body: JSON.stringify(requestBody) + }); + + const responseData = await response.json(); + + return new Response(JSON.stringify(responseData), { status: 200 }); +} +``` + +Then, we access our endpoint using `fetch` from a client script: + +```astro title="src/pages/index.astro" + + + + + + + + + + + +``` diff --git a/src/i18n/en/nav.ts b/src/i18n/en/nav.ts index 04e41310f0e8a..841e3ca54c2c1 100644 --- a/src/i18n/en/nav.ts +++ b/src/i18n/en/nav.ts @@ -30,7 +30,6 @@ export default [ slug: 'core-concepts/project-structure', key: 'core-concepts/project-structure', }, -//This will have some content removed to go into astro syntax page { text: 'Components', slug: 'core-concepts/astro-components', @@ -45,10 +44,9 @@ export default [ { text: 'Migrate to Astro', slug: 'guides/migrate-to-astro', key: 'guides/migrate-to-astro' }, { text: 'Connect a CMS', slug: 'guides/cms', key: 'guides/cms' }, { text: 'Add integrations', slug: 'guides/integrations-guide', key: 'guides/integrations-guide' }, - { text: 'Deploy your site', slug: 'guides/deploy', key: 'guides/deploy' }, -// { text: 'Test', slug: 'guides/testing', key: 'guides/testing' }, -// { text: 'All Recipes', slug: 'guides/deploy', key: 'guides/deploy' }, +{ text: 'All Recipes', slug: 'guides/recipes', key: 'guides/recipes' }, + // TODO: Can some of these be removed, merged, or pulled entirely into Recipes? (ex: RSS as recipe) { text: 'Guides', header: true, type: 'learn', key: 'features' }, @@ -77,7 +75,7 @@ export default [ slug: 'guides/server-side-rendering', key: 'guides/server-side-rendering', }, -{ text: 'Authoring Content', slug: 'guides/content', key: 'guides/content' }, +// { text: 'Authoring Content', slug: 'guides/content', key: 'guides/content' }, { text: 'Content Collections', slug: 'guides/content-collections', @@ -85,13 +83,13 @@ export default [ }, // { text: 'MDX', slug: 'guides/markdown-content', key: 'guides/markdown-content' }, { text: 'Images', slug: 'guides/images', key: 'guides/images' }, -{ text: 'Fonts', slug: 'guides/fonts', key: 'guides/fonts' }, +// { text: 'Fonts', slug: 'guides/fonts', key: 'guides/fonts' }, { text: 'Sharing State', slug: 'core-concepts/sharing-state', key: 'core-concepts/sharing-state', }, -{ text: 'RSS', slug: 'guides/rss', key: 'guides/rss' }, +// { text: 'RSS', slug: 'guides/rss', key: 'guides/rss' }, { text: 'Testing', slug: 'guides/testing', key: 'guides/testing' }, { text: 'Troubleshooting', slug: 'guides/troubleshooting', key: 'guides/troubleshooting' }, From 57329db9d1a68517b34c1530d784081ebbcc0ae8 Mon Sep 17 00:00:00 2001 From: Sarah Rainsberger Date: Sat, 18 Feb 2023 00:17:09 +0000 Subject: [PATCH 11/90] add yaml support recipe --- src/content/docs/en/guides/imports.mdx | 29 ----------------- src/content/docs/en/guides/recipes.mdx | 6 ++-- .../en/guides/recipes/add-yaml-support.mdx | 32 +++++++++++++++++++ src/i18n/en/nav.ts | 6 +--- 4 files changed, 35 insertions(+), 38 deletions(-) create mode 100644 src/content/docs/en/guides/recipes/add-yaml-support.mdx diff --git a/src/content/docs/en/guides/imports.mdx b/src/content/docs/en/guides/imports.mdx index d60a52af67adf..141c7c1ea299c 100644 --- a/src/content/docs/en/guides/imports.mdx +++ b/src/content/docs/en/guides/imports.mdx @@ -237,32 +237,3 @@ With **Vite** and compatible **Rollup** plugins, you can import file types which Refer to your plugin's documentation for configuration options, and how to correctly install it. ::: -### Example: YAML support - -The YAML (`.yml`) data format isn't natively supported by Astro, but you can add support for it by using a compatible Rollup plugin like [`@rollup/plugin-yaml`](https://www.npmjs.com/package/@rollup/plugin-yaml): - -1. Install `@rollup/plugin-yaml`: - - ```bash - npm install @rollup/plugin-yaml --save-dev - ``` - -2. Import the plugin in your `astro.config.mjs` and add it to the Vite plugins array: - - ```js title="astro.config.mjs" ins={2,5-7} - import { defineConfig } from 'astro/config'; - import yaml from '@rollup/plugin-yaml'; - - export default defineConfig({ - vite: { - plugins: [yaml()] - } - }); - ``` - - -3. Finally, you can import YAML data using an `import` statement: - - ```js - import yml from './data.yml'; - ``` diff --git a/src/content/docs/en/guides/recipes.mdx b/src/content/docs/en/guides/recipes.mdx index d94946dc879e7..c816702e22544 100644 --- a/src/content/docs/en/guides/recipes.mdx +++ b/src/content/docs/en/guides/recipes.mdx @@ -20,13 +20,11 @@ See guided examples of adding features to your Astro project. {/* Examples taken from other larger pages; new pages to be created */ } -[eCommerce cart flyout](/en/core-concepts/sharing-state/) +[Build an eCommerce cart flyout with nanostores](/en/guides/recipes/nanostores/) [Verify a Captcha](/en/guides/recipes/captcha/) -[Add support for importing YAML](/en/guides/imports/#example-yaml-support) - -[Create a single layout for `.md`, `.mdx` and `.astro` files](/en/core-concepts/layouts/#using-one-layout-for-md-mdx-and-astro) +[Add support for importing YAML](/en/guides/recipes/add-yaml-support/) [Convert an existing project to content collections](/en/guides/content-collections/#migrating-from-file-based-routing) diff --git a/src/content/docs/en/guides/recipes/add-yaml-support.mdx b/src/content/docs/en/guides/recipes/add-yaml-support.mdx new file mode 100644 index 0000000000000..ad25748caf0a3 --- /dev/null +++ b/src/content/docs/en/guides/recipes/add-yaml-support.mdx @@ -0,0 +1,32 @@ +--- +title: Add YAML Support +i18nReady: false +--- + +The YAML (`.yml`) data format isn't natively supported by Astro, but you can add support for it by using a compatible Rollup plugin like [`@rollup/plugin-yaml`](https://www.npmjs.com/package/@rollup/plugin-yaml): + +1. Install `@rollup/plugin-yaml`: + + ```bash + npm install @rollup/plugin-yaml --save-dev + ``` + +2. Import the plugin in your `astro.config.mjs` and add it to the Vite plugins array: + + ```js title="astro.config.mjs" ins={2,5-7} + import { defineConfig } from 'astro/config'; + import yaml from '@rollup/plugin-yaml'; + + export default defineConfig({ + vite: { + plugins: [yaml()] + } + }); + ``` + + +3. Finally, you can import YAML data using an `import` statement: + + ```js + import yml from './data.yml'; + ``` diff --git a/src/i18n/en/nav.ts b/src/i18n/en/nav.ts index 841e3ca54c2c1..def8dac045c9d 100644 --- a/src/i18n/en/nav.ts +++ b/src/i18n/en/nav.ts @@ -84,11 +84,7 @@ export default [ // { text: 'MDX', slug: 'guides/markdown-content', key: 'guides/markdown-content' }, { text: 'Images', slug: 'guides/images', key: 'guides/images' }, // { text: 'Fonts', slug: 'guides/fonts', key: 'guides/fonts' }, -{ - text: 'Sharing State', - slug: 'core-concepts/sharing-state', - key: 'core-concepts/sharing-state', -}, +// { text: 'Sharing State', slug: 'core-concepts/sharing-state', key: 'core-concepts/sharing-state' }, // { text: 'RSS', slug: 'guides/rss', key: 'guides/rss' }, { text: 'Testing', slug: 'guides/testing', key: 'guides/testing' }, { text: 'Troubleshooting', slug: 'guides/troubleshooting', key: 'guides/troubleshooting' }, From 93a67cbb53137bf39211c3fd230bfbb71d187285 Mon Sep 17 00:00:00 2001 From: Sarah Rainsberger Date: Sat, 18 Feb 2023 00:45:29 +0000 Subject: [PATCH 12/90] move some component content out --- .../en/core-concepts/astro-components.mdx | 55 +------------------ .../docs/en/guides/client-side-scripts.mdx | 26 +++++++++ src/content/docs/en/guides/recipes.mdx | 4 -- src/i18n/en/nav.ts | 39 +++++++------ 4 files changed, 48 insertions(+), 76 deletions(-) diff --git a/src/content/docs/en/core-concepts/astro-components.mdx b/src/content/docs/en/core-concepts/astro-components.mdx index a53292a93a65f..9b8378ea1b7b8 100644 --- a/src/content/docs/en/core-concepts/astro-components.mdx +++ b/src/content/docs/en/core-concepts/astro-components.mdx @@ -450,57 +450,6 @@ const { title } = Astro.props
``` -## CSS Styles - -CSS ` - -

Hello, world!

-``` - -:::caution -The styles defined here apply only to content written directly in the component's own component template. Children, and any imported components will **not** be styled by default. -::: - -📚 See our [Styling Guide](/en/guides/styling/) for more information on applying styles. - -## Client-Side Scripts - -Astro components support adding client-side interactivity using standard HTML ` -``` - -By default, Astro processes and bundles ` +``` + +By default, Astro processes and bundles ` -``` -::: - -### Dynamic HTML - -Local variables can be used in JSX-like functions to produce dynamically-generated HTML elements: - -```astro title="src/components/DynamicHtml.astro" "{item}" ---- -const items = ["Dog", "Cat", "Platypus"]; ---- -
    - {items.map((item) => ( -
  • {item}
    • - ))} -
-``` - -Astro can conditionally display HTML using JSX logical operators and ternary expressions. - -```astro title="src/components/ConditionalHtml.astro" "visible" ---- -const visible = true; ---- -{visible &&

Show me!

} - -{visible ?

Show me!

:

Else show me!

} -``` - -### Dynamic Tags - -You can also use dynamic tags by setting a variable to an HTML tag name or a component import: - -```astro title="src/components/DynamicTags.astro" /Element|(?Hello! - -``` - -When using dynamic tags: - -- **Variable names must be capitalized.** For example, use `Element`, not `element`. Otherwise, Astro will try to render your variable name as a literal HTML tag. - -- **Hydration directives are not supported.** When using [`client:*` hydration directives](/en/core-concepts/framework-components/#hydrating-interactive-components), Astro needs to know which components to bundle for production, and the dynamic tag pattern prevents this from working. - -### Fragments & Multiple Elements - -An Astro component template can render multiple elements with no need to wrap everything in a single `
` or `<>`, unlike JavaScript or JSX. - -```astro title="src/components/RootElements.astro" ---- -// Template with multiple elements ---- -

No need to wrap elements in a single containing element.

-

Astro supports multiple root elements in a template.

-``` - -However, when using an expression to dynamically create multiple elements, you should wrap these elements inside a **fragment** as you would in JavaScript or JSX. Astro supports using either ` ` or the shorthand `<> `. - -```astro title="src/components/FragmentWrapper.astro" "<>" "" ---- -const items = ["Dog", "Cat", "Platypus"]; ---- -
    - {items.map((item) => ( - <> -
  • Red {item}
    • -
  • Blue {item}
    • -
  • Green {item}
    • - - ))} -
-``` - -Fragments can also be useful to avoid wrapper elements when adding [`set:*` directives](/en/reference/directives-reference/#sethtml), as in the following example: - -```astro title="src/components/SetHtml.astro" "Fragment" ---- -const htmlString = '

Raw HTML content

'; ---- - -``` - -### Differences between Astro and JSX - -Astro component syntax is a superset of HTML. It was designed to feel familiar to anyone with HTML or JSX experience, but there are a couple of key differences between `.astro` files and JSX. - -#### Attributes - -In Astro, you use the standard `kebab-case` format for all HTML attributes instead of the `camelCase` used in JSX. This even works for `class`, which is not supported by React. - -```jsx del={1} ins={2} title="example.astro" -
-
-``` - -#### Comments - -In Astro, you can use standard HTML comments or JavaScript-style comments. - -```astro title="example.astro" ---- ---- - -{/* JS comment syntax is also valid */} -``` - -:::caution -HTML-style comments will be included in browser DOM, while JS ones will be skipped. To leave TODO messages or other development-only explanations, you may wish to use JavaScript-style comments instead. -::: ## Component Props @@ -313,7 +132,6 @@ const name = "Astro"

I hope you have a wonderful day!

``` - You can also define your props with TypeScript with a `Props` type interface. Astro will automatically pick up the `Props` interface in your frontmatter and give type warnings/errors. These props can also be given default values when destructured from `Astro.props`. ```astro ins={3-6} From 8a9800fed679a37a6d2c6e5fd7058a6ecbfd162d Mon Sep 17 00:00:00 2001 From: Sarah Rainsberger Date: Sat, 18 Feb 2023 01:43:35 +0000 Subject: [PATCH 14/90] some simplifying/editing edits to routing --- src/content/docs/en/core-concepts/routing.mdx | 32 +++++++++---------- 1 file changed, 16 insertions(+), 16 deletions(-) diff --git a/src/content/docs/en/core-concepts/routing.mdx b/src/content/docs/en/core-concepts/routing.mdx index 58783501a12c3..e05334446050b 100644 --- a/src/content/docs/en/core-concepts/routing.mdx +++ b/src/content/docs/en/core-concepts/routing.mdx @@ -5,11 +5,19 @@ i18nReady: true --- import FileTree from '~/components/FileTree.astro' -Astro uses **file-based routing** to generate your build URLs based on the file layout of your project `src/pages/` directory. When a file is added to the `src/pages` directory of your project, it is automatically available as a route based on its filename. +Astro uses **file-based routing** to generate your build URLs based on the file layout of your project `src/pages/` directory. + +## Navigating between pages + +Astro uses standard HTML [`` elements](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/a) to navigate between routes. There is no framework-specific `` component provided. + +```astro title="src/pages/index.astro" +

Read more about Astro!

+``` ## Static routes -Astro Components (`.astro`) and Markdown Files (`.md`) in the `src/pages` directory **automatically become pages on your website**. Each page’s route corresponds to its path and filename within the `src/pages` directory. +`.astro` [page components](/en/core-concepts/astro-pages/) as well as Markdown and MDX Files (`.md`, `.mdx`) within the `src/pages/` directory **automatically become pages on your website**. Each page’s route corresponds to its path and filename within the `src/pages/` directory. ```diff # Example: Static routes @@ -21,20 +29,12 @@ src/pages/posts/1.md -> mysite.com/posts/1 ``` :::tip -There is no separate "routing config" to maintain in an Astro project! When you add a file to the `/src/pages` directory, a new route is automatically created for you. In static builds, you can customize the file output format using the [`build.format`](/en/reference/configuration-reference/#buildformat) configuration option. +There is no separate "routing config" to maintain in an Astro project! When you add a file to the `src/pages/` directory, a new route is automatically created for you. In static builds, you can customize the file output format using the [`build.format`](/en/reference/configuration-reference/#buildformat) configuration option. ::: -## Navigating between pages - -Astro uses standard HTML [`` elements](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/a) to navigate between routes. There is no framework-specific `` component provided. - -```astro title="src/pages/index.astro" -

Read more about Astro!

-``` - ## Dynamic routes -An Astro page file can specify dynamic route parameters in its filename to generate matching pages. For example, you might create an `authors/[author].astro` file that generates a bio page for every author on your blog. `author` becomes a _parameter_ that you can access from inside the page. +An Astro page file can specify dynamic route parameters in its filename to generate multiple, matching pages. For example, `src/pages/authors/[author].astro` generates a bio page for every author on your blog. `author` becomes a _parameter_ that you can access from inside the page. In Astro's default static output mode, these pages are generated at build time, and so you must predetermine the list of `author`s that get a corresponding file. In SSR mode, a page will be generated on request for any route that matches. @@ -79,7 +79,7 @@ const { lang, version } = Astro.params; This will generate `/en-v1/info` and `/fr-v2/info`. -Parameters can be included in separate parts of the path, so we could use `src/pages/[lang]/[version]/info.astro` with the same `getStaticPaths` to generate `/en/v1/info` and `/fr/v2/info`. +Parameters can be included in separate parts of the path. For example, the file `src/pages/[lang]/[version]/info.astro` with the same `getStaticPaths()` above will generate the routes `/en/v1/info` and `/fr/v2/info`. 📚 Learn more about [`getStaticPaths()`](/en/reference/api-reference/#getstaticpaths). @@ -104,7 +104,7 @@ const { path } = Astro.params; This will generate `/sequences/one/two/three`, `/sequences/four`, and `/sequences`. (Setting the rest parameter to `undefined` allows it to match the top level page.) -Rest parameters can be used with **other named parameters**. For example, we could represent GitHub's file viewer with a dynamic route like this: +Rest parameters can be used with **other named parameters**. For example, GitHub's file viewer can be represented with the following dynamic route: ``` /[org]/[repo]/tree/[branch]/[...file] @@ -122,7 +122,7 @@ In this example, a request for `/withastro/astro/tree/main/docs/public/favicon.s #### Example: Dynamic pages at multiple levels -Here, we use a rest parameter (`[...slug]`) and the [`props`](/en/reference/api-reference/#data-passing-with-props) feature of `getStaticPaths()` to generate pages for slugs of different depths. +In the following example, a rest parameter (`[...slug]`) and the [`props`](/en/reference/api-reference/#data-passing-with-props) feature of `getStaticPaths()` generate pages for slugs of different depths. ```astro title="src/pages/[...slug].astro" --- @@ -178,7 +178,7 @@ This page will be served for any value of `resource` and `id`: `resources/users/ #### Modifying the `[...slug]` example for SSR -Because SSR pages can't use `getStaticPaths`, they can't receive props. Here, we modify our [earlier example](#example-dynamic-pages-at-multiple-levels) to work in SSR by looking up the value of the `slug` param in an object. If the route is at the root ("/"), the slug param will be `undefined`. If the value doesn't exist in the object, we redirect to a 404 page. +Because SSR pages can't use `getStaticPaths()`, they can't receive props. The [previous example](#example-dynamic-pages-at-multiple-levels) can be adapted for SSR mode by looking up the value of the `slug` param in an object. If the route is at the root ("/"), the slug param will be `undefined`. If the value doesn't exist in the object, we redirect to a 404 page. ```astro title="src/pages/[...slug].astro" --- From d737a363ba11f3d95b8ac5c443f762c18a129845 Mon Sep 17 00:00:00 2001 From: Sarah Rainsberger Date: Sat, 18 Feb 2023 02:51:42 +0000 Subject: [PATCH 15/90] update links to astro-syntax --- src/content/docs/en/core-concepts/framework-components.mdx | 2 +- src/content/docs/en/core-concepts/layouts.mdx | 2 +- src/content/docs/en/guides/data-fetching.mdx | 2 +- src/content/docs/en/guides/imports.mdx | 2 +- src/content/docs/en/guides/migrate-to-astro/from-jekyll.mdx | 2 +- src/content/docs/en/guides/troubleshooting.mdx | 4 ++-- src/content/docs/en/guides/upgrade-to/v1.mdx | 2 +- src/content/docs/en/reference/directives-reference.mdx | 4 ++-- .../reference/errors/static-client-address-not-available.mdx | 2 +- src/content/docs/en/tutorial/2-pages/3.mdx | 2 +- src/content/docs/en/tutorial/2-pages/4.mdx | 2 +- src/content/docs/en/tutorial/2-pages/5.mdx | 2 +- src/content/docs/en/tutorial/3-components/4.mdx | 2 +- src/content/docs/en/tutorial/6-islands/2.mdx | 2 +- 14 files changed, 16 insertions(+), 16 deletions(-) diff --git a/src/content/docs/en/core-concepts/framework-components.mdx b/src/content/docs/en/core-concepts/framework-components.mdx index bb348a0e9c896..c8dfdd8bbee60 100644 --- a/src/content/docs/en/core-concepts/framework-components.mdx +++ b/src/content/docs/en/core-concepts/framework-components.mdx @@ -224,7 +224,7 @@ If you try to hydrate an Astro component with a `client:` modifier, you will get [Astro components](/en/core-concepts/astro-components/) are HTML-only templating components with no client-side runtime. But, you can use a ` ``` -📚 See how [client-side scripts](/en/core-concepts/astro-components/#client-side-scripts) work in Astro components. +📚 See how [client-side scripts](/en/guides/client-side-scripts/) work in Astro components. ### `define:vars` diff --git a/src/content/docs/en/reference/errors/static-client-address-not-available.mdx b/src/content/docs/en/reference/errors/static-client-address-not-available.mdx index 3956aa4141f41..816aef0175011 100644 --- a/src/content/docs/en/reference/errors/static-client-address-not-available.mdx +++ b/src/content/docs/en/reference/errors/static-client-address-not-available.mdx @@ -18,7 +18,7 @@ import DontEditWarning from '~/components/DontEditWarning.astro' ## What went wrong? The `Astro.clientAddress` property is only available when [Server-side rendering](/en/guides/server-side-rendering/) is enabled. -To get the user's IP address in static mode, different APIs such as [Ipify](https://www.ipify.org/) can be used in a [Client-side script](/en/core-concepts/astro-components/#client-side-scripts) or it may be possible to get the user's IP using a serverless function hosted on your hosting provider. +To get the user's IP address in static mode, different APIs such as [Ipify](https://www.ipify.org/) can be used in a [Client-side script](/en/guides/client-side-scripts/) or it may be possible to get the user's IP using a serverless function hosted on your hosting provider. **See Also:** - [Enabling SSR in Your Project](/en/guides/server-side-rendering/#enabling-ssr-in-your-project) diff --git a/src/content/docs/en/tutorial/2-pages/3.mdx b/src/content/docs/en/tutorial/2-pages/3.mdx index 04d9872d7fa40..b3765c1f3413c 100644 --- a/src/content/docs/en/tutorial/2-pages/3.mdx +++ b/src/content/docs/en/tutorial/2-pages/3.mdx @@ -276,4 +276,4 @@ For each Astro template expression, can you predict the HTML (if any!) that will ### Resources -- [Dynamic expressions in Astro](/en/core-concepts/astro-components/#jsx-like-expressions) +- [Dynamic expressions in Astro](/en/core-concepts/astro-syntax/#jsx-like-expressions) diff --git a/src/content/docs/en/tutorial/2-pages/4.mdx b/src/content/docs/en/tutorial/2-pages/4.mdx index 13c4e8497e93a..11d4d21478585 100644 --- a/src/content/docs/en/tutorial/2-pages/4.mdx +++ b/src/content/docs/en/tutorial/2-pages/4.mdx @@ -194,7 +194,7 @@ const textCase = "uppercase"; ### Resources -- [Astro syntax vs JSX - comparison](/en/core-concepts/astro-components/#differences-between-astro-and-jsx) +- [Astro syntax vs JSX - comparison](/en/core-concepts/astro-syntax/#differences-between-astro-and-jsx) - [Astro ` diff --git a/src/components/recipes/RecipeBox.astro b/src/components/recipes/RecipeBox.astro new file mode 100644 index 0000000000000..fb2a363f007ac --- /dev/null +++ b/src/components/recipes/RecipeBox.astro @@ -0,0 +1,41 @@ +--- + +--- + +
+
+ +
+
+ + diff --git a/src/content/docs/en/guides/recipes.mdx b/src/content/docs/en/guides/recipes.mdx index 2f02f5a995f13..a8d14a6c0e109 100644 --- a/src/content/docs/en/guides/recipes.mdx +++ b/src/content/docs/en/guides/recipes.mdx @@ -3,26 +3,35 @@ title: All Recipes description: See guided examples of building features in Astro. i18nReady: false --- - +import RecipeBox from '~/components/recipes/RecipeBox.astro'; +import BackToRecipes from '~/components/recipes/BackToRecipes.astro'; See guided examples of adding features to your Astro project. ## Curated Recipes + + Add an RSS feed + -{/* Existing guide pages that are to be removed from sidebar and be accessible via recipes */} - - -[Add an RSS feed](/en/guides/rss/) + + Add custom fonts + -[Add custom fonts](/en/guides/fonts/) + + Build an eCommerce cart flyout with nanostores + -[Build an eCommerce cart flyout with nanostores](/en/guides/recipes/nanostores/) + + Verify a Captcha + -[Verify a Captcha](/en/guides/recipes/captcha/) + + Add support for importing YAML + -[Add support for importing YAML](/en/guides/recipes/add-yaml-support/) + ## Community Resources From b4fcc5207323729a84bd297fe1473769cab0f354 Mon Sep 17 00:00:00 2001 From: Shinya Fujino Date: Thu, 23 Feb 2023 07:12:06 +0900 Subject: [PATCH 29/90] i18n(ja): Update nav.ts (#2693) --- src/i18n/ja/nav.ts | 43 +++++++++++++++++++++++++------------------ 1 file changed, 25 insertions(+), 18 deletions(-) diff --git a/src/i18n/ja/nav.ts b/src/i18n/ja/nav.ts index 469469a179b4e..38cfa9b7602ba 100644 --- a/src/i18n/ja/nav.ts +++ b/src/i18n/ja/nav.ts @@ -6,12 +6,8 @@ export default NavDictionary({ 'getting-started': 'はじめに', install: 'インストール', 'editor-setup': 'エディタのセットアップ', + 'reference/cli-reference': 'Astro CLI', 'guides/upgrade-to/v2': 'v2へのアップグレード', - 'guides/migrate-to-astro': 'Astroへの移行', - - // Tutorials - tutorials: 'チュートリアル', - 'blog-tutorial': 'ブログを作る', // Core Concepts coreConcepts: 'コアコンセプト', @@ -19,35 +15,47 @@ export default NavDictionary({ 'concepts/mpa-vs-spa': 'MPA vs. SPA', 'concepts/islands': 'Astroアイランド', + // Tutorials + tutorials: 'チュートリアル', + 'blog-tutorial': 'ブログを作る', + // 'island-tutorial': 'Thinking with Islands', + // Basics basics: '基本', 'core-concepts/project-structure': 'ディレクトリ構成', - 'core-concepts/astro-components': 'Astroコンポーネント', + 'core-concepts/astro-components': 'コンポーネント', 'core-concepts/astro-pages': 'ページ', 'core-concepts/layouts': 'レイアウト', 'guides/markdown-content': 'MarkdownとMDX', 'core-concepts/routing': 'ルーティング', - 'guides/imports': 'インポート', - 'core-concepts/endpoints': 'エンドポイント', - 'guides/data-fetching': 'データフェッチ', - 'guides/deploy': 'デプロイ', - 'guides/troubleshooting': 'トラブルシューティング', + + // Recipes + examples: 'レシピ', + 'guides/migrate-to-astro': 'Astroへの移行', + 'guides/cms': 'CMSとの接続', + 'guides/integrations-guide': 'インテグレーションの追加', + 'guides/deploy': 'サイトのデプロイ', + 'guides/recipes': 'すべてのレシピ', // Guides features: 'ガイド', - 'guides/integrations-guide': 'インテグレーション', + 'core-concepts/astro-syntax': 'Astroコンポーネントの構文', 'core-concepts/framework-components': 'UIフレームワーク', + 'guides/content-collections': 'コンテンツコレクション', + 'guides/server-side-rendering': 'サーバーサイドレンダリング（SSR）', 'guides/client-side-scripts': 'スクリプトとイベントハンドリング', 'guides/styling': 'CSSとスタイル', - 'guides/server-side-rendering': 'サーバーサイドレンダリング（SSR）', - // 'guides/content': 'コンテンツの執筆', - 'guides/content-collections': 'コンテンツコレクション', - 'guides/cms': 'CMSとの接続', 'guides/images': '画像', + 'guides/imports': 'インポート', + 'core-concepts/endpoints': 'エンドポイント', + 'guides/data-fetching': 'データフェッチ', + 'guides/testing': 'テスト', + 'guides/troubleshooting': 'トラブルシューティング', + + // 'guides/content': 'コンテンツの執筆', // 'guides/fonts': 'フォント', // 'core-concepts/sharing-state': '状態の共有', // 'guides/rss': 'RSS', - 'guides/testing': 'テスト', // Configuration configuration: '設定', @@ -59,7 +67,6 @@ export default NavDictionary({ // Reference reference: 'リファレンス', 'reference/configuration-reference': '設定方法', - 'reference/cli-reference': 'CLI', 'reference/api-reference': 'ランタイムAPI', 'reference/integrations-reference': 'インテグレーションAPI', 'reference/adapter-reference': 'アダプターAPI', From 9f613609d1587d021078049fdfcb0c46653ecdb3 Mon Sep 17 00:00:00 2001 From: Sarah Rainsberger Date: Thu, 23 Feb 2023 20:38:36 +0000 Subject: [PATCH 30/90] move Routing and MD/MDX pages into guides --- src/i18n/en/nav.ts | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/i18n/en/nav.ts b/src/i18n/en/nav.ts index 15f7fa66745b3..0032e99b6db75 100644 --- a/src/i18n/en/nav.ts +++ b/src/i18n/en/nav.ts @@ -38,8 +38,6 @@ export default [ }, { text: 'Pages', slug: 'core-concepts/astro-pages', key: 'core-concepts/astro-pages' }, { text: 'Layouts', slug: 'core-concepts/layouts', key: 'core-concepts/layouts' }, - { text: 'Markdown & MDX', slug: 'guides/markdown-content', key: 'guides/markdown-content' }, - { text: 'Routing', slug: 'core-concepts/routing', key: 'core-concepts/routing' }, { text: 'Recipes', header: true, type: 'learn', key: 'examples' }, { text: 'Migrate to Astro', slug: 'guides/migrate-to-astro', key: 'guides/migrate-to-astro' }, @@ -76,6 +74,8 @@ export default [ slug: 'guides/client-side-scripts', key: 'guides/client-side-scripts', }, + { text: 'Markdown & MDX', slug: 'guides/markdown-content', key: 'guides/markdown-content' }, + { text: 'Routing', slug: 'core-concepts/routing', key: 'core-concepts/routing' }, { text: 'CSS & Styling', slug: 'guides/styling', key: 'guides/styling' }, { text: 'Images', slug: 'guides/images', key: 'guides/images' }, { text: 'Imports', slug: 'guides/imports', key: 'guides/imports' }, From 51e6669287a66214e9b5b61d5c43539dc48d8d60 Mon Sep 17 00:00:00 2001 From: Sarah Rainsberger Date: Thu, 23 Feb 2023 20:39:45 +0000 Subject: [PATCH 31/90] rename new page Astro Template Syntax --- src/i18n/en/nav.ts | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/i18n/en/nav.ts b/src/i18n/en/nav.ts index 0032e99b6db75..9f728f2da1f8b 100644 --- a/src/i18n/en/nav.ts +++ b/src/i18n/en/nav.ts @@ -50,7 +50,7 @@ export default [ // TODO: Can some of these be removed, merged, or pulled entirely into Recipes? (ex: RSS as recipe) { text: 'Guides', header: true, type: 'learn', key: 'features' }, { - text: 'Astro Component Syntax', + text: 'Astro Template Syntax', slug: 'core-concepts/astro-syntax', key: 'core-concepts/astro-syntax', }, From f2a76b6f391db6671ae9252fe3d67c6edc22a27e Mon Sep 17 00:00:00 2001 From: Dan Jutan Date: Thu, 23 Feb 2023 20:42:20 +0000 Subject: [PATCH 32/90] recipes folder --- src/components/recipes/BackToRecipes.astro | 2 +- .../docs/en/{guides => }/recipes/add-yaml-support.mdx | 0 src/content/docs/en/{guides => }/recipes/captcha.mdx | 0 .../docs/en/{guides/recipes.mdx => recipes/index.mdx} | 6 +++--- src/content/docs/en/{guides => }/recipes/nanostores.mdx | 0 src/i18n/en/nav.ts | 2 +- 6 files changed, 5 insertions(+), 5 deletions(-) rename src/content/docs/en/{guides => }/recipes/add-yaml-support.mdx (100%) rename src/content/docs/en/{guides => }/recipes/captcha.mdx (100%) rename src/content/docs/en/{guides/recipes.mdx => recipes/index.mdx} (75%) rename src/content/docs/en/{guides => }/recipes/nanostores.mdx (100%) diff --git a/src/components/recipes/BackToRecipes.astro b/src/components/recipes/BackToRecipes.astro index 5146171eea1f1..265771914cae7 100644 --- a/src/components/recipes/BackToRecipes.astro +++ b/src/components/recipes/BackToRecipes.astro @@ -1,7 +1,7 @@ --- --- - + - Build an eCommerce cart flyout with nanostores + Build an eCommerce cart flyout with nanostores - Verify a Captcha + Verify a Captcha - Add support for importing YAML + Add support for importing YAML diff --git a/src/content/docs/en/guides/recipes/nanostores.mdx b/src/content/docs/en/recipes/nanostores.mdx similarity index 100% rename from src/content/docs/en/guides/recipes/nanostores.mdx rename to src/content/docs/en/recipes/nanostores.mdx diff --git a/src/i18n/en/nav.ts b/src/i18n/en/nav.ts index 9f728f2da1f8b..b385e32127970 100644 --- a/src/i18n/en/nav.ts +++ b/src/i18n/en/nav.ts @@ -44,7 +44,7 @@ export default [ { text: 'Connect a CMS', slug: 'guides/cms', key: 'guides/cms' }, { text: 'Add integrations', slug: 'guides/integrations-guide', key: 'guides/integrations-guide' }, { text: 'Deploy your site', slug: 'guides/deploy', key: 'guides/deploy' }, - { text: 'All Recipes', slug: 'guides/recipes', key: 'guides/recipes' }, + { text: 'All Recipes', slug: 'recipes', key: 'recipes' }, // TODO: Can some of these be removed, merged, or pulled entirely into Recipes? (ex: RSS as recipe) From f904e35b428eaa24de83ff40a13f25a84cc1efa3 Mon Sep 17 00:00:00 2001 From: Dan Jutan Date: Thu, 23 Feb 2023 20:54:07 +0000 Subject: [PATCH 33/90] Move fonts back to guides --- src/content/docs/en/recipes/index.mdx | 4 ---- src/i18n/en/nav.ts | 2 +- 2 files changed, 1 insertion(+), 5 deletions(-) diff --git a/src/content/docs/en/recipes/index.mdx b/src/content/docs/en/recipes/index.mdx index 5e90f0e580879..9fbca996a1311 100644 --- a/src/content/docs/en/recipes/index.mdx +++ b/src/content/docs/en/recipes/index.mdx @@ -15,10 +15,6 @@ See guided examples of adding features to your Astro project. Add an RSS feed - - Add custom fonts - - Build an eCommerce cart flyout with nanostores diff --git a/src/i18n/en/nav.ts b/src/i18n/en/nav.ts index b385e32127970..3b8d151a93b1f 100644 --- a/src/i18n/en/nav.ts +++ b/src/i18n/en/nav.ts @@ -78,6 +78,7 @@ export default [ { text: 'Routing', slug: 'core-concepts/routing', key: 'core-concepts/routing' }, { text: 'CSS & Styling', slug: 'guides/styling', key: 'guides/styling' }, { text: 'Images', slug: 'guides/images', key: 'guides/images' }, + { text: 'Fonts', slug: 'guides/fonts', key: 'guides/fonts' }, { text: 'Imports', slug: 'guides/imports', key: 'guides/imports' }, { text: 'Endpoints', slug: 'core-concepts/endpoints', key: 'core-concepts/endpoints' }, { text: 'Data Fetching', slug: 'guides/data-fetching', key: 'guides/data-fetching' }, @@ -86,7 +87,6 @@ export default [ // { text: 'Authoring Content', slug: 'guides/content', key: 'guides/content' }, // { text: 'MDX', slug: 'guides/markdown-content', key: 'guides/markdown-content' }, - // { text: 'Fonts', slug: 'guides/fonts', key: 'guides/fonts' }, // { text: 'Sharing State', slug: 'core-concepts/sharing-state', key: 'core-concepts/sharing-state' }, // { text: 'RSS', slug: 'guides/rss', key: 'guides/rss' }, From f9d9edcb914a0536188d03b9c60a20b6438ac883 Mon Sep 17 00:00:00 2001 From: Dan Jutan Date: Thu, 23 Feb 2023 20:57:48 +0000 Subject: [PATCH 34/90] all recipes -> more recipes --- src/components/recipes/BackToRecipes.astro | 2 +- src/content/docs/en/recipes/index.mdx | 2 +- src/i18n/en/nav.ts | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/src/components/recipes/BackToRecipes.astro b/src/components/recipes/BackToRecipes.astro index 265771914cae7..339094af2cd44 100644 --- a/src/components/recipes/BackToRecipes.astro +++ b/src/components/recipes/BackToRecipes.astro @@ -14,7 +14,7 @@
- Back to all recipes + Back to recipes
diff --git a/src/content/docs/en/recipes/index.mdx b/src/content/docs/en/recipes/index.mdx index 9fbca996a1311..47f12233ee121 100644 --- a/src/content/docs/en/recipes/index.mdx +++ b/src/content/docs/en/recipes/index.mdx @@ -1,5 +1,5 @@ --- -title: All Recipes +title: More Recipes description: See guided examples of building features in Astro. i18nReady: false --- diff --git a/src/i18n/en/nav.ts b/src/i18n/en/nav.ts index 3b8d151a93b1f..a53582fd1e52a 100644 --- a/src/i18n/en/nav.ts +++ b/src/i18n/en/nav.ts @@ -44,7 +44,7 @@ export default [ { text: 'Connect a CMS', slug: 'guides/cms', key: 'guides/cms' }, { text: 'Add integrations', slug: 'guides/integrations-guide', key: 'guides/integrations-guide' }, { text: 'Deploy your site', slug: 'guides/deploy', key: 'guides/deploy' }, - { text: 'All Recipes', slug: 'recipes', key: 'recipes' }, + { text: 'More Recipes', slug: 'recipes', key: 'recipes' }, // TODO: Can some of these be removed, merged, or pulled entirely into Recipes? (ex: RSS as recipe) From f68cb3336be6456f6a6dd010442e24e18e9e9e4f Mon Sep 17 00:00:00 2001 From: Dan Jutan Date: Thu, 23 Feb 2023 20:58:06 +0000 Subject: [PATCH 35/90] remove back button on recipe index --- src/content/docs/en/recipes/index.mdx | 2 -- 1 file changed, 2 deletions(-) diff --git a/src/content/docs/en/recipes/index.mdx b/src/content/docs/en/recipes/index.mdx index 47f12233ee121..f17fa838acc54 100644 --- a/src/content/docs/en/recipes/index.mdx +++ b/src/content/docs/en/recipes/index.mdx @@ -27,8 +27,6 @@ See guided examples of adding features to your Astro project. Add support for importing YAML - - ## Community Resources Add your own here! From af2e870d57888633167e0470184fb78ae32f59f9 Mon Sep 17 00:00:00 2001 From: Chris Swithinbank Date: Fri, 24 Feb 2023 15:46:53 +0100 Subject: [PATCH 36/90] Fix nav key type issue --- src/i18n/en/nav.ts | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/i18n/en/nav.ts b/src/i18n/en/nav.ts index a53582fd1e52a..0253f01bf5fb9 100644 --- a/src/i18n/en/nav.ts +++ b/src/i18n/en/nav.ts @@ -44,7 +44,7 @@ export default [ { text: 'Connect a CMS', slug: 'guides/cms', key: 'guides/cms' }, { text: 'Add integrations', slug: 'guides/integrations-guide', key: 'guides/integrations-guide' }, { text: 'Deploy your site', slug: 'guides/deploy', key: 'guides/deploy' }, - { text: 'More Recipes', slug: 'recipes', key: 'recipes' }, + { text: 'More Recipes', slug: 'recipes', key: 'guides/recipes' }, // TODO: Can some of these be removed, merged, or pulled entirely into Recipes? (ex: RSS as recipe) From 166f218319ba1c0f54213981ec566c1b51620684 Mon Sep 17 00:00:00 2001 From: Chris Swithinbank Date: Fri, 24 Feb 2023 15:51:29 +0100 Subject: [PATCH 37/90] Move main recipes file to avoid `index.mdx` --- src/content/docs/en/{recipes/index.mdx => recipes.mdx} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename src/content/docs/en/{recipes/index.mdx => recipes.mdx} (100%) diff --git a/src/content/docs/en/recipes/index.mdx b/src/content/docs/en/recipes.mdx similarity index 100% rename from src/content/docs/en/recipes/index.mdx rename to src/content/docs/en/recipes.mdx From 6977d33942ba78ec88fc7d833c3809145307ae49 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E6=9D=8E=E7=91=9E=E4=B8=B0?= Date: Fri, 24 Feb 2023 23:22:36 +0800 Subject: [PATCH 38/90] i18n(zh-cn): Update nav.ts based on reorg-incl-recipes (#2687) * i18n(zh-cn): Update nav.ts * i18n(zh-cn): Update nav.ts * Update nav.ts --------- Co-authored-by: Sarah Rainsberger --- src/i18n/zh-cn/nav.ts | 62 +++++++++++++++++++++++++------------------ 1 file changed, 36 insertions(+), 26 deletions(-) diff --git a/src/i18n/zh-cn/nav.ts b/src/i18n/zh-cn/nav.ts index 7302f56b67b84..a478dcb9e5a81 100644 --- a/src/i18n/zh-cn/nav.ts +++ b/src/i18n/zh-cn/nav.ts @@ -3,53 +3,63 @@ import { NavDictionary } from '../translation-checkers'; export default NavDictionary({ startHere: '起步', 'getting-started': '入门指南', - install: '安装', + 'install': '安装', 'editor-setup': '编辑器设置', + 'reference/cli-reference': '命令行', 'guides/upgrade-to/v2': '升级到 v2', - 'guides/migrate-to-astro': '迁移到 Astro', - tutorials: '教程', - 'blog-tutorial': '搭建博客', - 'guides/client-side-scripts': '处理脚本和事件', + coreConcepts: '核心理念', - basics: '基础内容', 'concepts/why-astro': '为什么选择Astro', 'concepts/islands': 'Astro群岛', + + tutorials: '教程', + 'blog-tutorial': '搭建博客', + + basics: '基础内容', 'core-concepts/project-structure': '项目结构', 'core-concepts/astro-components': '组件', 'core-concepts/astro-pages': '页面', 'core-concepts/layouts': '结构布局', - // 'core-concepts/sharing-state': '共享状态', 'guides/markdown-content': 'Markdown', - 'guides/imports': '静态资源', - 'guides/images': '图像', + 'core-concepts/routing': '路由规则', + + examples: "方案", + 'guides/migrate-to-astro': '迁移到 Astro', + 'guides/cms': '连接到 CMS', + 'guides/integrations-guide': '集成', + 'guides/deploy': '部署', + 'guides/recipes': "所有方案", + // 'core-concepts/sharing-state': '共享状态', // 'guides/fonts': '字体', + // 'guides/rss': 'RSS', + // 'guides/content': '创作内容', + features: '使用指南', - configuration: '配置', - 'guides/configuring-astro': '配置 Astro', + 'core-concepts/astro-syntax': "Astro 组件语法", + 'core-concepts/framework-components': '框架组件', + 'guides/content-collections': '内容集合', + 'guides/server-side-rendering': '服务端渲染 (SSR)', + 'guides/client-side-scripts': '处理脚本和事件', 'guides/styling': 'CSS 样式', + 'guides/images': '图像', + 'guides/imports': '静态资源', + 'core-concepts/endpoints': 'API 端点', 'guides/data-fetching': '数据获取', - 'guides/deploy': '部署', - 'guides/environment-variables': '环境变量', - 'guides/aliases': '路径别名', - 'guides/integrations-guide': '集成', - // 'guides/rss': 'RSS', - 'guides/server-side-rendering': '服务端渲染 (SSR)', - 'guides/typescript': 'TypeScript', - 'guides/troubleshooting': '故障排除', 'guides/testing': '测试', - // 'guides/content': '创作内容', - 'guides/content-collections': '内容集合', - 'guides/cms': '连接到 CMS', - 'core-concepts/framework-components': '框架组件', + 'guides/troubleshooting': '故障排除', + + configuration: '配置', + 'guides/configuring-astro': '配置 Astro', + 'guides/typescript': 'TypeScript', + 'guides/aliases': '路径别名', + 'guides/environment-variables': '环境变量', + reference: '参考', 'reference/configuration-reference': '配置', - 'reference/cli-reference': '命令行', 'reference/api-reference': '运行时 API', 'reference/integrations-reference': '集成 API', 'reference/adapter-reference': '适配器 API', - 'core-concepts/routing': '路由规则', 'reference/directives-reference': '模板指令', 'reference/error-reference': '错误参考', 'guides/publish-to-npm': 'NPM 包格式', - 'core-concepts/endpoints': 'API 端点', }); From aa7b4504d76ba5d1c9d07c2fc4ee5f182ee840a4 Mon Sep 17 00:00:00 2001 From: Paul Valladares <85648028+dreyfus92@users.noreply.github.com> Date: Fri, 24 Feb 2023 09:25:40 -0600 Subject: [PATCH 39/90] update of nav (#2725) --- src/i18n/es/nav.ts | 58 ++++++++++++++++++++++++++++++++-------------- 1 file changed, 40 insertions(+), 18 deletions(-) diff --git a/src/i18n/es/nav.ts b/src/i18n/es/nav.ts index 41e33acc53087..97a0d9ea823b1 100644 --- a/src/i18n/es/nav.ts +++ b/src/i18n/es/nav.ts @@ -1,47 +1,69 @@ import { NavDictionary } from '../translation-checkers'; export default NavDictionary({ + //startHere startHere: 'Configuración', 'getting-started': 'Empezando', - install: 'Instalación', + 'install': 'Instalación', 'editor-setup': 'Configuración del editor de código', + 'reference/cli-reference': 'CLI', + 'guides/upgrade-to/v2': 'Actualizando a la versión v2', + + //coreConcepts coreConcepts: 'Conceptos básicos', 'concepts/why-astro': '¿Por qué usar Astro?', 'concepts/mpa-vs-spa': 'MPA vs. SPA', 'concepts/islands': 'Astro Islands', + + //tutorials + tutorials: 'Tutoriales', + 'blog-tutorial': 'Crea un Blog', + + //basics basics: 'Fundamentos', 'core-concepts/project-structure': 'Estructura de proyecto', 'core-concepts/astro-components': 'Componentes', 'core-concepts/astro-pages': 'Páginas', 'core-concepts/layouts': 'Plantillas de página', - 'guides/markdown-content': 'Markdown & MDX', + + //recipes + examples: 'Recetas', + 'guides/migrate-to-astro': 'Migrar a Astro', + 'guides/cms': 'Conectando un CMS', + 'guides/integrations-guide': 'Integraciones', + 'guides/deploy': 'Desplegar', + 'recipes': 'Más recetas', + + //guides + features: 'Guías', + 'core-concepts/astro-syntax': 'Sintaxis de Astro', + 'core-concepts/framework-components': 'Componentes de otros frameworks', + 'guides/server-side-rendering': 'Renderizado en el servidor', + 'guides/client-side-scripts': 'Renderizado en el cliente', + 'guides/markdown-content': 'Contenido en Markdown', 'core-concepts/routing': 'Enrutamiento', + 'guides/styling': 'Estilos & CSS', + 'guides/images': 'Imágenes', + 'guides/fonts': 'Usando fuentes personalizadas', 'guides/imports': 'Recursos estáticos', 'core-concepts/endpoints': 'Endpoints', + 'guides/data-fetching': 'Fetching de datos', + 'guides/testing': 'Pruebas', 'guides/troubleshooting': 'Solución de problemas', - 'guides/deploy': 'Desplegar', - features: 'Características', + + //configurations + configuration: 'Configuraciones', 'guides/configuring-astro': 'Configuración de Astro', - 'guides/styling': 'Estilos & CSS', - // 'guides/content': 'Contenido de autoría', - 'guides/cms': 'Conectando un CMS', - 'guides/data-fetching': 'Fetching de datos', - 'guides/environment-variables': 'Variables de entorno', - 'guides/images': 'Imágenes', - // 'guides/fonts': 'Fuentes', - // 'core-concepts/sharing-state': 'Compartiendo estado', - 'guides/aliases': 'Alias de importación', - 'guides/integrations-guide': 'Integraciones', - // 'guides/rss': 'RSS', - 'guides/server-side-rendering': 'Renderizado en el servidor', 'guides/typescript': 'TypeScript', - 'core-concepts/framework-components': 'Componentes de otros frameworks', + 'guides/environment-variables': 'Variables de entorno', + + //reference reference: 'Referencia', 'reference/configuration-reference': 'Configuración', - 'reference/cli-reference': 'CLI', 'reference/api-reference': 'API', 'reference/integrations-reference': 'API de Integraciones', 'reference/adapter-reference': 'API de adaptadores', 'reference/directives-reference': 'Directivas en maquetado', + 'reference/error-reference': 'Referencia de errores', 'guides/publish-to-npm': 'Publica en NPM', }); From bbc345270ca23bb6278cd248fa94bfa01e359868 Mon Sep 17 00:00:00 2001 From: Sarah Rainsberger Date: Fri, 24 Feb 2023 16:05:08 +0000 Subject: [PATCH 40/90] kill nanostores, replace with orig sharing state --- src/content/docs/en/recipes.mdx | 2 +- src/content/docs/en/recipes/nanostores.mdx | 692 --------------------- 2 files changed, 1 insertion(+), 693 deletions(-) delete mode 100644 src/content/docs/en/recipes/nanostores.mdx diff --git a/src/content/docs/en/recipes.mdx b/src/content/docs/en/recipes.mdx index f17fa838acc54..60a9dd92c53d0 100644 --- a/src/content/docs/en/recipes.mdx +++ b/src/content/docs/en/recipes.mdx @@ -16,7 +16,7 @@ See guided examples of adding features to your Astro project. - Build an eCommerce cart flyout with nanostores + Share state across components with nanostores diff --git a/src/content/docs/en/recipes/nanostores.mdx b/src/content/docs/en/recipes/nanostores.mdx deleted file mode 100644 index 64225ca690a82..0000000000000 --- a/src/content/docs/en/recipes/nanostores.mdx +++ /dev/null @@ -1,692 +0,0 @@ ---- -title: Add an eCommerce cart using Nano Stores -i18nReady: false ---- - -import UIFrameworkTabs from '~/components/tabs/UIFrameworkTabs.astro' -import LoopingVideo from '~/components/LoopingVideo.astro' -import JavascriptFlavorTabs from '~/components/tabs/JavascriptFlavorTabs.astro' - -When building an Astro website with [islands architecture / partial hydration](/en/concepts/islands/), you may have run into this problem: **I want to share state between my components.** - -UI frameworks like React or Vue may encourage ["context" providers](https://reactjs.org/docs/context.html) for other components to consume. But when [partially hydrating components](/en/core-concepts/framework-components/#hydrating-interactive-components) within Astro or Markdown, you can't use these context wrappers. - -Astro recommends a different solution for shared client-side storage: [**Nano Stores**](https://github.com/nanostores/nanostores). - -## Why Nano Stores? - -The [Nano Stores](https://github.com/nanostores/nanostores) library allows you to author stores that any component can interact with. We recommend Nano Stores because: -- **They're lightweight.** Nano Stores ship the bare minimum JS you'll need (less than 1 KB) with zero dependencies. -- **They're framework-agnostic.** This means sharing state between frameworks will be seamless! Astro is built on flexibility, so we love solutions that offer a similar developer experience no matter your preference. - -Still, there are a number of alternatives you can explore. These include: -- [Svelte's built-in stores](https://svelte.dev/tutorial/writable-stores) -- [Solid signals](https://www.solidjs.com/docs/latest) outside of a component context -- [Vue's reactivity API](https://vuejs.org/guide/scaling-up/state-management.html#simple-state-management-with-reactivity-api) -- [Sending custom browser events](https://developer.mozilla.org/en-US/docs/Web/Events/Creating_and_triggering_events) between components - -:::note[FAQ] - -
-**🙋 Can I use Nano Stores in `.astro` files or other server-side components?** - -Nano Stores _can_ be imported, written to, and read from in server-side components, **but we don't recommend it!** This is due to a few restrictions: -- Writing to a store from a `.astro` file or [non-hydrated component](/en/core-concepts/framework-components/#hydrating-interactive-components) will _not_ affect the value received by [client-side components](/en/reference/directives-reference/#client-directives). -- You cannot pass a Nano Store as a "prop" to client-side components. -- You cannot subscribe to store changes from a `.astro` file, since Astro components do not re-render. - -If you understand these restrictions and still find a use case, you can give Nano Stores a try! Just remember that Nano Stores are built for reactivity to changes on the **client** specifically. - -
- -
-**🙋 How do Svelte stores compare to Nano Stores?** - -**Nano Stores and [Svelte stores](https://svelte.dev/tutorial/writable-stores) are very similar!** In fact, [nanostores allow you to use the same `$` shortcut](https://github.com/nanostores/nanostores#svelte) for subscriptions that you might use with Svelte stores. - -If you want to avoid third-party libraries, [Svelte stores](https://svelte.dev/tutorial/writable-stores) are a great cross-island communication tool on their own. Still, you might prefer Nano Stores if a) you like their add-ons for ["objects"](https://github.com/nanostores/nanostores#maps) and [async state](https://github.com/nanostores/nanostores#lazy-stores), or b) you want to communicate between Svelte and other UI frameworks like Preact or Vue. -
- -
-**🙋 How do Solid signals compare to Nano Stores?** - -If you've used Solid for a while, you may have tried moving [signals](https://www.solidjs.com/docs/latest#createsignal) or [stores](https://www.solidjs.com/docs/latest#createstore) outside of your components. This is a great way to share state between Solid islands! Try exporting signals from a shared file: - -```js -// sharedStore.js -import { createSignal } from 'solid-js'; - -export const sharedCount = createSignal(0); -``` -...and all components importing `sharedCount` will share the same state. Though this works well, you might prefer Nano Stores if a) you like their add-ons for ["objects"](https://github.com/nanostores/nanostores#maps) and [async state](https://github.com/nanostores/nanostores#lazy-stores), or b) you want to communicate between Solid and other UI frameworks like Preact or Vue. -
-::: - -## Installing Nano Stores - -To get started, install Nano Stores alongside their helper package for your favorite UI framework: - - - - ```shell - npm install nanostores @nanostores/preact - ``` - - - ```shell - npm install nanostores @nanostores/react - ``` - - - ```shell - npm install nanostores @nanostores/solid - ``` - - - ```shell - npm install nanostores - ``` - :::note - No helper package here! Nano Stores can be used like standard Svelte stores. - ::: - - - ```shell - npm install nanostores @nanostores/vue - ``` - - - -You can jump into the [Nano Stores usage guide](https://github.com/nanostores/nanostores#guide) from here, or follow along with our example below! - -## Usage example - ecommerce cart flyout - -Let's say we're building a simple ecommerce interface with three interactive elements: -- An "add to cart" submission form -- A cart flyout to display those added items -- A cart flyout toggle - - - -_[**Try the completed example**](https://github.com/withastro/astro/tree/main/examples/with-nanostores) on your machine or online via Stackblitz._ - -Your base Astro file may look like this: - -```astro ---- -// Example: src/pages/index.astro -import CartFlyoutToggle from '../components/CartFlyoutToggle'; -import CartFlyout from '../components/CartFlyout'; -import AddToCartForm from '../components/AddToCartForm'; ---- - - - -... - -
- -
-
- - - -
- - - -``` - -### Using "atoms" - -Let's start by opening our `CartFlyout` whenever `CartFlyoutToggle` is clicked. - -First, create a new JS or TS file to contain our store. We'll use an ["atom"](https://github.com/nanostores/nanostores#atoms) for this: - -```js -// src/cartStore.js -import { atom } from 'nanostores'; - -export const isCartOpen = atom(false); -``` - -Now, we can import this store into any file that needs to read or write. We'll start by wiring up our `CartFlyoutToggle`: - - - -```jsx -// src/components/CartFlyoutToggle.jsx -import { useStore } from '@nanostores/preact'; -import { isCartOpen } from '../cartStore'; - -export default function CartButton() { - // read the store value with the `useStore` hook - const $isCartOpen = useStore(isCartOpen); - // write to the imported store using `.set` - return ( - - ) -} -``` - - -```jsx -// src/components/CartFlyoutToggle.jsx -import { useStore } from '@nanostores/react'; -import { isCartOpen } from '../cartStore'; - -export default function CartButton() { - // read the store value with the `useStore` hook - const $isCartOpen = useStore(isCartOpen); - // write to the imported store using `.set` - return ( - - ) -} -``` - - -```jsx -// src/components/CartFlyoutToggle.jsx -import { useStore } from '@nanostores/solid'; -import { isCartOpen } from '../cartStore'; - -export default function CartButton() { - // read the store value with the `useStore` hook - const $isCartOpen = useStore(isCartOpen); - // write to the imported store using `.set` - return ( - - ) -} -``` - - -```svelte - - - - - -``` - - -```vue - - - - -``` - - - -Then, we can read `isCartOpen` from our `CartFlyout` component: - - - -```jsx -// src/components/CartFlyout.jsx -import { useStore } from '@nanostores/preact'; -import { isCartOpen } from '../cartStore'; - -export default function CartFlyout() { - const $isCartOpen = useStore(isCartOpen); - - return $isCartOpen ? : null; -} -``` - - -```jsx -// src/components/CartFlyout.jsx -import { useStore } from '@nanostores/react'; -import { isCartOpen } from '../cartStore'; - -export default function CartFlyout() { - const $isCartOpen = useStore(isCartOpen); - - return $isCartOpen ? : null; -} -``` - - -```jsx -// src/components/CartFlyout.jsx -import { useStore } from '@nanostores/solid'; -import { isCartOpen } from '../cartStore'; - -export default function CartFlyout() { - const $isCartOpen = useStore(isCartOpen); - - return $isCartOpen() ? : null; -} -``` - - -```svelte - - - -{#if $isCartOpen} - -{/if} -``` - - -```vue - - - - -``` - - - -### Using "maps" - -:::tip -**[Maps](https://github.com/nanostores/nanostores#maps) are a great choice for objects you write to regularly!** Alongside the standard `get()` and `set()` helpers an `atom` provides, you'll also have a `.setKey()` function to efficiently update individual object keys. -::: - -Now, let's keep track of the items inside your cart. To avoid duplicates and keep track of "quantity," we can store your cart as an object with the item's ID as a key. We'll use a [Map](https://github.com/nanostores/nanostores#maps) for this. - -Let's add a `cartItem` store to our `cartStore.js` from earlier. You can also switch to a TypeScript file to define the shape if you're so inclined. - - - - ```js - // src/cartStore.js - import { atom, map } from 'nanostores'; - - export const isCartOpen = atom(false); - - /** - * @typedef {Object} CartItem - * @property {string} id - * @property {string} name - * @property {string} imageSrc - * @property {number} quantity - */ - - /** @type {import('nanostores').MapStore>} */ - export const cartItems = map({}); - - ``` - - - ```ts - // src/cartStore.ts - import { atom, map } from 'nanostores'; - - export const isCartOpen = atom(false); - - export type CartItem = { - id: string; - name: string; - imageSrc: string; - quantity: number; - } - - export const cartItems = map>({}); - ``` - - - -Now, let's export an `addCartItem` helper for our components to use. -- **If that item doesn't exist in your cart**, add the item with a starting quantity of 1. -- **If that item _does_ already exist**, bump the quantity by 1. - - - - ```js - // src/cartStore.js - ... - export function addCartItem({ id, name, imageSrc }) { - const existingEntry = cartItems.get()[id]; - if (existingEntry) { - cartItems.setKey(id, { - ...existingEntry, - quantity: existingEntry.quantity + 1, - }) - } else { - cartItems.setKey( - id, - { id, name, imageSrc, quantity: 1 } - ); - } - } - ``` - - - ```ts - // src/cartStore.ts - ... - type ItemDisplayInfo = Pick; - export function addCartItem({ id, name, imageSrc }: ItemDisplayInfo) { - const existingEntry = cartItems.get()[id]; - if (existingEntry) { - cartItems.setKey(id, { - ...existingEntry, - quantity: existingEntry.quantity + 1, - }); - } else { - cartItems.setKey( - id, - { id, name, imageSrc, quantity: 1 } - ); - } - } - ``` - - - -:::note -
- -**🙋 Why use `.get()` here instead of a `useStore` helper?** - -You may have noticed we're calling `cartItems.get()` here, instead of grabbing that `useStore` helper from our React / Preact / Solid / Vue examples. This is because **useStore is meant to trigger component re-renders.** In other words, `useStore` should be used whenever the store value is being rendered to the UI. Since we're reading the value when an **event** is triggered (`addToCart` in this case), and we aren't trying to render that value, we don't need `useStore` here. -
-::: - -With our store in place, we can call this function inside our `AddToCartForm` whenever that form is submitted. We'll also open the cart flyout so you can see a full cart summary. - - - -```jsx -// src/components/AddToCartForm.jsx -import { addCartItem, isCartOpen } from '../cartStore'; - -export default function AddToCartForm({ children }) { - // we'll hardcode the item info for simplicity! - const hardcodedItemInfo = { - id: 'astronaut-figurine', - name: 'Astronaut Figurine', - imageSrc: '/images/astronaut-figurine.png', - } - - function addToCart(e) { - e.preventDefault(); - isCartOpen.set(true); - addCartItem(hardcodedItemInfo); - } - - return ( -
- {children} -
- ) -} -``` - - -```jsx -// src/components/AddToCartForm.jsx -import { addCartItem, isCartOpen } from '../cartStore'; - -export default function AddToCartForm({ children }) { - // we'll hardcode the item info for simplicity! - const hardcodedItemInfo = { - id: 'astronaut-figurine', - name: 'Astronaut Figurine', - imageSrc: '/images/astronaut-figurine.png', - } - - function addToCart(e) { - e.preventDefault(); - isCartOpen.set(true); - addCartItem(hardcodedItemInfo); - } - - return ( -
- {children} -
- ) -} -``` - - -```jsx -// src/components/AddToCartForm.jsx -import { addCartItem, isCartOpen } from '../cartStore'; - -export default function AddToCartForm({ children }) { - // we'll hardcode the item info for simplicity! - const hardcodedItemInfo = { - id: 'astronaut-figurine', - name: 'Astronaut Figurine', - imageSrc: '/images/astronaut-figurine.png', - } - - function addToCart(e) { - e.preventDefault(); - isCartOpen.set(true); - addCartItem(hardcodedItemInfo); - } - - return ( -
- {children} -
- ) -} -``` - - -```svelte - -
- -
- - -``` - - -```vue - - - - -``` - - - -Finally, we'll render those cart items inside our `CartFlyout`: - - - -```jsx -// src/components/CartFlyout.jsx -import { useStore } from '@nanostores/preact'; -import { isCartOpen, cartItems } from '../cartStore'; - -export default function CartFlyout() { - const $isCartOpen = useStore(isCartOpen); - const $cartItems = useStore(cartItems); - - return $isCartOpen ? ( - - ) : null; -} -``` - - -```jsx -// src/components/CartFlyout.jsx -import { useStore } from '@nanostores/react'; -import { isCartOpen, cartItems } from '../cartStore'; - -export default function CartFlyout() { - const $isCartOpen = useStore(isCartOpen); - const $cartItems = useStore(cartItems); - - return $isCartOpen ? ( - - ) : null; -} -``` - - -```jsx -// src/components/CartFlyout.jsx -import { useStore } from '@nanostores/solid'; -import { isCartOpen, cartItems } from '../cartStore'; - -export default function CartFlyout() { - const $isCartOpen = useStore(isCartOpen); - const $cartItems = useStore(cartItems); - - return $isCartOpen() ? ( - - ) : null; -} -``` - - -```svelte - - - -{#if $isCartOpen} - {#if Object.values($cartItems).length} - - {#else} -

Your cart is empty!

- {/if} -{/if} -``` - - -```vue - - - - -``` - - - -Now, you should have a fully interactive ecommerce example with the smallest JS bundle in the galaxy 🚀 - -[**Try the completed example**](https://github.com/withastro/astro/tree/main/examples/with-nanostores) on your machine or online via Stackblitz! From 85cb32f17d91e967494f65d8f4c88b4c885928ec Mon Sep 17 00:00:00 2001 From: Sarah Rainsberger Date: Fri, 24 Feb 2023 16:57:22 +0000 Subject: [PATCH 41/90] add commented out original content back in to CLI --- .../docs/en/reference/cli-reference.mdx | 54 +++++++++++++++++++ 1 file changed, 54 insertions(+) diff --git a/src/content/docs/en/reference/cli-reference.mdx b/src/content/docs/en/reference/cli-reference.mdx index d1d293f5a1759..5a8af95877521 100644 --- a/src/content/docs/en/reference/cli-reference.mdx +++ b/src/content/docs/en/reference/cli-reference.mdx @@ -134,6 +134,60 @@ You will often use these `astro` commands, or the scripts that run them, without +{/* + +ORIGINAL CONTENT That We Can Always revert to if new stuff is too friendly + +You can use the Command-Line Interface (CLI) provided by Astro to develop, build, and preview your project from a terminal window. + +Use the CLI by running one of the **commands** documented on this page, optionally followed by any **flags**. Flags customize the behavior of a command. For example, to start the development server on port `8080`, you would combine the `astro dev` command with the `--port` flag: `astro dev --port 8080`. + +In most cases you will use the CLI via your package manager: + + + + ```shell + npx astro dev --port 8080 + ``` + + + ```shell + pnpm astro dev --port 8080 + ``` + + + ```shell + yarn astro dev --port 8080 + ``` + + + +If you started your project using [the `create astro` wizard](/en/install/auto/#1-run-the-setup-wizard), you can also use the scripts in `package.json` for a shorter version of these commands. See the `README.md` in your project for details of which commands are available. + + + + ```shell + # run the dev server on port 8080 using the `start` script in `package.json` + npm run start -- --port 8080 + ``` + (The extra `--` before the `--port` flag is necessary for `npm` to pass your flags to the `astro` command.) + + + ```shell + # run the dev server on port 8080 using the `start` script in `package.json` + pnpm start --port 8080 + ``` + + + ```shell + # run the dev server on port 8080 using the `start` script in `package.json` + yarn start --port 8080 + ``` + + + +*/} + ## `astro dev` Runs Astro's development server. This is a local HTTP server that doesn't bundle assets. It uses Hot Module Replacement (HMR) to update your browser as you save changes in your editor. From 7fa3ea3e6d5d4f5a9ca222ebc3301511e7fd9358 Mon Sep 17 00:00:00 2001 From: Chris Swithinbank Date: Fri, 24 Feb 2023 19:28:07 +0100 Subject: [PATCH 42/90] Make logos optional in `` --- src/components/NavGrid/Card.astro | 4 ++-- src/components/NavGrid/CardsNav.astro | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/src/components/NavGrid/Card.astro b/src/components/NavGrid/Card.astro index 5c08ae5b2c74c..8bb6fae92a1a6 100644 --- a/src/components/NavGrid/Card.astro +++ b/src/components/NavGrid/Card.astro @@ -4,7 +4,7 @@ import BrandLogo from '../BrandLogo.astro'; export interface Props { href: string; - logo: LogoKey; + logo?: LogoKey; current?: boolean; minimal?: boolean; [key: string]: any; @@ -14,7 +14,7 @@ const { href, logo, current, minimal, class: classes, ...attrs } = Astro.props a ---
  • - + {logo && }

    diff --git a/src/components/NavGrid/CardsNav.astro b/src/components/NavGrid/CardsNav.astro index 067f707faf4db..5701d700e2be9 100644 --- a/src/components/NavGrid/CardsNav.astro +++ b/src/components/NavGrid/CardsNav.astro @@ -9,7 +9,7 @@ export interface Props { links: { title: string; href: string; - logo: LogoKey; + logo?: LogoKey; /** Map of tag IDs to translated tag display text, e.g. `{ static: 'Statisch' }`. */ tags?: Record; }[]; From 543c9d2a75adc0af6611c05516094991067728c4 Mon Sep 17 00:00:00 2001 From: Chris Swithinbank Date: Fri, 24 Feb 2023 19:28:22 +0100 Subject: [PATCH 43/90] Add optional `description` support to `` --- src/components/NavGrid/CardsNav.astro | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/src/components/NavGrid/CardsNav.astro b/src/components/NavGrid/CardsNav.astro index 5701d700e2be9..009d524942ae2 100644 --- a/src/components/NavGrid/CardsNav.astro +++ b/src/components/NavGrid/CardsNav.astro @@ -8,6 +8,7 @@ export interface Props { minimal?: boolean; links: { title: string; + description?: string; href: string; logo?: LogoKey; /** Map of tag IDs to translated tag display text, e.g. `{ static: 'Statisch' }`. */ @@ -25,7 +26,7 @@ const currentPage = new URL(Astro.request.url).pathname; { - links.map(({ href, logo, title, tags }) => ( + links.map(({ description, href, logo, title, tags }) => ( + {description &&

    {description}

    } {tags && (
    {Object.values(tags).map((tag) => ( From e91b42826385314fda8d0d578c7fdfbb2da6852b Mon Sep 17 00:00:00 2001 From: Chris Swithinbank Date: Fri, 24 Feb 2023 19:28:46 +0100 Subject: [PATCH 44/90] Configure content collection schema for recipes (no tags yet) --- src/content/config.ts | 14 ++++++++++++++ 1 file changed, 14 insertions(+) diff --git a/src/content/config.ts b/src/content/config.ts index d31de1a389894..96d120bb4b207 100644 --- a/src/content/config.ts +++ b/src/content/config.ts @@ -45,6 +45,11 @@ export const tutorialSchema = baseSchema.extend({ unitTitle: z.string().optional(), }); +export const recipeSchema = baseSchema.extend({ + type: z.literal('recipe'), + description: z.string(), +}); + export type DeployEntry = CollectionEntry<'docs'> & { data: z.infer; }; @@ -65,6 +70,10 @@ export type TutorialEntry = CollectionEntry<'docs'> & { data: z.infer; }; +export type RecipeEntry = CollectionEntry<'docs'> & { + data: z.infer; +}; + export type IntegrationCategory = z.infer['category']; export function isCmsEntry(entry: CollectionEntry<'docs'>): entry is CmsEntry { @@ -83,6 +92,10 @@ export function isMigrationEntry(entry: CollectionEntry<'docs'>): entry is Migra return entry.data.type === 'migration'; } +export function isRecipeEntry(entry: CollectionEntry<'docs'>): entry is RecipeEntry { + return entry.data.type === 'recipe'; +} + export function isEnglishEntry(entry: CollectionEntry<'docs'>): boolean { return entry.slug.startsWith('en/'); } @@ -95,6 +108,7 @@ const docs = defineCollection({ migrationSchema, tutorialSchema, deploySchema, + recipeSchema, ]), }); From 71cbfb371dfb9ea3789c57145d3fed7fef07c335 Mon Sep 17 00:00:00 2001 From: Chris Swithinbank Date: Fri, 24 Feb 2023 19:30:53 +0100 Subject: [PATCH 45/90] Add `type: recipe` to recipes & write missing descriptions --- src/content/docs/en/core-concepts/sharing-state.mdx | 2 ++ src/content/docs/en/guides/rss.mdx | 5 +++-- src/content/docs/en/recipes/add-yaml-support.mdx | 2 ++ src/content/docs/en/recipes/captcha.mdx | 4 +++- 4 files changed, 10 insertions(+), 3 deletions(-) diff --git a/src/content/docs/en/core-concepts/sharing-state.mdx b/src/content/docs/en/core-concepts/sharing-state.mdx index 79149f8a296ba..aede68dce2e6d 100644 --- a/src/content/docs/en/core-concepts/sharing-state.mdx +++ b/src/content/docs/en/core-concepts/sharing-state.mdx @@ -1,6 +1,8 @@ --- title: Sharing State +description: Learn how to share state across components — and frameworks! — with Nano Stores. i18nReady: true +type: recipe --- import UIFrameworkTabs from '~/components/tabs/UIFrameworkTabs.astro' diff --git a/src/content/docs/en/guides/rss.mdx b/src/content/docs/en/guides/rss.mdx index 4f5822ca50a87..72e338491b417 100644 --- a/src/content/docs/en/guides/rss.mdx +++ b/src/content/docs/en/guides/rss.mdx @@ -1,7 +1,8 @@ --- -title: RSS -description: An intro to RSS in Astro +title: Add an RSS feed +description: Let users subscribe to your content by adding an RSS feed to your Astro site. i18nReady: true +type: recipe --- import PackageManagerTabs from '~/components/tabs/PackageManagerTabs.astro' import Since from '~/components/Since.astro' diff --git a/src/content/docs/en/recipes/add-yaml-support.mdx b/src/content/docs/en/recipes/add-yaml-support.mdx index ad25748caf0a3..24f9c197ca66f 100644 --- a/src/content/docs/en/recipes/add-yaml-support.mdx +++ b/src/content/docs/en/recipes/add-yaml-support.mdx @@ -1,6 +1,8 @@ --- title: Add YAML Support +description: Learn how you can import YAML data in your projects by extending file-type support in Astro. i18nReady: false +type: recipe --- The YAML (`.yml`) data format isn't natively supported by Astro, but you can add support for it by using a compatible Rollup plugin like [`@rollup/plugin-yaml`](https://www.npmjs.com/package/@rollup/plugin-yaml): diff --git a/src/content/docs/en/recipes/captcha.mdx b/src/content/docs/en/recipes/captcha.mdx index 425c16fb4a74f..7c902a5f2bc2e 100644 --- a/src/content/docs/en/recipes/captcha.mdx +++ b/src/content/docs/en/recipes/captcha.mdx @@ -1,6 +1,8 @@ --- -title: Verifying a Captcha +title: Verify a Captcha +description: Learn how to verify a user is human using a “recaptcha” API route. i18nReady: false +type: recipe --- [Server endpoints](/en/core-concepts/endpoints/#server-endpoints-api-routes) can be used as REST API endpoints to run functions such as authentications, database access, and verifications without exposing sensitive data to the client. From cd29df73c1fbbfdade319043d88427a14beca938 Mon Sep 17 00:00:00 2001 From: Chris Swithinbank Date: Fri, 24 Feb 2023 19:31:55 +0100 Subject: [PATCH 46/90] =?UTF-8?q?Very=20basic=20``=20=E2=80=94?= =?UTF-8?q?=20needs=20tag,=20i18n=20support=20&=20styling?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- src/components/RecipesNav.astro | 20 ++++++++++++++++++++ 1 file changed, 20 insertions(+) create mode 100644 src/components/RecipesNav.astro diff --git a/src/components/RecipesNav.astro b/src/components/RecipesNav.astro new file mode 100644 index 0000000000000..f99af8f2e303a --- /dev/null +++ b/src/components/RecipesNav.astro @@ -0,0 +1,20 @@ +--- +import { englishPages } from '~/content'; +import { isRecipeEntry } from '~/content/config'; +import CardsNav from './NavGrid/CardsNav.astro'; + +export interface Props { + minimal?: boolean; +} + +const recipes = englishPages.filter(isRecipeEntry); +--- + + ({ + title: data.title, + description: data.description, + href: slug, + }))} +/> From c77cbd43230805f1a8c903626b9a9421942e8859 Mon Sep 17 00:00:00 2001 From: Chris Swithinbank Date: Fri, 24 Feb 2023 19:32:39 +0100 Subject: [PATCH 47/90] Replace `` with `` --- src/components/recipes/BackToRecipes.astro | 62 ---------------------- src/components/recipes/RecipeBox.astro | 41 -------------- src/content/docs/en/recipes.mdx | 20 ++----- 3 files changed, 3 insertions(+), 120 deletions(-) delete mode 100644 src/components/recipes/BackToRecipes.astro delete mode 100644 src/components/recipes/RecipeBox.astro diff --git a/src/components/recipes/BackToRecipes.astro b/src/components/recipes/BackToRecipes.astro deleted file mode 100644 index 339094af2cd44..0000000000000 --- a/src/components/recipes/BackToRecipes.astro +++ /dev/null @@ -1,62 +0,0 @@ ---- ---- - - - - - - -
    -
    - Back to recipes -
    -
    -     - - diff --git a/src/components/recipes/RecipeBox.astro b/src/components/recipes/RecipeBox.astro deleted file mode 100644 index fb2a363f007ac..0000000000000 --- a/src/components/recipes/RecipeBox.astro +++ /dev/null @@ -1,41 +0,0 @@ ---- - ---- - -
    -
    - -
    -
    - - diff --git a/src/content/docs/en/recipes.mdx b/src/content/docs/en/recipes.mdx index 60a9dd92c53d0..4dd59dae057e8 100644 --- a/src/content/docs/en/recipes.mdx +++ b/src/content/docs/en/recipes.mdx @@ -3,29 +3,15 @@ title: More Recipes description: See guided examples of building features in Astro. i18nReady: false --- -import RecipeBox from '~/components/recipes/RecipeBox.astro'; -import BackToRecipes from '~/components/recipes/BackToRecipes.astro'; + +import RecipesNav from '~/components/RecipesNav.astro'; See guided examples of adding features to your Astro project. ## Curated Recipes - - Add an RSS feed - - - - Share state across components with nanostores - - - - Verify a Captcha - - - - Add support for importing YAML - + ## Community Resources From 1e3c3acb9b67af933d1bb8b69226496d011cbb2c Mon Sep 17 00:00:00 2001 From: Chris Swithinbank Date: Fri, 24 Feb 2023 19:33:59 +0100 Subject: [PATCH 48/90] Fix es nav type error --- src/i18n/es/nav.ts | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/i18n/es/nav.ts b/src/i18n/es/nav.ts index 97a0d9ea823b1..640e34d4c5afc 100644 --- a/src/i18n/es/nav.ts +++ b/src/i18n/es/nav.ts @@ -32,7 +32,7 @@ export default NavDictionary({ 'guides/cms': 'Conectando un CMS', 'guides/integrations-guide': 'Integraciones', 'guides/deploy': 'Desplegar', - 'recipes': 'Más recetas', + 'guides/recipes': 'Más recetas', //guides features: 'Guías', From 89977bd270c70b9ddbc2ef97d4e6d2c8f6a75275 Mon Sep 17 00:00:00 2001 From: Dan Jutan Date: Fri, 24 Feb 2023 20:36:02 +0000 Subject: [PATCH 49/90] sharing state -> share state between islands --- src/content/docs/en/core-concepts/sharing-state.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/content/docs/en/core-concepts/sharing-state.mdx b/src/content/docs/en/core-concepts/sharing-state.mdx index aede68dce2e6d..d04c13028d9a8 100644 --- a/src/content/docs/en/core-concepts/sharing-state.mdx +++ b/src/content/docs/en/core-concepts/sharing-state.mdx @@ -1,5 +1,5 @@ --- -title: Sharing State +title: Share State Between Islands description: Learn how to share state across components — and frameworks! — with Nano Stores. i18nReady: true type: recipe From a511f11c371476f0fed61f0fb2e01697c74069d7 Mon Sep 17 00:00:00 2001 From: Chris Swithinbank Date: Fri, 24 Feb 2023 22:03:17 +0100 Subject: [PATCH 50/90] Tweak card grid to work better for recipe cards --- src/components/NavGrid/Grid.astro | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/src/components/NavGrid/Grid.astro b/src/components/NavGrid/Grid.astro index c5f3d025a6bbb..7aeba2e04ab1b 100644 --- a/src/components/NavGrid/Grid.astro +++ b/src/components/NavGrid/Grid.astro @@ -18,19 +18,19 @@ const { minimal } = Astro.props as Props; display: grid; grid-template-columns: repeat(auto-fill, minmax(var(--column-min-width), 1fr)); grid-template-columns: repeat(auto-fill, minmax(min(var(--column-min-width), 100%), 1fr)); - gap: 1.5rem; + gap: 2rem; list-style: none; + align-items: start; } @media (min-width: 37.75em) { .fluid-grid { - gap: 1.5rem 2.5rem; + gap: 2rem 2.5rem; } } .fluid-grid--minimal { --column-min-width: 6rem; gap: 1.5rem 0.75rem; - align-items: start; } From 958bff4bf14e3136f49392420afab5437ee45455 Mon Sep 17 00:00:00 2001 From: Chris Swithinbank Date: Fri, 24 Feb 2023 22:07:05 +0100 Subject: [PATCH 51/90] Style description text in `` --- src/components/NavGrid/CardsNav.astro | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/src/components/NavGrid/CardsNav.astro b/src/components/NavGrid/CardsNav.astro index 009d524942ae2..9d984330c54db 100644 --- a/src/components/NavGrid/CardsNav.astro +++ b/src/components/NavGrid/CardsNav.astro @@ -34,7 +34,7 @@ const currentPage = new URL(Astro.request.url).pathname; > - {description &&

    {description}

    } + {description &&

    {description}

    } {tags && (
    {Object.values(tags).map((tag) => ( @@ -55,6 +55,12 @@ const currentPage = new URL(Astro.request.url).pathname; accent-color: var(--theme-accent-secondary); } + .description { + margin-top: 0.25rem; + color: var(--theme-text-lighter); + font-size: var(--theme-text-sm); + } + .tags { display: flex; gap: 0.5rem; From b5bbf7e777430dc073573becdc15e40fd0625fba Mon Sep 17 00:00:00 2001 From: Chris Swithinbank Date: Fri, 24 Feb 2023 22:12:19 +0100 Subject: [PATCH 52/90] Remove unneeded styles in `` --- src/components/CMSGuidesNav.astro | 13 ------------- 1 file changed, 13 deletions(-) diff --git a/src/components/CMSGuidesNav.astro b/src/components/CMSGuidesNav.astro index ad7367b218419..d9d9b6e19bbaa 100644 --- a/src/components/CMSGuidesNav.astro +++ b/src/components/CMSGuidesNav.astro @@ -41,17 +41,4 @@ const links = enPages .cms-nav > :global(*) { margin-top: -2rem; } - - .cms-nav > :global(* + *) { - margin-top: -3rem; - } - - .cms-nav :global(.scope) { - font-weight: normal; - color: var(--theme-text-lighter); - } - - h3 { - margin-bottom: 0; - } From 7322ab98551fee6b96c8c36dcdc0c042eecca5fe Mon Sep 17 00:00:00 2001 From: Chris Swithinbank Date: Fri, 24 Feb 2023 22:12:40 +0100 Subject: [PATCH 53/90] Fix margins on `` --- src/components/RecipesNav.astro | 25 +++++++++++++++++-------- 1 file changed, 17 insertions(+), 8 deletions(-) diff --git a/src/components/RecipesNav.astro b/src/components/RecipesNav.astro index f99af8f2e303a..da50b82847ac4 100644 --- a/src/components/RecipesNav.astro +++ b/src/components/RecipesNav.astro @@ -10,11 +10,20 @@ export interface Props { const recipes = englishPages.filter(isRecipeEntry); --- - ({ - title: data.title, - description: data.description, - href: slug, - }))} -/> +
    + ({ + title: data.title, + description: data.description, + href: slug, + tags: Object.fromEntries(data.tags?.map((t) => [t, t]) || []), + }))} + /> +
    + + From cf6dfa663ebee41266354126a94900dcc3fb4649 Mon Sep 17 00:00:00 2001 From: Chris Swithinbank Date: Fri, 24 Feb 2023 22:35:26 +0100 Subject: [PATCH 54/90] Fix `` links & remove tags --- src/components/RecipesNav.astro | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/src/components/RecipesNav.astro b/src/components/RecipesNav.astro index da50b82847ac4..f204de9d6f4cf 100644 --- a/src/components/RecipesNav.astro +++ b/src/components/RecipesNav.astro @@ -1,12 +1,14 @@ --- import { englishPages } from '~/content'; import { isRecipeEntry } from '~/content/config'; +import { getLanguageFromURL } from '~/util'; import CardsNav from './NavGrid/CardsNav.astro'; export interface Props { minimal?: boolean; } +const lang = getLanguageFromURL(Astro.url.pathname); const recipes = englishPages.filter(isRecipeEntry); --- @@ -16,8 +18,7 @@ const recipes = englishPages.filter(isRecipeEntry); links={recipes.map(({ data, slug }) => ({ title: data.title, description: data.description, - href: slug, - tags: Object.fromEntries(data.tags?.map((t) => [t, t]) || []), + href: '/' + slug.replace('en/', `${lang}/`) + '/', }))} />
    From 1fd34a13cf2108188c9e0b429013891793e37bbd Mon Sep 17 00:00:00 2001 From: Chris Swithinbank Date: Fri, 24 Feb 2023 22:39:18 +0100 Subject: [PATCH 55/90] Add `` --- src/i18n/en/ui.ts | 2 ++ src/layouts/LayoutSwitcher.astro | 5 +++++ src/layouts/RecipeLayout.astro | 27 +++++++++++++++++++++++++++ 3 files changed, 34 insertions(+) create mode 100644 src/layouts/RecipeLayout.astro diff --git a/src/i18n/en/ui.ts b/src/i18n/en/ui.ts index 7686580ec40c7..6814bda05d744 100644 --- a/src/i18n/en/ui.ts +++ b/src/i18n/en/ui.ts @@ -51,6 +51,8 @@ export default { 'cms.navTitle': 'More CMS guides', // Migration Guides vocabulary 'migration.navTitle': 'More migration guides', + // Recipes vocabulary + 'recipes.navTitle': 'More recipes', // `` fallback text 'contributors.seeAll': 'See all contributors', // Fallback content notice shown when a page is not yet translated diff --git a/src/layouts/LayoutSwitcher.astro b/src/layouts/LayoutSwitcher.astro index f4c9b8835cce7..b709ddd99141b 100644 --- a/src/layouts/LayoutSwitcher.astro +++ b/src/layouts/LayoutSwitcher.astro @@ -7,6 +7,7 @@ import IntegrationLayout from '~/layouts/IntegrationLayout.astro'; import MainLayout from '~/layouts/MainLayout.astro'; import MigrationLayout from '~/layouts/MigrationLayout.astro'; import TutorialLayout from '~/layouts/TutorialLayout.astro'; +import RecipeLayout from './RecipeLayout.astro'; export interface Props { data: CollectionEntry<'docs'>['data']; @@ -37,6 +38,10 @@ const { data, headings } = Astro.props; + ) : data.type === 'recipe' ? ( + + + ) : ( diff --git a/src/layouts/RecipeLayout.astro b/src/layouts/RecipeLayout.astro new file mode 100644 index 0000000000000..5cfc2e89d680e --- /dev/null +++ b/src/layouts/RecipeLayout.astro @@ -0,0 +1,27 @@ +--- +import type { MarkdownHeading } from 'astro'; +import RecipesNav from '~/components/RecipesNav.astro'; +import UIString from '~/components/UIString.astro'; +import type { RecipeEntry } from '~/content/config'; +import MainLayout from './MainLayout.astro'; + +export interface Props { + content: RecipeEntry['data']; + headings: MarkdownHeading[]; +} +--- + + + +
    +

    + +     + + From a3181647f07851d260232681301a00cbe4029f79 Mon Sep 17 00:00:00 2001 From: Sarah Rainsberger Date: Fri, 24 Feb 2023 22:20:45 +0000 Subject: [PATCH 56/90] move CLI Reference page back to reference, remove Learn cateogry --- src/i18n/en/nav.ts | 2 +- src/util/getPageCategory.ts | 1 - 2 files changed, 1 insertion(+), 2 deletions(-) diff --git a/src/i18n/en/nav.ts b/src/i18n/en/nav.ts index 0253f01bf5fb9..d67f9ab4d0052 100644 --- a/src/i18n/en/nav.ts +++ b/src/i18n/en/nav.ts @@ -12,7 +12,6 @@ export default [ { text: 'Getting Started', slug: 'getting-started', key: 'getting-started' }, { text: 'Installation', slug: 'install/auto', key: 'install' }, { text: 'Editor Setup', slug: 'editor-setup', key: 'editor-setup' }, - { text: 'The Astro CLI', slug: 'reference/cli-reference', key: 'reference/cli-reference' }, { text: 'Upgrade to v2', slug: 'guides/upgrade-to/v2', key: 'guides/upgrade-to/v2' }, { text: 'Core Concepts', header: true, type: 'learn', key: 'coreConcepts' }, @@ -122,6 +121,7 @@ export default [ slug: 'reference/directives-reference', key: 'reference/directives-reference', }, + { text: 'The Astro CLI', slug: 'reference/cli-reference', key: 'reference/cli-reference' }, { text: 'Error Reference', slug: 'reference/error-reference', diff --git a/src/util/getPageCategory.ts b/src/util/getPageCategory.ts index 1fae75bad1561..17ded868b6d61 100644 --- a/src/util/getPageCategory.ts +++ b/src/util/getPageCategory.ts @@ -5,7 +5,6 @@ const defaultCategory = 'Learn'; // these paths and will return early when one matches. This means more specific // paths need to be earlier in the array, e.g. `reference/errors/` before `reference/`. const categories = [ - ['reference/cli', 'Learn'], ['guides/deploy/', 'Deploy Guides'], ['guides/integrations-guide/', 'Integration Guides'], ['reference/errors/', 'Error Reference'], From 4f74b44f8cc3fe65300910709e815fcc4288415c Mon Sep 17 00:00:00 2001 From: Sarah Rainsberger Date: Sun, 26 Feb 2023 02:09:32 +0000 Subject: [PATCH 57/90] add links back to recipes from original pages --- src/content/docs/en/guides/imports.mdx | 6 +++--- src/content/docs/en/guides/server-side-rendering.mdx | 4 ++++ 2 files changed, 7 insertions(+), 3 deletions(-) diff --git a/src/content/docs/en/guides/imports.mdx b/src/content/docs/en/guides/imports.mdx index f93c1363bda53..00e932fd3e519 100644 --- a/src/content/docs/en/guides/imports.mdx +++ b/src/content/docs/en/guides/imports.mdx @@ -232,8 +232,8 @@ const data = JSON.parse(json); With **Vite** and compatible **Rollup** plugins, you can import file types which aren't natively supported by Astro. Learn where to find the plugins you need in the [Finding Plugins](https://vitejs.dev/guide/using-plugins.html#finding-plugins) section of the Vite Documentation. - - :::note[plugin configuration] Refer to your plugin's documentation for configuration options, and how to correctly install it. -::: +:::note[Related recipe] +[Add support for importing YAML](/en/recipes/add-yaml-support/) +::: \ No newline at end of file diff --git a/src/content/docs/en/guides/server-side-rendering.mdx b/src/content/docs/en/guides/server-side-rendering.mdx index 2fd10a9819317..a702d6c204296 100644 --- a/src/content/docs/en/guides/server-side-rendering.mdx +++ b/src/content/docs/en/guides/server-side-rendering.mdx @@ -231,3 +231,7 @@ if (!product) { A server endpoint, also known as an **API route**, is a special function exported from a `.js` or `.ts` file within the `src/pages/` folder. The function takes an [endpoint context](/en/reference/api-reference/#endpoint-context) and returns a [Response](https://developer.mozilla.org/en-US/docs/Web/API/Response). A powerful feature of SSR, API routes are able to securely execute code on the server. To learn more, see our [Endpoints Guide](/en/core-concepts/endpoints/#server-endpoints-api-routes). + +:::note[Related recipe:] +[Verify a CAPTCHA](/en/recipes/captcha/) +::: \ No newline at end of file From ed1e3be9bfb13ae565f4bbad43e63731aa91a39e Mon Sep 17 00:00:00 2001 From: Sarah Rainsberger Date: Sun, 26 Feb 2023 02:22:20 +0000 Subject: [PATCH 58/90] nit edits in integrations-guide --- src/content/docs/en/guides/integrations-guide.mdx | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/src/content/docs/en/guides/integrations-guide.mdx b/src/content/docs/en/guides/integrations-guide.mdx index e15ed846a0227..2a512ca2dd279 100644 --- a/src/content/docs/en/guides/integrations-guide.mdx +++ b/src/content/docs/en/guides/integrations-guide.mdx @@ -1,5 +1,5 @@ --- -title: Using Integrations +title: Add Integrations i18nReady: true --- import IntegrationsNav from '~/components/IntegrationsNav.astro'; @@ -7,7 +7,7 @@ import PackageManagerTabs from '~/components/tabs/PackageManagerTabs.astro' -**Astro Integrations** add new functionality and behaviors for your project with only a few lines of code. You can write a custom integration yourself, use an official integration, or use integrations built by the community. +**Astro integrations** add new functionality and behaviors for your project with only a few lines of code. You can write a custom integration yourself, use an official integration, or use integrations built by the community. Integrations can… @@ -44,7 +44,7 @@ Run the `astro add` command using the package manager of your choice and our aut     -It's even possible to configure multiple integrations at the same time! +It's even possible to add multiple integrations at the same time! From d8cb0168056a9a6fa9e6620cf69b9ba414dfd39b Mon Sep 17 00:00:00 2001 From: Sarah Rainsberger Date: Sun, 26 Feb 2023 03:20:14 +0000 Subject: [PATCH 59/90] links no longer notes; use emoji --- src/content/docs/en/guides/imports.mdx | 6 +++--- src/content/docs/en/guides/server-side-rendering.mdx | 4 +--- 2 files changed, 4 insertions(+), 6 deletions(-) diff --git a/src/content/docs/en/guides/imports.mdx b/src/content/docs/en/guides/imports.mdx index 00e932fd3e519..3399db23f9ec2 100644 --- a/src/content/docs/en/guides/imports.mdx +++ b/src/content/docs/en/guides/imports.mdx @@ -232,8 +232,8 @@ const data = JSON.parse(json); With **Vite** and compatible **Rollup** plugins, you can import file types which aren't natively supported by Astro. Learn where to find the plugins you need in the [Finding Plugins](https://vitejs.dev/guide/using-plugins.html#finding-plugins) section of the Vite Documentation. +:::note[plugin configuration] Refer to your plugin's documentation for configuration options, and how to correctly install it. +::: -:::note[Related recipe] -[Add support for importing YAML](/en/recipes/add-yaml-support/) -::: \ No newline at end of file +🧑‍🍳 [Add support for importing YAML data](/en/recipes/add-yaml-support/). diff --git a/src/content/docs/en/guides/server-side-rendering.mdx b/src/content/docs/en/guides/server-side-rendering.mdx index a702d6c204296..13d5ec0a43a33 100644 --- a/src/content/docs/en/guides/server-side-rendering.mdx +++ b/src/content/docs/en/guides/server-side-rendering.mdx @@ -232,6 +232,4 @@ if (!product) { A server endpoint, also known as an **API route**, is a special function exported from a `.js` or `.ts` file within the `src/pages/` folder. The function takes an [endpoint context](/en/reference/api-reference/#endpoint-context) and returns a [Response](https://developer.mozilla.org/en-US/docs/Web/API/Response). A powerful feature of SSR, API routes are able to securely execute code on the server. To learn more, see our [Endpoints Guide](/en/core-concepts/endpoints/#server-endpoints-api-routes). -:::note[Related recipe:] -[Verify a CAPTCHA](/en/recipes/captcha/) -::: \ No newline at end of file +🧑‍🍳 [Use server endpoints to verify a CAPTCHA](/en/recipes/captcha/) \ No newline at end of file From bec79cab9b15538c95aed2151b0715ed2cf7f350 Mon Sep 17 00:00:00 2001 From: Sarah Rainsberger Date: Sun, 26 Feb 2023 03:34:24 +0000 Subject: [PATCH 60/90] related recipes bold text instead of heading; might delete --- src/content/docs/en/guides/imports.mdx | 2 ++ src/content/docs/en/guides/server-side-rendering.mdx | 2 ++ 2 files changed, 4 insertions(+) diff --git a/src/content/docs/en/guides/imports.mdx b/src/content/docs/en/guides/imports.mdx index 3399db23f9ec2..8bf41c7a9b972 100644 --- a/src/content/docs/en/guides/imports.mdx +++ b/src/content/docs/en/guides/imports.mdx @@ -236,4 +236,6 @@ With **Vite** and compatible **Rollup** plugins, you can import file types which Refer to your plugin's documentation for configuration options, and how to correctly install it. ::: +**Related recipe** + 🧑‍🍳 [Add support for importing YAML data](/en/recipes/add-yaml-support/). diff --git a/src/content/docs/en/guides/server-side-rendering.mdx b/src/content/docs/en/guides/server-side-rendering.mdx index 13d5ec0a43a33..2df5fb0f4d670 100644 --- a/src/content/docs/en/guides/server-side-rendering.mdx +++ b/src/content/docs/en/guides/server-side-rendering.mdx @@ -232,4 +232,6 @@ if (!product) { A server endpoint, also known as an **API route**, is a special function exported from a `.js` or `.ts` file within the `src/pages/` folder. The function takes an [endpoint context](/en/reference/api-reference/#endpoint-context) and returns a [Response](https://developer.mozilla.org/en-US/docs/Web/API/Response). A powerful feature of SSR, API routes are able to securely execute code on the server. To learn more, see our [Endpoints Guide](/en/core-concepts/endpoints/#server-endpoints-api-routes). +**Related recipe** + 🧑‍🍳 [Use server endpoints to verify a CAPTCHA](/en/recipes/captcha/) \ No newline at end of file From e8259d8abcde8a28f68948a83979742fed19b856 Mon Sep 17 00:00:00 2001 From: Sarah Rainsberger Date: Sun, 26 Feb 2023 15:39:40 +0000 Subject: [PATCH 61/90] updated links to recipes - one line --- src/content/docs/en/guides/imports.mdx | 4 +--- src/content/docs/en/guides/server-side-rendering.mdx | 4 +--- 2 files changed, 2 insertions(+), 6 deletions(-) diff --git a/src/content/docs/en/guides/imports.mdx b/src/content/docs/en/guides/imports.mdx index 8bf41c7a9b972..428c9866f929e 100644 --- a/src/content/docs/en/guides/imports.mdx +++ b/src/content/docs/en/guides/imports.mdx @@ -236,6 +236,4 @@ With **Vite** and compatible **Rollup** plugins, you can import file types which Refer to your plugin's documentation for configuration options, and how to correctly install it. ::: -**Related recipe** - -🧑‍🍳 [Add support for importing YAML data](/en/recipes/add-yaml-support/). +**Related recipe:** [Add support for importing YAML data](/en/recipes/add-yaml-support/). diff --git a/src/content/docs/en/guides/server-side-rendering.mdx b/src/content/docs/en/guides/server-side-rendering.mdx index 2df5fb0f4d670..2abe52f98ddd4 100644 --- a/src/content/docs/en/guides/server-side-rendering.mdx +++ b/src/content/docs/en/guides/server-side-rendering.mdx @@ -232,6 +232,4 @@ if (!product) { A server endpoint, also known as an **API route**, is a special function exported from a `.js` or `.ts` file within the `src/pages/` folder. The function takes an [endpoint context](/en/reference/api-reference/#endpoint-context) and returns a [Response](https://developer.mozilla.org/en-US/docs/Web/API/Response). A powerful feature of SSR, API routes are able to securely execute code on the server. To learn more, see our [Endpoints Guide](/en/core-concepts/endpoints/#server-endpoints-api-routes). -**Related recipe** - -🧑‍🍳 [Use server endpoints to verify a CAPTCHA](/en/recipes/captcha/) \ No newline at end of file +**Related recipe:** [Use server endpoints to verify a CAPTCHA](/en/recipes/captcha/) \ No newline at end of file From 0e5a60b36686a85523894c5adcea615cfc0f5b05 Mon Sep 17 00:00:00 2001 From: Sarah Rainsberger Date: Sun, 26 Feb 2023 16:11:50 +0000 Subject: [PATCH 62/90] fix broken link, move recipe to proper page! --- src/content/docs/en/core-concepts/endpoints.mdx | 2 +- src/content/docs/en/guides/server-side-rendering.mdx | 4 +--- 2 files changed, 2 insertions(+), 4 deletions(-) diff --git a/src/content/docs/en/core-concepts/endpoints.mdx b/src/content/docs/en/core-concepts/endpoints.mdx index 70d93c2f6ba1b..379b1339cd61e 100644 --- a/src/content/docs/en/core-concepts/endpoints.mdx +++ b/src/content/docs/en/core-concepts/endpoints.mdx @@ -210,4 +210,4 @@ export async function get({ params, redirect }) { } ``` -See an example of [verifying a captcha](/en/guides/recipes/captcha/) +**Related recipe:** [Use server endpoints to verify a CAPTCHA](/en/recipes/captcha/) diff --git a/src/content/docs/en/guides/server-side-rendering.mdx b/src/content/docs/en/guides/server-side-rendering.mdx index 2abe52f98ddd4..6add04d11d1f5 100644 --- a/src/content/docs/en/guides/server-side-rendering.mdx +++ b/src/content/docs/en/guides/server-side-rendering.mdx @@ -230,6 +230,4 @@ if (!product) { ### Server Endpoints A server endpoint, also known as an **API route**, is a special function exported from a `.js` or `.ts` file within the `src/pages/` folder. -The function takes an [endpoint context](/en/reference/api-reference/#endpoint-context) and returns a [Response](https://developer.mozilla.org/en-US/docs/Web/API/Response). A powerful feature of SSR, API routes are able to securely execute code on the server. To learn more, see our [Endpoints Guide](/en/core-concepts/endpoints/#server-endpoints-api-routes). - -**Related recipe:** [Use server endpoints to verify a CAPTCHA](/en/recipes/captcha/) \ No newline at end of file +The function takes an [endpoint context](/en/reference/api-reference/#endpoint-context) and returns a [Response](https://developer.mozilla.org/en-US/docs/Web/API/Response). A powerful feature of SSR, API routes are able to securely execute code on the server. To learn more, see our [Endpoints Guide](/en/core-concepts/endpoints/#server-endpoints-api-routes). \ No newline at end of file From cda234c68735f7404d3c92e2abec30546f877c49 Mon Sep 17 00:00:00 2001 From: Dan Jutan Date: Tue, 28 Feb 2023 16:25:07 +0000 Subject: [PATCH 63/90] Curated -> Official --- src/content/docs/en/recipes.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/content/docs/en/recipes.mdx b/src/content/docs/en/recipes.mdx index 4dd59dae057e8..d846f7024fee5 100644 --- a/src/content/docs/en/recipes.mdx +++ b/src/content/docs/en/recipes.mdx @@ -9,7 +9,7 @@ import RecipesNav from '~/components/RecipesNav.astro'; See guided examples of adding features to your Astro project. -## Curated Recipes +## Official Recipes From 126d6d3f4cc4205847b2276b7f9a4d275ddaad07 Mon Sep 17 00:00:00 2001 From: Yan Thomas <61414485+Yan-Thomas@users.noreply.github.com> Date: Tue, 28 Feb 2023 18:47:48 -0300 Subject: [PATCH 64/90] [i18nIgnore] Add new subpage handling logic (#2758) * [i18nIgnore] Add new subpage handling logic * Revert "[i18nIgnore] Add new subpage handling logic" This reverts commit 5fce612aef206855e497e8e0b8fac198b6a03264. * Refactor subpage highlighting logic * Add missing frontmatter fields from translations * Avoid using `import.meta.url` --------- Co-authored-by: Chris Swithinbank --- src/components/LeftSidebar/LeftSidebar.astro | 2 +- .../LeftSidebar/SidebarContent.astro | 9 ++-- .../docs/es/core-concepts/sharing-state.mdx | 2 + src/content/docs/es/guides/rss.mdx | 1 + .../docs/fr/core-concepts/sharing-state.mdx | 2 + src/content/docs/fr/guides/rss.mdx | 1 + src/content/docs/ja/guides/rss.mdx | 1 + .../pt-br/core-concepts/sharing-state.mdx | 2 + src/content/docs/pt-br/guides/rss.mdx | 1 + .../zh-cn/core-concepts/sharing-state.mdx | 2 + src/content/docs/zh-cn/guides/rss.mdx | 1 + src/util.ts | 15 ------ src/util/getPageCategory.ts | 2 +- src/util/isSubPage.ts | 49 +++++++++++++++++++ 14 files changed, 67 insertions(+), 23 deletions(-) create mode 100644 src/util/isSubPage.ts diff --git a/src/components/LeftSidebar/LeftSidebar.astro b/src/components/LeftSidebar/LeftSidebar.astro index c3e73a7c94935..edf6e18ec6b90 100644 --- a/src/components/LeftSidebar/LeftSidebar.astro +++ b/src/components/LeftSidebar/LeftSidebar.astro @@ -35,7 +35,7 @@ let activeTab: 'learn' | 'api' = 'learn'; // Certain pages are not in the sidebar nav, so we manually set the active tab based on other factors (e.g. Algolia page category). const isReference = ['Error Reference', 'Reference'].includes( - getPageCategory(new URL(currentPage, import.meta.url)) + getPageCategory({ pathname: currentPage }) ); if (isReference) { activeTab = 'api'; diff --git a/src/components/LeftSidebar/SidebarContent.astro b/src/components/LeftSidebar/SidebarContent.astro index 6afd711d034ab..22eb038d2334b 100644 --- a/src/components/LeftSidebar/SidebarContent.astro +++ b/src/components/LeftSidebar/SidebarContent.astro @@ -1,5 +1,6 @@ --- -import { getLanguageFromURL, removeSubpageSegment } from '../../util'; +import { getLanguageFromURL } from '~/util'; +import { isSubPage } from '~/util/isSubPage'; export interface Props { type: TabType; @@ -44,11 +45,7 @@ const lang = getLanguageFromURL(Astro.url.pathname); {isFallback && EN} diff --git a/src/content/docs/es/core-concepts/sharing-state.mdx b/src/content/docs/es/core-concepts/sharing-state.mdx index 8d56c02654dda..b8b00fa6f7fd2 100644 --- a/src/content/docs/es/core-concepts/sharing-state.mdx +++ b/src/content/docs/es/core-concepts/sharing-state.mdx @@ -1,6 +1,8 @@ --- title: Compartiendo Estado +description: Learn how to share state across components — and frameworks! — with Nano Stores. i18nReady: true +type: recipe --- import UIFrameworkTabs from '~/components/tabs/UIFrameworkTabs.astro' diff --git a/src/content/docs/es/guides/rss.mdx b/src/content/docs/es/guides/rss.mdx index 18566819280b7..22f2f3bc934d5 100644 --- a/src/content/docs/es/guides/rss.mdx +++ b/src/content/docs/es/guides/rss.mdx @@ -2,6 +2,7 @@ title: RSS description: Introducción a RSS en Astro i18nReady: true +type: recipe --- import PackageManagerTabs from '~/components/tabs/PackageManagerTabs.astro'; diff --git a/src/content/docs/fr/core-concepts/sharing-state.mdx b/src/content/docs/fr/core-concepts/sharing-state.mdx index 33d33a24e3a88..cc293957de0b5 100644 --- a/src/content/docs/fr/core-concepts/sharing-state.mdx +++ b/src/content/docs/fr/core-concepts/sharing-state.mdx @@ -1,6 +1,8 @@ --- title: Partage d'État +description: Learn how to share state across components — and frameworks! — with Nano Stores. i18nReady: true +type: recipe --- import UIFrameworkTabs from '~/components/tabs/UIFrameworkTabs.astro' import LoopingVideo from '~/components/LoopingVideo.astro' diff --git a/src/content/docs/fr/guides/rss.mdx b/src/content/docs/fr/guides/rss.mdx index 851447f047e8d..f2675796abf3c 100644 --- a/src/content/docs/fr/guides/rss.mdx +++ b/src/content/docs/fr/guides/rss.mdx @@ -1,6 +1,7 @@ --- title: Flux RSS description: Une introduction aux flux RSS avec Astro. +type: recipe --- import PackageManagerTabs from '~/components/tabs/PackageManagerTabs.astro' import Since from '~/components/Since.astro' diff --git a/src/content/docs/ja/guides/rss.mdx b/src/content/docs/ja/guides/rss.mdx index 6c30742fddaf2..1d2e707a0bbe8 100644 --- a/src/content/docs/ja/guides/rss.mdx +++ b/src/content/docs/ja/guides/rss.mdx @@ -2,6 +2,7 @@ title: RSS description: AstroのRSS入門 i18nReady: true +type: recipe --- import PackageManagerTabs from '~/components/tabs/PackageManagerTabs.astro' diff --git a/src/content/docs/pt-br/core-concepts/sharing-state.mdx b/src/content/docs/pt-br/core-concepts/sharing-state.mdx index c6c22bb71ff17..e4a2497bfec32 100644 --- a/src/content/docs/pt-br/core-concepts/sharing-state.mdx +++ b/src/content/docs/pt-br/core-concepts/sharing-state.mdx @@ -1,6 +1,8 @@ --- title: Compartilhamento de Estado +description: Aprenda como compartilhar estado entre componentes — e frameworks! — com Nano Stores. i18nReady: true +type: recipe --- import UIFrameworkTabs from '~/components/tabs/UIFrameworkTabs.astro'; import LoopingVideo from '~/components/LoopingVideo.astro'; diff --git a/src/content/docs/pt-br/guides/rss.mdx b/src/content/docs/pt-br/guides/rss.mdx index 34e5612d5f5bd..3feec642bce5a 100644 --- a/src/content/docs/pt-br/guides/rss.mdx +++ b/src/content/docs/pt-br/guides/rss.mdx @@ -2,6 +2,7 @@ title: RSS description: Uma introdução a RSS em Astro i18nReady: true +type: recipe --- import PackageManagerTabs from '~/components/tabs/PackageManagerTabs.astro'; import Since from '~/components/Since.astro'; diff --git a/src/content/docs/zh-cn/core-concepts/sharing-state.mdx b/src/content/docs/zh-cn/core-concepts/sharing-state.mdx index cbdb1d9e99ca8..447a66ff9f457 100644 --- a/src/content/docs/zh-cn/core-concepts/sharing-state.mdx +++ b/src/content/docs/zh-cn/core-concepts/sharing-state.mdx @@ -1,6 +1,8 @@ --- title: 状态共享 +description: Learn how to share state across components — and frameworks! — with Nano Stores. i18nReady: false +type: recipe --- import UIFrameworkTabs from '~/components/tabs/UIFrameworkTabs.astro' import LoopingVideo from '~/components/LoopingVideo.astro' diff --git a/src/content/docs/zh-cn/guides/rss.mdx b/src/content/docs/zh-cn/guides/rss.mdx index bb968203569d8..82fa6c884bc62 100644 --- a/src/content/docs/zh-cn/guides/rss.mdx +++ b/src/content/docs/zh-cn/guides/rss.mdx @@ -1,6 +1,7 @@ --- title: RSS description: Astro RSS 介绍 +type: recipe --- Astro 支持为博客和其他内容网站快速自动生成 RSS 摘要。更多关于 RSS 摘要的信息参见 [aboutfeeds.com](https://aboutfeeds.com/)。 diff --git a/src/util.ts b/src/util.ts index bf526d70fba2c..0b43ae52668ce 100644 --- a/src/util.ts +++ b/src/util.ts @@ -21,18 +21,3 @@ export const stripLangFromSlug = (slug: CollectionEntry<'docs'>['slug']) => /** Get a page’s lang tag from its slug (e.g. `'en/migrate'` => `'en'`). */ export const getLangFromSlug = (slug: CollectionEntry<'docs'>['slug']) => slug.split('/')[0]; - -/** Remove the subpage segment of a URL string */ -export function removeSubpageSegment(path: string) { - // Include new pages with subpages as part of this regex. - const regex = /(?:install|deploy|integrations-guide|tutorial|migrate-to-astro|recipes|cms)\//; - const matches = regex.exec(path); - - if (matches) { - const matchIndex = matches.index; - // Get the first slash index after the main page path segment. - const slashIndex = path.slice(matchIndex).indexOf('/') + matchIndex; - return path.slice(0, slashIndex); - } - return path; -} diff --git a/src/util/getPageCategory.ts b/src/util/getPageCategory.ts index 17ded868b6d61..d7c5af7815b49 100644 --- a/src/util/getPageCategory.ts +++ b/src/util/getPageCategory.ts @@ -16,7 +16,7 @@ const categories = [ * @param url URL for the current page. * @returns The category for the current page as used by Algolia DocSearch to group search results. */ -export function getPageCategory(url: URL) { +export function getPageCategory(url: { pathname: string }) { const langAgnosticPath = url.pathname.replace(/\/\w\w(-\w\w)?\//, ''); for (const [path, label] of categories) { if (langAgnosticPath.startsWith(path)) return label; diff --git a/src/util/isSubPage.ts b/src/util/isSubPage.ts new file mode 100644 index 0000000000000..9de1b984f019c --- /dev/null +++ b/src/util/isSubPage.ts @@ -0,0 +1,49 @@ +import type { CollectionEntry } from 'astro:content'; +import { englishPages } from '~/content'; +import { getPageCategory } from './getPageCategory'; + +/** Remove the sub-page segment of a URL string */ +export function removeSubPageSegment(path: string) { + // Include new pages with sub-pages as part of this regex. + const regex = /(?:install|deploy|integrations-guide|tutorial|migrate-to-astro|recipes|cms)\//; + const matches = regex.exec(path); + + if (matches) { + const matchIndex = matches.index; + // Get the first slash index after the main page path segment. + const slashIndex = path.slice(matchIndex).indexOf('/') + matchIndex; + return path.slice(0, slashIndex); + } + return path; +} + +const typeIndexes: Partial['data']['type'], string>> = { + recipe: 'recipes', +}; + +const categoryIndex: Partial, string>> = { + 'Error Reference': 'reference/error-reference', +}; + +/** + * Test if `currentPage` is considered a sub-page of `parentSlug`. + * @param currentPage The full slug for the current page, e.g. `'en/guides/rss'` + * @param parentSlug The language-less slug for the parent to test against e.g. `'guides/content-collections'` + */ +export function isSubPage(currentPage: string, parentSlug: string): boolean { + // Test 1: do the two pages share a base URL segment? + if (removeSubPageSegment(currentPage).endsWith(removeSubPageSegment(parentSlug))) { + return true; + } + // Test 2: is there a known parent page for this page category? + const category = getPageCategory({ pathname: '/' + currentPage + '/' }); + if (categoryIndex[category] === parentSlug) { + return true; + } + // Test 3: is there a known parent page for this page type? + const type = englishPages.find(({ slug }) => slug === currentPage)?.data.type; + if (type && typeIndexes[type] === parentSlug) { + return true; + } + return false; +} From 05c54a59f571925625b27c1340b9cd14180075d0 Mon Sep 17 00:00:00 2001 From: Dan Jutan Date: Wed, 1 Mar 2023 23:05:00 +0000 Subject: [PATCH 65/90] handle forms recipe + skeleton --- .../docs/en/recipes/handle-forms-api.mdx | 16 ++ src/content/docs/en/recipes/handle-forms.mdx | 195 ++++++++++++++++++ 2 files changed, 211 insertions(+) create mode 100644 src/content/docs/en/recipes/handle-forms-api.mdx create mode 100644 src/content/docs/en/recipes/handle-forms.mdx diff --git a/src/content/docs/en/recipes/handle-forms-api.mdx b/src/content/docs/en/recipes/handle-forms-api.mdx new file mode 100644 index 0000000000000..a1bcf09e74800 --- /dev/null +++ b/src/content/docs/en/recipes/handle-forms-api.mdx @@ -0,0 +1,16 @@ +--- +title: Handle Forms With API Routes +description: Learn how to use JavaScript to send form submissions to an API Route +i18nReady: false +type: recipe +--- + +An HTML form causes the browser to refresh the page or to navigate to a new one. To send form data to an API endpoint instead, you must intercept the form submission using JavaScript. This recipe shows you how to send form data to an API endpoint and handle that data. + +## Recipe + +### Extension: Use Zod to validate your form + +[Zod form data](https://www.npmjs.com/package/zod-form-data) builds on top of [Zod](https://github.com/colinhacks/zod) to validate your form using a schema. This simplifies your code, as it allows you to declare the required fields + +Declare your schema using `zfd.formData`. diff --git a/src/content/docs/en/recipes/handle-forms.mdx b/src/content/docs/en/recipes/handle-forms.mdx new file mode 100644 index 0000000000000..f4c5267fbe2a0 --- /dev/null +++ b/src/content/docs/en/recipes/handle-forms.mdx @@ -0,0 +1,195 @@ +--- +title: Handle Forms With Astro Pages +description: Learn how to build HTML forms and handle submissions with zero JavaScript +i18nReady: false +type: recipe +--- + +In SSR mode, Astro pages can both display and handle forms. In this recipe, you'll use a standard HTML form to submit data to the server, where you'll handle the data in your frontmatter script. + +## Recipe + +1. Create or identify a `.astro` page which will contain your form and your handling code. For example, you could add a feedback page: + + ```astro title="src/pages/register.astro" + --- + --- +

    Register

    + ``` + +2. Add a `
    ` tag with some inputs to the page. Each input should have a `name` attribute that describes the value of that input. Be sure to add a ` +
    + ``` + +3. Use [validation attributes](https://developer.mozilla.org/en-US/docs/Learn/Forms/Form_validation#using_built-in_form_validation) to provide basic client-side validation that works even if JavaScript is disabled. Here, `required` prevents form submission until the field is filled, and `minlength` sets a minimum required length for the input text. `type="email"` also introduces validation that will only accept a valid email format. + + ```astro title="src/pages/register.astro" + --- + --- +

    Register

    +
    + + + + +
    + ``` + + :::tip + You can add custom validation logic, and validation logic that refers to multiple fields, using a ` + +
    + + +