From a4fe77693b97db1ed76f72e251824c0c17631ee9 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Elian=20=E2=98=95=EF=B8=8F?= Date: Wed, 30 Aug 2023 15:25:52 +0200 Subject: [PATCH] Upgrade to Astro v3 guide (#4166) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * initial page * a few entries to get us started * added some more entries * document Astro.cookies, compressHTML and default port * updates sidebar entry and adds more items to guide * update sidebar in international versions * add more entries * typo: fix `astro.mjs.config` to `astro.config.mjs` * refactor: endpoint methods to uppercase variants * chore: update DEL to DELETE * chore: remove `` component * all beta 0 and 1 placeholders entered * edit JSX entry * all placeholder entries in up to date! * added experimental flags to remove * deleted the assets page since it won't be in new docs * Update CSS Bundle Control for 3.0 (#4253) Co-authored-by: Sarah Rainsberger * Use astro: namespace modules (#4239) * feat: document astro features (#3924) Co-authored-by: Sarah Rainsberger * feat: document logger for Astro integrations (#3817) Co-authored-by: Sarah Rainsberger Co-authored-by: Reuben Tier <64310361+TheOtterlord@users.noreply.github.com> Co-authored-by: Chris Swithinbank * removed Assets from sidebar since file was deleted * updated image links to point to page we want them to visit * edited removed astro image integration * edited removed markdown component * edited build config options moved to adapters * remove extra build to adapter code samples * updated typescript version entry * kebab case, astro check entries done; end of REMOVEDs * tralingslash default behavior entry * htmlcompress entry * scopedStyleStrategy and added links up to here * typo in trailingSlash * scoped style link * inlineStyleSheets plus code example syntax fixes up to here * class:list entries * defalt port * getStaticPaths flattening entry * internal API endpoints entry * squoosh sharp * HTTP request methods and more links to this point * shortened image service title * astro.cookies entry * final draft done!! * feat: document adapter features (#3917) Co-authored-by: Elian ☕️ Co-authored-by: Sarah Rainsberger * Update capitalisation of GET * Apply suggestions from EVERYONE's code review! Co-authored-by: Yan Thomas <61414485+Yan-Thomas@users.noreply.github.com> Co-authored-by: Kevin Zuniga Cuellar <46791833+kevinzunigacuellar@users.noreply.github.com> Co-authored-by: Bjorn Lu Co-authored-by: Erika <3019731+Princesseuh@users.noreply.github.com> Co-authored-by: Shinya Fujino * Touche, Matthew. Co-authored-by: Matthew Phillips * Every time someone has a good idea, we commit! Co-authored-by: J. B. Rainsberger * Document experimental JS API (#4234) Co-authored-by: Sarah Rainsberger * Update Firebase example to use cookies.has() (#4302) Co-authored-by: Sarah Rainsberger Co-authored-by: Reuben Tier <64310361+TheOtterlord@users.noreply.github.com> * last new entries for upgrade guide! Code freeze! * Mostly formatting catches, also build config DEPRECATED and line highlighting Co-authored-by: Emanuele Stoppa Co-authored-by: Shinya Fujino * missed a formatting correction Co-authored-by: Emanuele Stoppa * moves build config options down to deprecated section * bluwy nits! Co-authored-by: Bjorn Lu * earlier link to image upgrade advice * upgrade node version to 18.14.1 in English files only * removed examples that listed astrojs/image * Generate v3 reference docs (#4327) * deleting es/guides/assets * deleted guides/assets from nav.ts files that had it * remove mention of assets folder from project structure * Update `class:list` and astro-hash classes (#4322) Co-authored-by: Sarah Rainsberger * Remove markdown draft reference (#4354) * update endpoints * update endpoints * apply Blu's suggestions * clearer, and scarier unexperimental image assets * translatable * View transitions 3.0 changes (#4320) Co-authored-by: Nate Moore Co-authored-by: Yan Thomas <61414485+Yan-Thomas@users.noreply.github.com> Co-authored-by: Matthew Phillips Co-authored-by: Nate Moore Co-authored-by: Sarah Rainsberger * remove note to Team Docs * remove Canadian spelling * remove advice to uninstall sharp * Fix import Co-authored-by: Waxer59 <78129249+Waxer59@users.noreply.github.com> * friendly note! * ci: update reference docs (#4361) Co-authored-by: delucis Co-authored-by: Chris Swithinbank * ci: update integration docs (#4362) Co-authored-by: delucis Co-authored-by: Chris Swithinbank * add deprication note to simple objects in endpoints * correct endpoints examples for ResponseWithEncoding * backnit * put the v in the 2 Co-authored-by: 李瑞丰 * put the v in the 3 Co-authored-by: 李瑞丰 * put the v in the 3 part 2 Co-authored-by: 李瑞丰 * wording * chore: supplement `functionPerRoute` docs (#4419) * chore: supplement `functionPerRoute` docs * Update src/content/docs/en/reference/adapter-reference.mdx Co-authored-by: Sarah Rainsberger --------- Co-authored-by: Sarah Rainsberger * Add note about passing classes to children * Add some whitespace * i18n(ja): Update tutorial for v3 (#4415) Co-authored-by: Yan Thomas <61414485+Yan-Thomas@users.noreply.github.com> * i18n(es): Update `tutorial/` `V3` (#4372) * update tutorial * Update src/content/docs/es/tutorial/5-astro-api/4.mdx Co-authored-by: Paul Valladares <85648028+dreyfus92@users.noreply.github.com> --------- Co-authored-by: Paul Valladares <85648028+dreyfus92@users.noreply.github.com> Co-authored-by: Yan Thomas <61414485+Yan-Thomas@users.noreply.github.com> * i18n(ja): Update installation guides for v3 (#4414) Co-authored-by: Yan Thomas <61414485+Yan-Thomas@users.noreply.github.com> * i18n(es): Update install/v3 (#4379) Co-authored-by: Yan Thomas <61414485+Yan-Thomas@users.noreply.github.com> * ci: update integration docs (#4400) Co-authored-by: delucis Co-authored-by: Yan Thomas <61414485+Yan-Thomas@users.noreply.github.com> * i18n(es): Update `view-transitions.mdx v3` (#4370) * update page * fix broken links * fix broken note * fix typo * fix broken link * Apply suggestions from code review Co-authored-by: Paul Valladares <85648028+dreyfus92@users.noreply.github.com> --------- Co-authored-by: Paul Valladares <85648028+dreyfus92@users.noreply.github.com> Co-authored-by: Yan Thomas <61414485+Yan-Thomas@users.noreply.github.com> * i18n(pt-BR): Update remaining `reference/` pages for 3.0 (#4407) * i18n(pt-BR): Update remaining `reference/` pages for 3.0 * Apply suggestions from translation review Co-authored-by: Alisson Nunes * Update to latest changes * map -> mapa Co-authored-by: Luiz Ferraz * Better wording * Fix whitespace --------- Co-authored-by: Alisson Nunes Co-authored-by: Luiz Ferraz * i18n(ja): Update integrations-guide.mdx for v3 (#4398) * cbe66e9da9916132663631990d8615e08d8ad523 * 1703b1dfb5e4056572461252585d7642ebfe56a3 * 60f35d65a6ef99bb13fafbbc312c332213ab5a70 * i18n(ja): Update integrations-guide.mdx for v3 --------- Co-authored-by: Yan Thomas <61414485+Yan-Thomas@users.noreply.github.com> * i18n(ja): Update vercel.mdx for v3 (#4397) Co-authored-by: Yan Thomas <61414485+Yan-Thomas@users.noreply.github.com> * i18n(ja): Update styling.mdx for v3 (#4413) * aedcab56a9a83ea17ce123e2ffab1b24f8be2355 * a52460cf5f4ae3f1c96fcded06063cb10b967972 * i18n(ja): Update styling.mdx for v3 --------- Co-authored-by: Yan Thomas <61414485+Yan-Thomas@users.noreply.github.com> * i18n(ja): Update middleware.mdx for v3 (#4412) Co-authored-by: Yan Thomas <61414485+Yan-Thomas@users.noreply.github.com> * i18n(es): Update `reference/` `V3` (#4409) * update pages * Update src/content/docs/es/reference/adapter-reference.mdx * Update src/content/docs/es/reference/cli-reference.mdx * update page * Apply suggestions from code review --------- Co-authored-by: Yan Thomas <61414485+Yan-Thomas@users.noreply.github.com> * i18n(ja): Update content-collections.mdx for v3 (#4396) Co-authored-by: Yan Thomas <61414485+Yan-Thomas@users.noreply.github.com> * i18n(ja): Update project-structure.mdx for v3 (#4395) * 8104a41a883838cd300fa22705eae97d99e3c954 * 577ca11ac53006ab4e029f72c578b92c07fb3b93 * i18n(ja): Update project-structure.mdx for v3 * Update src/content/docs/ja/core-concepts/project-structure.mdx Co-authored-by: Kyosuke Nakamura --------- Co-authored-by: Kyosuke Nakamura Co-authored-by: Yan Thomas <61414485+Yan-Thomas@users.noreply.github.com> * i18n(ja): Update why-astro.mdx for v3 (#4394) Co-authored-by: Yan Thomas <61414485+Yan-Thomas@users.noreply.github.com> * i18n(es): Update `guides/` `V3` (#4383) * update pages * Apply suggestions from code review Co-authored-by: Paul Valladares <85648028+dreyfus92@users.noreply.github.com> * update styling --------- Co-authored-by: Paul Valladares <85648028+dreyfus92@users.noreply.github.com> Co-authored-by: Yan Thomas <61414485+Yan-Thomas@users.noreply.github.com> * i18n(es): Update guides/integrations-guide/ V3 (#4381) Co-authored-by: Yan Thomas <61414485+Yan-Thomas@users.noreply.github.com> * i18n(es): Update guides/backend/ & guides/deploy/ V3 (#4380) Co-authored-by: Yan Thomas <61414485+Yan-Thomas@users.noreply.github.com> * i18n(es): Update recipes/ V3 (#4373) Co-authored-by: Yan Thomas <61414485+Yan-Thomas@users.noreply.github.com> * i18n(es): Updated `concepts/` & `core-concepts/` `V3` (#4377) * update pages * apply changes --------- Co-authored-by: Yan Thomas <61414485+Yan-Thomas@users.noreply.github.com> * i18n(pt-BR): Update `view-transitions.mdx` for 3.0 (#4392) * i18n(pt-BR): Translate `upgrade-to/v3` and update smaller 3.0 changes (#4386) * i18n(pt-BR): Translate `upgrade-to/v3` and update smaller 3.0 changes * Update PT-BR tutorial * Reflect latest changes * Update to latest changes * Apply suggestions from translation review Co-authored-by: Alisson Nunes * Update to latest changes * Update to latest changes * Fix links * Fix all the broken links --------- Co-authored-by: Alisson Nunes * i18n(es): Translate `v3.mdx` `V3` (#4375) * translate sections * translate page * Apply suggestions from code review Co-authored-by: Paul Valladares <85648028+dreyfus92@users.noreply.github.com> * add changes * fix links * update page * update page * update page --------- Co-authored-by: Paul Valladares <85648028+dreyfus92@users.noreply.github.com> Co-authored-by: Yan Thomas <61414485+Yan-Thomas@users.noreply.github.com> * i18n(es): Update vercel.mdx V3 (#4423) Co-authored-by: Yan Thomas <61414485+Yan-Thomas@users.noreply.github.com> * Add v3 callout to getting started page * i18n(es): Update `images` `V3` (#4408) * translate page * Update src/content/docs/es/guides/images.mdx * Update src/content/docs/es/guides/images.mdx * update page --------- Co-authored-by: Yan Thomas <61414485+Yan-Thomas@users.noreply.github.com> * i18n(zh-cn): Upgrade to Astro v3 guide for simplified Chinese (#4353) * i18n(zh-cn): uppercase http methods & some update. * Update why-astro.mdx * Update content-collection.mdx * Update cloudflare.mdx * Update markdown-content.mdx * Update styling.mdx * Update preact.mdx * Update react.mdx & solid-js.mdx * Update cli-reference.mdx * Update adapter & configuration reference * Update directives reference * Update integrations reference * Translate missing-sharp.mdx * Remove blank line * Update endpoints * Update endpoints * Update view transitions for v3 * upgrade to v3 translated * Update src/content/docs/zh-cn/guides/styling.mdx Co-authored-by: Genteure * Update src/content/docs/zh-cn/concepts/why-astro.mdx Co-authored-by: Genteure * Update src/content/docs/zh-cn/concepts/why-astro.mdx Co-authored-by: Genteure * Update src/content/docs/zh-cn/concepts/why-astro.mdx Co-authored-by: Genteure * Update src/content/docs/zh-cn/concepts/why-astro.mdx Co-authored-by: Genteure * Update src/content/docs/zh-cn/concepts/why-astro.mdx Co-authored-by: Genteure * Update src/content/docs/zh-cn/concepts/why-astro.mdx Co-authored-by: Genteure * Update src/content/docs/zh-cn/guides/integrations-guide/preact.mdx Co-authored-by: Genteure * Update src/content/docs/zh-cn/guides/integrations-guide/preact.mdx Co-authored-by: Genteure * Update src/content/docs/zh-cn/guides/integrations-guide/preact.mdx Co-authored-by: Genteure * Update src/content/docs/zh-cn/guides/upgrade-to/v3.mdx Co-authored-by: Genteure * Update src/content/docs/zh-cn/guides/upgrade-to/v3.mdx Co-authored-by: Genteure * Update src/content/docs/zh-cn/guides/integrations-guide/react.mdx * Update src/content/docs/zh-cn/guides/integrations-guide/solid-js.mdx * Update src/content/docs/zh-cn/guides/integrations-guide/solid-js.mdx * Update src/content/docs/zh-cn/guides/integrations-guide/react.mdx * Update from v3-guide * Update src/content/docs/zh-cn/guides/integrations-guide/react.mdx Co-authored-by: Genteure * Update src/content/docs/zh-cn/guides/integrations-guide/solid-js.mdx Co-authored-by: Genteure * Update src/content/docs/zh-cn/reference/directives-reference.mdx Co-authored-by: Genteure * Update src/content/docs/zh-cn/guides/integrations-guide/preact.mdx Co-authored-by: Genteure * Update src/content/docs/zh-cn/guides/integrations-guide/react.mdx Co-authored-by: Genteure * Update src/content/docs/zh-cn/guides/integrations-guide/solid-js.mdx Co-authored-by: Genteure * Update src/content/docs/zh-cn/guides/upgrade-to/v3.mdx Co-authored-by: Genteure * Update src/content/docs/zh-cn/reference/configuration-reference.mdx Co-authored-by: Genteure * Update src/content/docs/zh-cn/reference/configuration-reference.mdx Co-authored-by: Genteure * Update src/content/docs/zh-cn/reference/integrations-reference.mdx Co-authored-by: Genteure * Update src/content/docs/zh-cn/reference/integrations-reference.mdx Co-authored-by: Genteure * Update src/content/docs/zh-cn/reference/integrations-reference.mdx Co-authored-by: Genteure * Update src/content/docs/zh-cn/guides/upgrade-to/v3.mdx Co-authored-by: Genteure * Update endpoints.mdx * Update endpoints.mdx * Update v3.mdx * Update v3.mdx * Update src/content/docs/zh-cn/guides/view-transitions.mdx Co-authored-by: Xiaoyue Lin <36526527+100gle@users.noreply.github.com> * Update src/content/docs/zh-cn/guides/upgrade-to/v3.mdx Co-authored-by: Genteure * Apply suggestions from code review Co-authored-by: Genteure * Update some from upstream * Update src/content/docs/zh-cn/reference/adapter-reference.mdx Co-authored-by: Xiaoyue Lin <36526527+100gle@users.noreply.github.com> --------- Co-authored-by: Genteure Co-authored-by: Xiaoyue Lin <36526527+100gle@users.noreply.github.com> Co-authored-by: Yan Thomas <61414485+Yan-Thomas@users.noreply.github.com> * i18n(ja): Update view-transitions.mdx for v3 (#4424) Co-authored-by: Yan Thomas <61414485+Yan-Thomas@users.noreply.github.com> * [v3 image assets] (#3739) * starting to take notes * notes re: using in Astro files * draft - images in astro files * choosing image img * move v3 upgrade guide stuff to bottom * draft - images in markdown files * draft - images in mdx * draft - images in framework components * sprinkled a few more only local images optimized * added and updates setting defaults on image component * carried over other Images page sections * split pages: images guide and other to be used elsewhere * update assets folder guidance, and some formatting * 3 migration guides - update links to image resources. NEED TO CHECK ALL CODE SAMPLES FOR USAGE * update link to public folder * link check in `ko` file * drafted upgrade to v3 content * v3 update guide - content collections advice * add info re: Sharp the default * more fine-tuning and reorg * remove assets page and sidebar entry * fixed links to old assets page in non-error pages * update netlify.toml with redirect assets to images * removes the old image integration guide and redirects to image * replaced error messages locally for checks * delete image integration guide from other languages * removed the built-in alias from code samples and explanations * remove references to assets folder entirely * added info about remote images * next pass at new image page (upgrade stuff still to do) * address links, incl fake config-ref links * another quick link hotfix in error message * change remaining links to images; incl eggregious error message hotfixes * move non-en images pages to old translations; update migrate-to links * more link fixes in astro-components; missing-image-dimensions and from- guides * draft pass at v3 upgrade stuff! * some proper Spanish Co-authored-by: Paul Valladares <85648028+dreyfus92@users.noreply.github.com> * fix long sentence * quick formatting fixes * Apply suggestions from code review Co-authored-by: Erika <3019731+Princesseuh@users.noreply.github.com> * Update src/content/docs/en/guides/images.mdx * remove too harsh info re image tag in Markdown * Apply suggestions from Yan comma review Co-authored-by: Yan Thomas <61414485+Yan-Thomas@users.noreply.github.com> * Update src/content/docs/en/guides/images.mdx * removed experimental flag from image service api config example * add code example showing removing astro integration * moved the no op image service blurb into here from v3 guide * updated from- guides with updated image assets content * i18n(zh-cn): Translate images.mdx (#4314) Co-authored-by: Camol Co-authored-by: Xiaoyue Lin <36526527+100gle@users.noreply.github.com> * Apply suggestions from morinokami code review Co-authored-by: Shinya Fujino * Everyone caught so many little fixes! Co-authored-by: Elian ☕️ Co-authored-by: Shinya Fujino Co-authored-by: Yan Thomas <61414485+Yan-Thomas@users.noreply.github.com> * extra line Co-authored-by: Shinya Fujino * another extra line Co-authored-by: Shinya Fujino * Rename and edit "4. Uninstall Sharp" * i18n(zh-cn): Update zh from upstream (#4393) * i18n(ja): Update images.mdx (#4418) Co-authored-by: Kyosuke Nakamura * i18n(pt-BR): Update `images.mdx` for 3.0 (#4411) * i18n(pt-BR): Update `images.mdx` for 3.0 * Apply suggestions from translation review Co-authored-by: Alisson Nunes * oops, missed suggestion Co-authored-by: Alisson Nunes * Update translation based on latest changes * Fix typo * Fix links --------- Co-authored-by: Alisson Nunes * Bring back ES guide changes --------- Co-authored-by: Paul Valladares <85648028+dreyfus92@users.noreply.github.com> Co-authored-by: Erika <3019731+Princesseuh@users.noreply.github.com> Co-authored-by: Yan Thomas <61414485+Yan-Thomas@users.noreply.github.com> Co-authored-by: 李瑞丰 Co-authored-by: Camol Co-authored-by: Xiaoyue Lin <36526527+100gle@users.noreply.github.com> Co-authored-by: Shinya Fujino Co-authored-by: Chris Swithinbank Co-authored-by: Elian ☕️ Co-authored-by: Kyosuke Nakamura Co-authored-by: Alisson Nunes * fix link 1 Co-authored-by: Waxer59 <78129249+Waxer59@users.noreply.github.com> * fix link 2 Co-authored-by: Waxer59 <78129249+Waxer59@users.noreply.github.com> * fix link 3 Co-authored-by: Waxer59 <78129249+Waxer59@users.noreply.github.com> * Remove `#draft-pages` link * i18n(zh-cn): Update getting-started.mdx (#4426) Co-authored-by: Yan Thomas <61414485+Yan-Thomas@users.noreply.github.com> * i18n(es): update getting started (#4427) Co-authored-by: Yan Thomas <61414485+Yan-Thomas@users.noreply.github.com> * Update PT-BR getting-started * FIX ALL THEM LINKS * fix link to experimental option * FIX LINKS PLEASE @tracker-major:./src/**/+(en|es|ja|zh-cn|pt-br)/concepts/*.mdx;./src/**/+(en|es|ja|zh-cn|pt-br)/core-concepts/*.mdx;./src/**/+(en|es|zh-cn)/guides/backend/*.mdx;./src/**/+(en|es|ja|zh-cn|pt-br)/guides/*.mdx;./src/**/+(en|es|ja|zh-cn|pt-br)/guides/deploy/*.mdx;./src/**/+(en|es|zh-cn)/guides/integrations-guide/*.mdx;./src/**/+(en|es|zh-cn)/guides/migrate-to-astro/*.mdx;./src/**/+(en|es|zh-cn|pt-br)/guides/upgrade-to/v3.mdx;./src/**/+(en|es|ja|zh-cn|pt-br)/install/*.mdx;./src/**/+(en|es|zh-cn|pt-br)/recipes/*.mdx;./src/**/+(en|es|zh-cn|pt-br)/reference/*.mdx;./src/**/+(en|es|zh-cn|pt-br)/reference/errors/*.mdx;./src/**/+(en|es|ja|zh-cn|pt-br)/tutorial/**/*.mdx;./src/**/+(en|es|zh-cn|pt-br)/getting-started.mdx; --------- Co-authored-by: Sarah Rainsberger Co-authored-by: Arsh <69170106+lilnasy@users.noreply.github.com> Co-authored-by: Matthew Phillips Co-authored-by: Emanuele Stoppa Co-authored-by: Reuben Tier <64310361+TheOtterlord@users.noreply.github.com> Co-authored-by: Chris Swithinbank Co-authored-by: = Co-authored-by: Yan Thomas <61414485+Yan-Thomas@users.noreply.github.com> Co-authored-by: Kevin Zuniga Cuellar <46791833+kevinzunigacuellar@users.noreply.github.com> Co-authored-by: Bjorn Lu Co-authored-by: Erika <3019731+Princesseuh@users.noreply.github.com> Co-authored-by: Shinya Fujino Co-authored-by: J. B. Rainsberger Co-authored-by: Nate Moore Co-authored-by: Nate Moore Co-authored-by: Waxer59 <78129249+Waxer59@users.noreply.github.com> Co-authored-by: Houston (Bot) <108291165+astrobot-houston@users.noreply.github.com> Co-authored-by: delucis Co-authored-by: 李瑞丰 Co-authored-by: Paul Valladares <85648028+dreyfus92@users.noreply.github.com> Co-authored-by: Alisson Nunes Co-authored-by: Luiz Ferraz Co-authored-by: Kyosuke Nakamura Co-authored-by: Genteure Co-authored-by: Xiaoyue Lin <36526527+100gle@users.noreply.github.com> Co-authored-by: Camol --- netlify.toml | 8 + .../de/guides/images.mdx | 8 +- .../guides => old-translations/fr}/images.mdx | 0 old-translations/ja/images.mdx | 373 +++++++++ old-translations/zh-CN/guides/images.mdx | 163 ++++ .../ar/core-concepts/astro-components.mdx | 2 +- src/content/docs/en/concepts/why-astro.mdx | 2 +- .../en/core-concepts/astro-components.mdx | 2 +- .../docs/en/core-concepts/endpoints.mdx | 119 ++- .../en/core-concepts/project-structure.mdx | 4 - src/content/docs/en/getting-started.mdx | 6 +- src/content/docs/en/guides/assets.mdx | 404 ---------- .../en/guides/backend/google-firebase.mdx | 25 +- .../docs/en/guides/content-collections.mdx | 12 +- src/content/docs/en/guides/deploy/netlify.mdx | 2 +- src/content/docs/en/guides/deploy/render.mdx | 2 +- src/content/docs/en/guides/deploy/vercel.mdx | 2 +- src/content/docs/en/guides/images.mdx | 684 ++++++++++++++-- .../docs/en/guides/integrations-guide.mdx | 10 +- .../guides/integrations-guide/cloudflare.mdx | 32 +- .../en/guides/integrations-guide/image.mdx | 750 ------------------ .../en/guides/integrations-guide/markdoc.mdx | 30 + .../docs/en/guides/integrations-guide/mdx.mdx | 2 +- .../en/guides/integrations-guide/netlify.mdx | 35 +- .../en/guides/integrations-guide/node.mdx | 2 +- .../en/guides/integrations-guide/preact.mdx | 35 + .../en/guides/integrations-guide/react.mdx | 35 +- .../en/guides/integrations-guide/solid-js.mdx | 35 + .../en/guides/integrations-guide/vercel.mdx | 40 +- .../docs/en/guides/markdown-content.mdx | 60 +- src/content/docs/en/guides/middleware.mdx | 6 +- .../guides/migrate-to-astro/from-gatsby.mdx | 29 +- .../guides/migrate-to-astro/from-nextjs.mdx | 19 +- .../guides/migrate-to-astro/from-nuxtjs.mdx | 21 +- src/content/docs/en/guides/rss.mdx | 10 +- .../docs/en/guides/server-side-rendering.mdx | 4 +- src/content/docs/en/guides/styling.mdx | 31 +- .../docs/en/guides/troubleshooting.mdx | 4 +- src/content/docs/en/guides/upgrade-to/v3.mdx | 640 +++++++++++++++ .../docs/en/guides/view-transitions.mdx | 215 ++++- src/content/docs/en/install/auto.mdx | 2 +- src/content/docs/en/install/manual.mdx | 2 +- .../docs/en/recipes/build-forms-api.mdx | 4 +- .../docs/en/recipes/call-endpoints.mdx | 8 +- src/content/docs/en/recipes/captcha.mdx | 4 +- .../docs/en/reference/adapter-reference.mdx | 246 +++++- .../docs/en/reference/api-reference.mdx | 26 +- .../docs/en/reference/cli-reference.mdx | 144 +++- .../en/reference/configuration-reference.mdx | 120 +-- .../en/reference/directives-reference.mdx | 9 +- .../docs/en/reference/error-reference.mdx | 1 + .../errors/expected-image-options.mdx | 2 +- .../en/reference/errors/expected-image.mdx | 2 +- .../en/reference/errors/image-missing-alt.mdx | 6 +- .../errors/local-image-used-wrongly.mdx | 2 +- .../reference/errors/locals-not-an-object.mdx | 2 +- .../errors/markdown-image-not-found.mdx | 2 +- .../middleware-no-data-or-next-called.mdx | 2 +- .../errors/middleware-not-aresponse.mdx | 2 +- .../errors/missing-image-dimension.mdx | 4 +- .../en/reference/errors/missing-sharp.mdx | 37 + .../errors/static-redirect-not-available.mdx | 2 +- .../errors/unsupported-image-format.mdx | 4 +- .../en/reference/image-service-reference.mdx | 11 +- .../en/reference/integrations-reference.mdx | 86 +- src/content/docs/en/tutorial/1-setup/1.mdx | 8 +- .../docs/en/tutorial/5-astro-api/4.mdx | 2 +- src/content/docs/es/concepts/why-astro.mdx | 2 +- .../es/core-concepts/astro-components.mdx | 2 +- .../docs/es/core-concepts/endpoints.mdx | 128 ++- .../es/core-concepts/project-structure.mdx | 2 +- src/content/docs/es/getting-started.mdx | 5 + src/content/docs/es/guides/assets.mdx | 375 --------- .../es/guides/backend/google-firebase.mdx | 25 +- .../docs/es/guides/content-collections.mdx | 10 + src/content/docs/es/guides/deploy/netlify.mdx | 2 +- src/content/docs/es/guides/deploy/render.mdx | 2 +- src/content/docs/es/guides/deploy/vercel.mdx | 2 +- src/content/docs/es/guides/images.mdx | 688 ++++++++++++++-- .../docs/es/guides/integrations-guide.mdx | 11 +- .../guides/integrations-guide/cloudflare.mdx | 31 +- .../es/guides/integrations-guide/image.mdx | 722 ----------------- .../docs/es/guides/integrations-guide/mdx.mdx | 2 +- .../es/guides/integrations-guide/netlify.mdx | 35 +- .../es/guides/integrations-guide/node.mdx | 2 +- .../es/guides/integrations-guide/preact.mdx | 35 + .../es/guides/integrations-guide/react.mdx | 33 + .../es/guides/integrations-guide/solid-js.mdx | 35 + .../es/guides/integrations-guide/vercel.mdx | 40 +- .../docs/es/guides/markdown-content.mdx | 56 +- src/content/docs/es/guides/middleware.mdx | 4 +- .../guides/migrate-to-astro/from-gatsby.mdx | 28 +- .../guides/migrate-to-astro/from-nextjs.mdx | 20 +- .../guides/migrate-to-astro/from-nuxtjs.mdx | 21 +- src/content/docs/es/guides/rss.mdx | 35 +- .../docs/es/guides/server-side-rendering.mdx | 6 +- src/content/docs/es/guides/styling.mdx | 31 +- .../docs/es/guides/troubleshooting.mdx | 4 +- src/content/docs/es/guides/upgrade-to/v3.mdx | 630 +++++++++++++++ .../docs/es/guides/view-transitions.mdx | 228 ++++-- src/content/docs/es/install/auto.mdx | 2 +- src/content/docs/es/install/manual.mdx | 2 +- .../docs/es/recipes/build-forms-api.mdx | 4 +- .../docs/es/recipes/call-endpoints.mdx | 8 +- src/content/docs/es/recipes/captcha.mdx | 4 +- .../docs/es/reference/adapter-reference.mdx | 237 +++++- .../docs/es/reference/api-reference.mdx | 30 +- .../docs/es/reference/cli-reference.mdx | 147 +++- .../es/reference/configuration-reference.mdx | 118 +-- .../es/reference/directives-reference.mdx | 9 +- .../docs/es/reference/error-reference.mdx | 1 + .../errors/expected-image-options.mdx | 2 +- .../es/reference/errors/expected-image.mdx | 2 +- .../es/reference/errors/image-missing-alt.mdx | 6 +- .../errors/local-image-used-wrongly.mdx | 2 +- .../reference/errors/locals-not-an-object.mdx | 2 +- .../errors/markdown-image-not-found.mdx | 2 +- .../middleware-no-data-or-next-called.mdx | 2 +- .../errors/middleware-not-aresponse.mdx | 2 +- .../errors/missing-image-dimension.mdx | 9 +- .../es/reference/errors/missing-sharp.mdx | 27 + .../errors/static-redirect-not-available.mdx | 4 +- .../errors/unsupported-image-format.mdx | 4 +- .../es/reference/image-service-reference.mdx | 11 +- .../es/reference/integrations-reference.mdx | 86 +- src/content/docs/es/tutorial/1-setup/1.mdx | 8 +- .../docs/es/tutorial/5-astro-api/4.mdx | 4 +- .../fr/core-concepts/astro-components.mdx | 2 +- src/content/docs/ja/concepts/why-astro.mdx | 2 +- .../ja/core-concepts/astro-components.mdx | 2 +- .../ja/core-concepts/project-structure.mdx | 10 +- .../docs/ja/guides/content-collections.mdx | 14 +- src/content/docs/ja/guides/deploy/vercel.mdx | 4 + src/content/docs/ja/guides/images.mdx | 734 ++++++++++++----- .../docs/ja/guides/integrations-guide.mdx | 44 +- src/content/docs/ja/guides/middleware.mdx | 4 +- src/content/docs/ja/guides/styling.mdx | 62 +- .../docs/ja/guides/view-transitions.mdx | 210 ++++- src/content/docs/ja/install/auto.mdx | 2 +- src/content/docs/ja/install/manual.mdx | 2 +- src/content/docs/ja/tutorial/1-setup/1.mdx | 8 +- .../docs/ja/tutorial/5-astro-api/4.mdx | 2 +- .../ko/core-concepts/astro-components.mdx | 2 +- .../ko/core-concepts/project-structure.mdx | 2 +- src/content/docs/pt-br/concepts/why-astro.mdx | 2 +- .../pt-br/core-concepts/astro-components.mdx | 2 +- .../docs/pt-br/core-concepts/endpoints.mdx | 127 ++- .../pt-br/core-concepts/project-structure.mdx | 2 +- src/content/docs/pt-br/getting-started.mdx | 6 +- .../docs/pt-br/guides/content-collections.mdx | 13 +- .../docs/pt-br/guides/deploy/netlify.mdx | 2 +- .../docs/pt-br/guides/deploy/render.mdx | 2 +- .../docs/pt-br/guides/deploy/vercel.mdx | 2 +- src/content/docs/pt-br/guides/images.mdx | 688 ++++++++++++++-- .../docs/pt-br/guides/integrations-guide.mdx | 10 +- .../docs/pt-br/guides/markdown-content.mdx | 61 +- src/content/docs/pt-br/guides/middleware.mdx | 4 +- src/content/docs/pt-br/guides/rss.mdx | 10 +- .../pt-br/guides/server-side-rendering.mdx | 4 +- src/content/docs/pt-br/guides/styling.mdx | 32 +- .../docs/pt-br/guides/troubleshooting.mdx | 4 +- .../docs/pt-br/guides/upgrade-to/v3.mdx | 639 +++++++++++++++ .../docs/pt-br/guides/view-transitions.mdx | 212 ++++- src/content/docs/pt-br/install/auto.mdx | 2 +- src/content/docs/pt-br/install/manual.mdx | 2 +- .../docs/pt-br/recipes/call-endpoints.mdx | 8 +- .../pt-br/reference/adapter-reference.mdx | 237 +++++- .../docs/pt-br/reference/api-reference.mdx | 26 +- .../docs/pt-br/reference/cli-reference.mdx | 144 +++- .../reference/configuration-reference.mdx | 104 +-- .../pt-br/reference/directives-reference.mdx | 8 +- .../docs/pt-br/reference/error-reference.mdx | 1 + .../errors/expected-image-options.mdx | 2 +- .../pt-br/reference/errors/expected-image.mdx | 2 +- .../reference/errors/image-missing-alt.mdx | 6 +- .../errors/markdown-image-not-found.mdx | 2 +- .../errors/missing-image-dimension.mdx | 4 +- .../errors/static-redirect-not-available.mdx | 4 +- .../errors/unsupported-image-format.mdx | 4 +- src/content/docs/pt-br/tutorial/1-setup/1.mdx | 8 +- .../docs/pt-br/tutorial/5-astro-api/4.mdx | 2 +- src/content/docs/zh-cn/concepts/why-astro.mdx | 43 +- .../zh-cn/core-concepts/astro-components.mdx | 2 +- .../docs/zh-cn/core-concepts/endpoints.mdx | 119 ++- .../zh-cn/core-concepts/project-structure.mdx | 2 +- src/content/docs/zh-cn/getting-started.mdx | 5 + .../zh-cn/guides/backend/google-firebase.mdx | 25 +- .../docs/zh-cn/guides/content-collections.mdx | 12 +- .../docs/zh-cn/guides/deploy/netlify.mdx | 2 +- .../docs/zh-cn/guides/deploy/render.mdx | 2 +- .../docs/zh-cn/guides/deploy/vercel.mdx | 2 +- src/content/docs/zh-cn/guides/images.mdx | 696 ++++++++++++++-- .../docs/zh-cn/guides/integrations-guide.mdx | 10 +- .../guides/integrations-guide/cloudflare.mdx | 30 +- .../zh-cn/guides/integrations-guide/image.mdx | 730 ----------------- .../guides/integrations-guide/markdoc.mdx | 26 + .../zh-cn/guides/integrations-guide/mdx.mdx | 2 +- .../guides/integrations-guide/netlify.mdx | 35 +- .../zh-cn/guides/integrations-guide/node.mdx | 2 +- .../guides/integrations-guide/preact.mdx | 35 + .../zh-cn/guides/integrations-guide/react.mdx | 33 + .../guides/integrations-guide/solid-js.mdx | 35 + .../guides/integrations-guide/vercel.mdx | 34 +- .../docs/zh-cn/guides/markdown-content.mdx | 57 +- src/content/docs/zh-cn/guides/middleware.mdx | 4 +- .../guides/migrate-to-astro/from-gatsby.mdx | 32 +- .../guides/migrate-to-astro/from-nextjs.mdx | 25 +- .../guides/migrate-to-astro/from-nuxtjs.mdx | 23 +- src/content/docs/zh-cn/guides/rss.mdx | 10 +- .../zh-cn/guides/server-side-rendering.mdx | 4 +- src/content/docs/zh-cn/guides/styling.mdx | 31 +- .../docs/zh-cn/guides/troubleshooting.mdx | 4 +- .../docs/zh-cn/guides/upgrade-to/v3.mdx | 630 +++++++++++++++ .../docs/zh-cn/guides/view-transitions.mdx | 232 ++++-- src/content/docs/zh-cn/install/auto.mdx | 2 +- src/content/docs/zh-cn/install/manual.mdx | 2 +- .../docs/zh-cn/recipes/build-forms-api.mdx | 2 +- .../docs/zh-cn/recipes/call-endpoints.mdx | 8 +- src/content/docs/zh-cn/recipes/captcha.mdx | 4 +- .../zh-cn/reference/adapter-reference.mdx | 247 +++++- .../docs/zh-cn/reference/api-reference.mdx | 24 +- .../docs/zh-cn/reference/cli-reference.mdx | 145 +++- .../reference/configuration-reference.mdx | 112 +-- .../zh-cn/reference/directives-reference.mdx | 9 +- .../docs/zh-cn/reference/error-reference.mdx | 1 + .../errors/expected-image-options.mdx | 2 +- .../zh-cn/reference/errors/expected-image.mdx | 2 +- .../reference/errors/image-missing-alt.mdx | 7 +- .../errors/local-image-used-wrongly.mdx | 2 +- .../reference/errors/locals-not-an-object.mdx | 2 +- .../errors/markdown-image-not-found.mdx | 2 +- .../middleware-no-data-or-next-called.mdx | 2 +- .../errors/middleware-not-aresponse.mdx | 2 +- .../errors/missing-image-dimension.mdx | 5 +- .../zh-cn/reference/errors/missing-sharp.mdx | 26 + .../errors/static-redirect-not-available.mdx | 2 +- .../errors/unsupported-image-format.mdx | 4 +- .../reference/image-service-reference.mdx | 11 +- .../reference/integrations-reference.mdx | 84 +- src/content/docs/zh-cn/tutorial/1-setup/1.mdx | 8 +- .../docs/zh-cn/tutorial/5-astro-api/4.mdx | 2 +- src/i18n/en/nav.ts | 5 +- src/i18n/es/nav.ts | 5 +- src/i18n/it/nav.ts | 3 +- src/i18n/ja/nav.ts | 5 +- src/i18n/ko/nav.ts | 2 +- src/i18n/pl/nav.ts | 2 +- src/i18n/pt-br/nav.ts | 6 +- src/i18n/ru/nav.ts | 3 +- src/i18n/zh-cn/nav.ts | 5 +- 250 files changed, 10306 insertions(+), 5467 deletions(-) rename {src/content/docs => old-translations}/de/guides/images.mdx (99%) rename {src/content/docs/fr/guides => old-translations/fr}/images.mdx (100%) create mode 100644 old-translations/ja/images.mdx create mode 100644 old-translations/zh-CN/guides/images.mdx delete mode 100644 src/content/docs/en/guides/assets.mdx delete mode 100644 src/content/docs/en/guides/integrations-guide/image.mdx create mode 100644 src/content/docs/en/guides/upgrade-to/v3.mdx create mode 100644 src/content/docs/en/reference/errors/missing-sharp.mdx delete mode 100644 src/content/docs/es/guides/assets.mdx delete mode 100644 src/content/docs/es/guides/integrations-guide/image.mdx create mode 100644 src/content/docs/es/guides/upgrade-to/v3.mdx create mode 100644 src/content/docs/es/reference/errors/missing-sharp.mdx create mode 100644 src/content/docs/pt-br/guides/upgrade-to/v3.mdx delete mode 100644 src/content/docs/zh-cn/guides/integrations-guide/image.mdx create mode 100644 src/content/docs/zh-cn/guides/upgrade-to/v3.mdx create mode 100644 src/content/docs/zh-cn/reference/errors/missing-sharp.mdx diff --git a/netlify.toml b/netlify.toml index 0843f1dfac07a..e4174d26a996d 100644 --- a/netlify.toml +++ b/netlify.toml @@ -83,6 +83,14 @@ from = "/:lang/guides/client-side-routing" to = "/:lang/guides/view-transitions" + [[redirects]] + from = "/:lang/guides/assets" + to = "/:lang/guides/images" + + [[redirects]] + from = "/:lang/guides/integrations-guide/image" + to = "/:lang/guides/images" + [[redirects]] from = "/:lang/migration/0.21.0" to = "/:lang/guides/upgrade-to/v1" diff --git a/src/content/docs/de/guides/images.mdx b/old-translations/de/guides/images.mdx similarity index 99% rename from src/content/docs/de/guides/images.mdx rename to old-translations/de/guides/images.mdx index e561b6b44b20c..693194dc9210e 100644 --- a/src/content/docs/de/guides/images.mdx +++ b/old-translations/de/guides/images.mdx @@ -9,7 +9,7 @@ import Since from '~/components/Since.astro'; Astro bietet dir verschiedene Möglichkeiten, Bilder auf deiner Website zu verwenden, ganz gleich, ob sie lokal in deinem Projekt gespeichert sind, auf anderen Quellen verlinkt werden oder in einem CMS oder CDN gespeichert sind! :::note[Assets verwenden (Experimentell)] -Die experimentelle Asset-Unterstützung wurde in `astro@2.1.0` hinzugefügt. Wenn du die Unterstützung für Assets aktiviert hast, findest du weitere Informationen in der [Asset-Anleitung (Experimentell)](/de/guides/assets/). +Die experimentelle Asset-Unterstützung wurde in `astro@2.1.0` hinzugefügt. Wenn du die Unterstützung für Assets aktiviert hast, findest du weitere Informationen in der [Asset-Anleitung (Experimentell)](/de/guides/images/). **Einige der folgenden Ratschläge sind nicht mit der experimentellen Flag kompatibel.** ::: @@ -38,7 +38,7 @@ import rocket from '../images/rocket.svg'; Du kannst die Standard Markdown `![]()` Syntax oder die Standard HTML ``-Tags in deinen `.md`-Dateien für Bilder verwenden, die sich in deinem `public/`-Ordner befinden, oder für Remote-Bilder auf einem anderen Server. -Wenn du deine Bilder nicht in `public/` speichern kannst, empfehlen wir, die [experimentelle Unterstützung für Assets](/de/guides/assets/) zu aktivieren oder das Dateiformat `.mdx` zu verwenden, mit dem du importierte Komponenten mit einer Markdown-ähnlichen Syntax kombinieren kannst. Verwende die [MDX-Integration](/de/guides/integrations-guide/mdx/), um Astro-Unterstützung für MDX hinzuzufügen. +Wenn du deine Bilder nicht in `public/` speichern kannst, empfehlen wir, die [experimentelle Unterstützung für Assets](/de/guides/images/) zu aktivieren oder das Dateiformat `.mdx` zu verwenden, mit dem du importierte Komponenten mit einer Markdown-ähnlichen Syntax kombinieren kannst. Verwende die [MDX-Integration](/de/guides/integrations-guide/mdx/), um Astro-Unterstützung für MDX hinzuzufügen. ```md @@ -121,7 +121,7 @@ Das Attribut `src` ist **relativ zum öffentlichen Ordner**. In Markdown kannst ### `src/assets/` (experimentell) -In der Anleitung [Assets (Experimentell)](/de/guides/assets/) kannst du nachlesen, wie du den Ordner `/assets/` experimentell nutzen kannst. +In der Anleitung [Assets (Experimentell)](/de/guides/images/) kannst du nachlesen, wie du den Ordner `/assets/` experimentell nutzen kannst. Dazu musst du deine bestehenden Bilder aktualisieren, die aktuelle Astro-Bildintegration entfernen und zusätzliche manuelle Änderungen vornehmen, um einige der neuen Funktionen zu nutzen. @@ -132,7 +132,7 @@ Die offizielle Bild-Integration von Astro bietet zwei verschiedene Astro-Kompone Nach der [Installation von `@astrojs/image`](/de/guides/integrations-guide/image/#installation) kannst du diese beiden Komponenten überall dort verwenden, wo du Astro-Komponenten verwenden kannst: in `.astro`- und `.mdx`-Dateien. :::note[Inkompatibel mit Assets] -Wenn du die experimentelle Asset-Unterstützung aktiviert hast, musst du die offizielle Integration deinstallieren. Weitere Informationen findest du im [Assets (Experimental) Guide](/de/guides/assets/). +Wenn du die experimentelle Asset-Unterstützung aktiviert hast, musst du die offizielle Integration deinstallieren. Weitere Informationen findest du im [Assets (Experimental) Guide](/de/guides/images/). ::: ### `` diff --git a/src/content/docs/fr/guides/images.mdx b/old-translations/fr/images.mdx similarity index 100% rename from src/content/docs/fr/guides/images.mdx rename to old-translations/fr/images.mdx diff --git a/old-translations/ja/images.mdx b/old-translations/ja/images.mdx new file mode 100644 index 0000000000000..54c53602c96e2 --- /dev/null +++ b/old-translations/ja/images.mdx @@ -0,0 +1,373 @@ +--- +title: 画像 +description: Astroでの画像の取り扱いを学びます +i18nReady: true +--- +import Since from '~/components/Since.astro'; + +Astroは、プロジェクト内に保存されている画像やリモート上にリンクされている画像、CMSやCDNに保存されている画像をサイト上で表示するために様々な手段を提供しています。 + +:::note[アセットの活用 (実験的)] +実験的なアセットサポートが`astro@2.1.0`に追加されました。アセットサポートを有効にした場合、追加情報については [アセット (実験的) ガイド](/ja/guides/images/) を参照してください。 + +**以下のアドバイスの中には、アセットのフラグを有効にした場合に互換性がなくなるものもあります。** +::: + + +### `.astro`ファイル内 + +astroでは``要素を使って画像を表示でき、HTML画像属性をすべてサポートしています。 + +`src` 属性は必須で、その書式は画像の保存場所や、アセットの実験的なサポートを有効にしているかどうかによって異なります： + +```astro title="src/pages/index.astro" +--- +import rocket from '../images/rocket.svg'; +--- + +Astro + + +A starry night sky. + + +A rocketship in space. +``` + +### Markdownファイル内 + +`.md`ファイル内では標準的な`![]()`構文や``タグを記載することで`public/`フォルダや、他サーバー上にあるリモート画像を表示できます。 + +もし`public/`に画像を保存できない場合、[アセットの実験的なサポート](/ja/guides/images/)を有効にするか、インポートされたコンポーネントをMarkdownのような構文と組み合わせて使える`.mdx`ファイルフォーマットを利用することをお勧めします。AstroにMDXのサポートを追加するには[MDX インテグレーション](/ja/guides/integrations-guide/mdx/)を利用します。 + +```md + + +# Markdownページ + + +![A starry night sky.](/assets/stars.png) +A starry night sky. + + +![Astro](https://docs.astro.build/assets/logomark-light.png) +Astro +``` + +### MDXファイル内 + +`.mdx`ファイル内では標準的なMarkdown文法`![]()`やJSXの``タグを使って`public/`フォルダーやリモートサーバーの画像を表示できます。 + +加えて、Astroコンポーネントのようにプロジェクトの`src/`ディレクトリに保存されている画像をインポートして利用できます。 + +```mdx title="src/pages/post-1.mdx" + +import rocket from '../images/rocket.svg'; + +# MDXページ + +// src/images/rocket.svgに保存されたローカル画像 +A rocketship in space. + +// public/assets/stars.pngに保存されたローカル画像 +![A starry night sky.](/assets/stars.png) +A starry night sky. + +// 他サーバー上にあるリモート画像 +![Astro](https://docs.astro.build/assets/logomark-light.png) +Astro +``` + +### UIフレームワークコンポーネント内 + +[UIフレームコンポーネント](/ja/core-concepts/framework-components/)(ReactやSvelteなど)に画像を追加する場合、そのコンポーネントのフレームワークに沿った画像の構文を利用します。 + +## 画像の保存場所 + +### `src/` + +`src`に保存された画像は、コンポーネント(`.astro`や`.mdx`、そして他のUIフレームワーク)から利用できますが、Markdownファイルからは利用できません。 + +Markdownファイルを利用する必要がある場合、[`public/`へ配置する](#public)か[CMSやCDN上の画像を利用](#cmsやcdn上の画像利用)することをお勧めします。 + +画像を**相対ファイルパス**または[importエイリアス](/ja/guides/aliases/)を利用してコンポーネントファイル内でインポートし、画像の`src`属性として利用できます。 + + +```astro +--- +// src/pages/index.astro + +// `src/images/`内の画像へアクセスします。 +import logo from '../images/logo.png'; +--- +Astro +``` + +### `public/` + +`public/`に保存された画像はコンポーネント(`.astro`や`.mdx`、そして他のUIフレームワーク)とMarkdownファイルからも利用できます。 + +しかし、`/public`ディレクトリにあるファイルは処理されずにそのまま提供、コピーされます。Markdownファイル以外で画像を利用する場合はAstroが画像を変換・最適化・バンドルできるように、可能な限りローカル画像は`src`に保存するのをお勧めします。 + +`src`属性は**publicフォルダからの相対パス**です。Markdownでは`![]()`の表記を利用できます。 + +```astro title="src/pages/index.astro" +--- +// `public/images/`内の画像へアクセスします。 +--- + +``` + +### `src/assets/` (実験的) + +`/assets/` フォルダの実験的な使用を有効にするには、[アセット(実験的)](/ja/guides/images/)ガイドを参照してください。 + +その場合、既存の画像を更新し、現在のAstro画像インテグレーションを削除する必要があります。また、Astroの新機能の一部を利用するためには、さらに手動での変更が必要になります。 + +## Astro画像インテグレーション + +Astro公式の画像のインテグレーションは、最適化された画像をレンダリングするためのAstroコンポーネント``と``を提供しています。これらのコンポーネントは全ての静的サイトと、[一部のサーバーサイドレンダリングのデプロイホスト](/ja/guides/integrations-guide/image/#installation)をサポートしています。 + +[`@astrojs/image`のインストール](/ja/guides/integrations-guide/image/#installation)で、`.astro`と`.mdx`などのAstroコンポーネントを利用できるファイル内でこの2つのコンポーネントを利用できます。 + +:::note[アセットの互換性がない] +アセットの実験的なサポートを有効にしている場合は、公式インテグレーションをアンインストールする必要があります。詳細については、[アセット (実験的) ガイド](/ja/guides/images/) を参照してください。 +::: + +### `` + +Astroの[``コンポーネント](/ja/guides/integrations-guide/image/#image-)は1つの画像を最適化し、幅・高さ・アスペクト比を指定できます。また特定の出力フォーマットに画像を変換できます。 + +このコンポーネントはディスプレイ間で一貫したサイズを維持したい画像や、画質を厳密にコントロールしたいもの(ロゴなど)に有効です。 + +レスポンシブ画像の場合やアートディレクションの場合は、代わりに``コンポーネントを利用します。 + +#### リモート画像 + +(必須属性: [`src`](/ja/guides/integrations-guide/image/#src)・[`alt`](/ja/guides/integrations-guide/image/#alt)・[`format`](/ja/guides/integrations-guide/image/#format)・サイズ) + +``コンポーネントの`src`属性に完全なURLを渡し、`alt`の値を含めます。 + +``コンポーネントはリモート画像のオリジナルのファイルフォーマットを検知できないため、リモート画像を変換するために出力する`format`(pngやavifなど)を指定する必要があります。 + +``コンポーネントはリモート画像のサイズを認識しないので、コンテンツレイアウトのシフトを回避するために[`width`](/ja/guides/integrations-guide/image/#width)と[`height`](/ja/guides/integrations-guide/image/#height)、またはどちらか1つのサイズと[`aspectRatio`](/ja/guides/integrations-guide/image/#aspectratio)を指定する必要があります。 + +[その他の属性](/ja/guides/integrations-guide/image/#image-)はオプションです。 + +#### `src/`のローカル画像 + +(必須属性: [`src`](/ja/guides/integrations-guide/image/#src)・[`alt`](/ja/guides/integrations-guide/image/#alt)) + +フロントマターで画像をインポートして、``コンポーネントの`src`属性へ直接渡します。 + +`alt`は必須ですが[その他の属性](/ja/guides/integrations-guide/image/#image-)はオプションで、指定が無ければ画像ファイルのプロパティがデフォルト値として設定されます。 + +#### `public/`のローカル画像 + +(必須属性: [`src`](/ja/guides/integrations-guide/image/#src)・[`alt`](/ja/guides/integrations-guide/image/#alt)・[`format`](/ja/guides/integrations-guide/image/#format)・サイズ) + +コンポーネントの`src`属性に公開フォルダからの相対パスを渡し、`alt`に値を含めます。 + +これはリモート画像として扱われ、[`width`](/ja/guides/integrations-guide/image/#width)と[`height`](/ja/guides/integrations-guide/image/#height)の両方の属性か、またはどちらか1つのサイズと[`aspectRatio`](/ja/guides/integrations-guide/image/#aspectratio)属性が必須です。 + +画像を変換するための`format`属性値が必要です。(pngやavifなど) + +[その他の属性](/ja/guides/integrations-guide/image/#image-)はオプションです。 + +元画像は`public/`にある他のファイルと同じくビルドフォルダーにそのままコピーされ、Astroの画像インテグレーションは最適化された画像を返します。 + +#### 例 + +```astro +--- +// src/pages/index.astro +import { Image } from '@astrojs/image/components'; +import localImage from "../assets/logo.png"; +const remoteImage = "https://picsum.photos/id/957/300/200.jpg"; +const localAlt = "The Astro Logo"; +const remoteAlt = "A low-angle view of a forest during the daytime"; +--- + + +{localAlt} + + +{localAlt} + + +{remoteAlt} + + +{localAlt}/ +{remoteAlt}/ + + +{localAlt}/ +{remoteAlt}/ + + +{localAlt}/ + + +A happy penguin +``` + +### ` ` + +Astroの[``コンポーネント](/ja/guides/integrations-guide/image/#picture-)は複数の画像サイズ・フォーマット・レイアウトなど、サイト上でレスポンシブな画像を提供するために利用できます。 + +画面サイズや帯域幅に基づいて、画像に最適なサイズ、解像度、ファイルタイプを利用ユーザーのブラウザに任せることができます。また、メディアクエリに基づいてブラウザに従わせるルールを指定できます。 + +このコンポーネントは、ユーザーが様々な画面サイズで見る画像を最適化するためや、アートディレクションに最適です。 + +:::tip +[レスポンシブ画像とアートディレクション](https://developer.mozilla.org/ja/docs/Learn/HTML/Multimedia_and_embedding/Responsive_images#%E3%82%A2%E3%83%BC%E3%83%88%E3%83%87%E3%82%A3%E3%83%AC%E3%82%AF%E3%82%B7%E3%83%A7%E3%83%B3)の詳細はMDNのガイドを参照してください。 +::: + +#### リモート画像 + +(必須属性: [`src`](/ja/guides/integrations-guide/image/#src-1)・[`widths`](/ja/guides/integrations-guide/image/#widths)・[`sizes`](/ja/guides/integrations-guide/image/#sizes)・[`alt`](/ja/guides/integrations-guide/image/#alt-1)・[`aspectRatio`](/ja/guides/integrations-guide/image/#aspectratio-1)) + +完全なURLを``コンポーネントの`src`属性へ渡します。 + +またビルド時に正しい高さを計算できるようにリモート画像は`aspectRatio`も必要になります。 + +画像の幅と画面サイズに関する指示をコンポーネントに与える必要がありますが、[その他の属性](/ja/guides/integrations-guide/image/#picture-)はオプションです。 + +[`formats`](/ja/guides/integrations-guide/image/#formats)は必須ではありませんが、リモート画像の元のフォーマットが不明となりデフォルト値は含まれません。何も指定が無ければ、`webp`と`avif`だけが含まれます。 + +#### ローカル画像 + +(必須属性: [`src`](/ja/guides/integrations-guide/image/#src-1)・[`widths`](/ja/guides/integrations-guide/image/#widths)・[`sizes`](/ja/guides/integrations-guide/image/#sizes)・[`alt`](/ja/guides/integrations-guide/image/#alt-1)) + +フロントマターで画像をインポートして、``コンポーネントの`src`属性へ直接渡します。 + +画像の幅と画像のガイダンスをコンポーネントへ渡す必要がありますが、[その他の属性](/ja/guides/integrations-guide/image/#picture-)はオプションです。 + +``コンポーネントの[`formats`](/ja/guides/integrations-guide/image/#formats)に指定がなければ、デフォルト値は元の画像のフォーマットに加えて`avif`と`webp`が含まれます。 + +#### `public/`の画像 + +(必須属性: [`src`](/ja/guides/integrations-guide/image/#src-1)・[`widths`](/ja/guides/integrations-guide/image/#widths)・[`sizes`](/ja/guides/integrations-guide/image/#sizes)・[`alt`](/ja/guides/integrations-guide/image/#alt-1)・[`aspectRatio`](/ja/guides/integrations-guide/image/#aspectratio-1)) + +コンポーネントの`src`属性にはpublicフォルダからの相対パスを渡し、`alt`の値を必要とします。 + +画像はリモート画像として扱われるため、ビルド時に正しい高さを計算できるように`aspectRatio`の指定が必要です。 + +画像の幅と画面サイズに関する指示をコンポーネントに与える必要がありますが、[その他の属性](/ja/guides/integrations-guide/image/#picture-)はオプションです。 + +[`formats`](/ja/guides/integrations-guide/image/#formats)は必須ではありませんが、`public/`フォルダにある画像の元のフォーマットが不明となりデフォルト値は含まれません。何も指定が無ければ、`webp`と`avif`だけが含まれます。 + +元の画像は`public/`にある他のファイルと同じくビルドフォルダーにそのままコピーされ、Astroの画像インテグレーションは最適化された画像を返します。 + +#### 例 + +```astro +--- +import { Picture } from '@astrojs/image/components'; +import localImage from '../assets/logo.png'; +const remoteImage = 'https://docs.astro.build/assets/full-logo-light.png'; +--- + + + + + + + + + + + + + +``` + +### MDXでの利用 + +`.mdx`ファイル内では、インポートとエクスポートを通して``と``が画像の`src`を受け取ることができます。 + +```mdx +// src/pages/index.mdx + +import { Image, Picture } from '@astrojs/image/components'; +import rocket from '../assets/rocket.png'; +export const logo = 'https://docs.astro.build/assets/full-logo-light.png'; + +Outer space. +Spaceship approaching the moon. + + +``` + +### デフォルト値を設定する + +現在、``と``コンポーネントにデフォルト値を指定する方法はありません。必須属性はそれぞれのコンポーネントに設定する必要があります。 + +代わりの方法として、再利用できるよう他のAstroコンポーネントでこれらのコンポーネントをラッピングできます。例えば、以下のようにブログ記事画像をコンポーネントとして作成できます。 + +```astro title="src/components/BlogPostImage.astro" +--- +import { Picture } from '@astrojs/image/components'; + +const {src, ...attrs} = Astro.props; +--- + + + +``` + +### 画像インテグレーションで``を使う + +公式の画像インテグレーションにより、画像のインポートはソース文字列ではなくオブジェクトを返すように変更されます。このオブジェクトは、インポートされたファイルから派生した以下のプロパティを持ちます。 +```ts +{ + src: string; + width: number; + height: number; + format: 'avif' | 'gif' | 'heic' | 'heif' | 'jpeg' | 'jpg' | 'png' | 'tiff' | 'webp'; +} +``` + +画像インテグレーションがインストールされている場合は、``を使用する際にオブジェクトの`src`プロパティを参照してください。 + +```astro ".src" +--- +import rocket from '../images/rocket.svg'; +--- +A rocketship in space. +``` + +あるいは、インポートに`?url`を追加して、ソース文字列を返すように指示する。 + +```astro "?url" +--- +import rocket from '../images/rocket.svg?url'; +--- +A rocketship in space. +``` + +## CMSやCDN上の画像利用 + +CDNネットワーク上の画像をAstroで利用するには、画像の完全なURLを``タグやMarkdownの`src`属性として利用します。 + +代わりに、もしCDNがNode.js SDKを提供している場合はプロジェクトでSDKを利用できます。例えば、[CloudinaryのSDK](https://cloudinary.com/documentation/node_integration)は適切な`src`を利用して``タグを生成できます。 + +Astroの画像インテグレーションの[``を用いた外部画像](#リモート画像)や[``](#リモート画像-1)コンポーネントを利用するには、リモート画像を扱うための適切なサイズとフォーマットを指定する必要があります。 + +## Altテキスト + +画像が誰も同じように見えるわけではないため、画像を扱う上でアクセシビリティは特に重要になります。`alt`属性は画像に[Altテキストによる記述](https://www.w3.org/WAI/tutorials/images/)を与えます。 + +この属性は画像インテグレーションの``と``コンポーネントには必須です。Altテキストが指定されていない場合これらのコンポーネントはエラーを投げます。 + +画像が単なる飾り(ページの理解に貢献しない画像)の場合、スクリーンリーダーが画像を無視するように`alt=""`を設定します。 + +## コミュニテーインテグレーション + +公式の[`@astrojs/image`](/ja/guides/integrations-guide/image/)インテグレーションに加え、Astroプロジェクトで画像の最適化や処理を行うためのサードパーティー製の[コミュニティー画像インテグレーション](https://astro.build/integrations?search=images)がいくつかあります。 diff --git a/old-translations/zh-CN/guides/images.mdx b/old-translations/zh-CN/guides/images.mdx new file mode 100644 index 0000000000000..a71300741771a --- /dev/null +++ b/old-translations/zh-CN/guides/images.mdx @@ -0,0 +1,163 @@ +--- +title: 图片 +description: 学习如何在 Astro 项目中包含图片。 +i18nReady: true +--- +import Since from '~/components/Since.astro'; + + +在 Astro 项目中，有很多种在网站中使用图片的方式。无论是用存储在项目中的图片，还是链接外部图片，亦或从像 CMS（内容管理系统）或 CDN（内容分发网络）这样的地方加载图片，都没问题！ + +:::note[`astro:assets` (Experimental - coming in v3.0)] +实验性 `astro:assets` 模块将在 `astro@3.0` 中默认启用. + +请按照 [资源（实验性）使用指南](/zh-cn/guides/images/) 开始使用新的图片解决方案！ + +**下面的一些建议可能与实验性标志不兼容。如果你正在使用 `astro:assets` 请参考资源页面。** +::: + +### 在 `.astro` 文件中 + +你可以在 `.astro` 文件中使用标准的 HTML `` 或 `` 元素来展示图片，同时也支持所有 HTML 图片属性。 + +src 属性是必需的，其格式取决于图像的存储位置以及你是否启用了对资源的实验性支持： + +```astro +--- +// src/pages/index.astro +import rocket from '../images/rocket.svg'; +--- + +Astro + + +一片繁星闪烁的夜空。 + + +外空中的一架火箭。 +``` + +### 在 Markdown 文件中 + +可以在 `.md` 文件中使用 Markdown 标准语法 `![]()`，或 HTML 标准语法 `` 标签，来调用位于 `public/` 文件夹下或其它服务器上的图片。 + +如果你无法将图片保留在 `public/` 中，我们建议启用 [资源的实验性支持](/zh-cn/guides/images/), 或使用 `.mdx` 文件格式，该格式允许你将导入的组件与类似 Markdown 的语法结合起来。使用 [MDX 集成](/zh-cn/guides/integrations-guide/mdx/) 向 Astro 添加对 MDX 的支持。 +```md + + +# 我的 Markdown 页面 + + +![一片繁星闪烁的夜空。](/assets/stars.png) +一片繁星闪烁的夜空。 + + +![Astro](https://docs.astro.build/assets/logomark-light.png) +Astro +``` + +### 在 MDX 文件中 + +你可以在 .mdx 文件中使用标准 Markdown `![]()` 语法或 JSX 的 `` 标签来显示 `public/ ` 文件夹或远程服务器中的图片。 + +此外，你也可以导入和使用位于项目 `src/` 目录中的图像，就像在 Astro 组件中一样。 + + +```mdx title="src/pages/post-1.mdx" + +import rocket from '../images/rocket.svg'; + +# My MDX Page + +// 存放在项目中 src/images/rocket.svg 路径的图片 +外空中的一架火箭。 + +// 存放在项目中 public/assets/stars.png 路径的图片 +![一片繁星闪烁的夜空。](/assets/stars.png) +一片繁星闪烁的夜空。 + +// 位于其它服务器上的图片 +![Astro](https://docs.astro.build/assets/logomark-light.png) +Astro +``` + +### UI 框架中的组件 + +当在 [UI 框架组件](/zh-cn/core-concepts/framework-components/)（例如 React、Svelte）中添加图像时，请使用适合该框架的图像语法。 + + + +## 存放图片的位置 + +### `src/` + +存储在 `src/`中的图像可以由组件（`.astro`，`.mdx`和其他 UI 框架）使用，但不能在 Markdown 文档中使用。 + +如果您必须使用 Markdown 文档，我们建议你将图像保存在 ['public/']（#public） 中或 [远程](#使用-cms-或-cdn-上的图片) 存储他们。 + +从任何组件文档中的 **相对文档路径** 或 [导入别名](/zh-cn/guides/aliases/) 导入它们，然后像使用 `src`属性一样使用。 + +```astro +--- +// src/pages/index.astro + +// Access images in `src/images/` +import logo from '../images/logo.png'; +--- +Astro 的图标 +``` + +### `public/` + +存储在 `public/` 中的图像可以被组件（`.astro`，`.mdx`和其他UI框架）和Markdown文档使用。 + +然而，位于 `/public` 目录中的文件始终按原样提供或复制，不进行任何处理。如果你在 Markdown 文件之外使用图像，我们建议尽可能将本地图像保存在 `src/` 中，以便 Astro 对其进行转换、优化和打包。 + +`src` 属性是 **相对于 public 文件夹的**。在 Markdown 中，你可以使用 `![]()` 表示。 + +```astro +--- +// src/pages/index.astro + +// 存取放在 `public/images/` 里的图片 +--- + +``` + +### `src/assets/` （实验性） + +请参阅 [资源（实验性）](/zh-cn/guides/images/) 指南，了解如何启用 `/assets/` 文件夹的实验性用法。 + +这将需要你更新现有图片，删除当前的 Astro 图片集成，并且还需要额外的手动更改以利用其某些新功能。 + +## Astro 的图片集成 + +:::note[将在 v3.0 中弃用] +Astro v3 将不再主动支持 [`@astrojs/image`](https://github.com/withastro/astro/tree/main/packages/integrations/image) 集成 + +我们建议你尽早删除它，并使用将内置在 `astro@3.0` 中的实验性 `astro:assets` 模块。 + +请按照 [资源（实验性）使用指南](/zh-cn/guides/images/) 开始使用新的图片解决方案！ + +**`astro:assets` 目前还不能完全替代 `@astrojs/image` ，但它正在被积极开发中。** +::: + +有关在 Astro v2 中使用 `@astrojs/image` 的文档，请参阅 [`@astrojs/image` 文档](https://github.com/withastro/astro/blob/main/packages/integrations/image/README.md) + +## 使用 CMS 或 CDN 上的图片 + +Image CDN 可与 Astro 配合使用，可将图片的完整网址作为 `` 标签中的 `src` 属性或 Markdown 标记 + +如果 CDN 提供了 Node.js SDK ，则可以在项目中使用它。例如，[Cloudinary 的 SDK](https://cloudinary.com/documentation/node_integration) 可以生成带有相应 `src` 属性 的 ` ` 标签。 + +## Alt Text + +并非所有用户都能以相同的方式查看图片，因此在使用图片时可访问性是一个特别重要的问题。使用 `alt` 属性为图片提供 [描述性替代文本](https://www.w3.org/WAI/tutorials/images/)。 + +此属性对于映像集成的 `` 和 `` 组件是必需的，如果未提供替代文本，这些组件将引发错误。 + +如果图像只是装饰性的（即无助于理解页面）请设置 `alt=""`，以便屏幕阅读器知道忽略该图像。 + +## 社区开发的集成 + +除了官方的 [`@astrojs/image`](/zh-cn/guides/integrations-guid/image/) 集成外，社区还开发了[社区图片集成](https://astro.build/integrations?search=images)，用于处理和优化 Astro 项目中的图片。 diff --git a/src/content/docs/ar/core-concepts/astro-components.mdx b/src/content/docs/ar/core-concepts/astro-components.mdx index f980a01ee1565..a1de3495cf2ed 100644 --- a/src/content/docs/ar/core-concepts/astro-components.mdx +++ b/src/content/docs/ar/core-concepts/astro-components.mdx @@ -286,7 +286,7 @@ const { title } = Astro.props - لا يدعمون frontmatter، أو الإستيراد على جانب الخادم (Server-side imports)، أو التعابير الديناميكية. - أي وسوم ` + +A starry night sky. -```astro title="src/pages/index.astro" ---- -// Access images in `public/images/` ---- - ``` -### `src/assets/` (experimental) +#### Passing the Image component -See the [Assets (Experimental)](/en/guides/assets/) guide for enabling experimental use of the `/assets/` folder. +The `` component, like any other Astro component, **is unavailable to UI framework components**. -This will require you to update your existing images, remove the current Astro image integration, and will also require additional manual changes to take advantage of some of its new features. +But, you can pass the static content generated by `` to a framework component inside a `.astro` file as children or using a [named ``](/en/core-concepts/framework-components/#can-i-use-astro-components-inside-my-framework-components): -## Astro's Image Integration -:::note[to be deprecated in v3.0] -The [`@astrojs/image`](https://github.com/withastro/astro/tree/main/packages/integrations/image) integration will no longer be actively supported in Astro v3.0. +```astro title="ImageWrapper.astro" +--- +import ReactComponent from './ReactComponent.jsx'; +import { Image } from "astro:assets" +import stars from "~/stars/docline.png"; +--- -We suggest removing it at your earliest convenience and using the experimental `astro:assets` module which will be built in to `astro@3.0`. + + A starry night sky. + +``` -Follow the [Assets (Experimental) Guide](/en/guides/assets/) to start using Astro's new image solution today! +## Generating images with `getImage()` -**`astro:assets` is not a complete replacement for `@astrojs/image` at this time, but it is under active development.** +:::caution +`getImage()` relies on server-only APIs and breaks the build when used on the client. ::: -For documentation on using `@astrojs/image` in Astro v2, please see the [`@astrojs/image` package documentation](https://github.com/withastro/astro/blob/main/packages/integrations/image/README.md) +The `getImage()` function is intended for generating images destined to be used somewhere else than directly in HTML, for example in an [API Route](/en/core-concepts/endpoints/#server-endpoints-api-routes). It also allows you to create your own custom `` component. -## Using Images from a CMS or CDN +`getImage()` takes an options object with the [same properties as the Image component](#properties) (except `alt`). -Image CDNs work with Astro. Use an image's full URL as the `src` attribute in an `` tag or Markdown notation. +```astro +--- +import { getImage } from "astro:assets"; +import myBackground from "../background.png" + +const optimizedBackground = await getImage({src: myBackground, format: 'avif'}) +--- + +
+``` -Alternatively, if the CDN provides a Node.js SDK, you can use that in your project. For example, [Cloudinary’s SDK](https://cloudinary.com/documentation/node_integration) can generate the `` tag with the appropriate `src` for you. +It returns an object with the following properties: + +```js +{ + options: {...} // Original parameters passed + src: "https//..." // Path to the generated image + attributes: {...} // Additional HTML attributes needed to render the image (width, height, style, etc..) +} +``` ## Alt Text Not all users can see images in the same way, so accessibility is an especially important concern when using images. Use the `alt` attribute to provide [descriptive alt text](https://www.w3.org/WAI/tutorials/images/) for images. -This attribute is required for the image integration's `` and `` components. These components will throw an error if no alt text is provided. +This attribute is required for the `` component. `` will throw an error if no alt text is provided. If the image is merely decorative (i.e. doesn’t contribute to the understanding of the page), set `alt=""` so that screen readers know to ignore the image. +## Default image service + +[Sharp](https://github.com/lovell/sharp) is the default image service used for `astro:assets`. + +If you would prefer to use [Squoosh](https://github.com/GoogleChromeLabs/squoosh) to transform your images, update your config with the following: +```js title="astro.config.mjs" ins={4-6} +import { defineConfig, squooshImageService } from 'astro/config'; + +export default defineConfig({ + image: { + service: squooshImageService(), + }, +}); +``` ## Community Integrations -In addition to the official [`@astrojs/image`](/en/guides/integrations-guide/image/) integration, there are several third-party [community image integrations](https://astro.build/integrations?search=images) for optimizing and working with images in your Astro project. +There are several third-party [community image integrations](https://astro.build/integrations?search=images) for optimizing and working with images in your Astro project. + +## Upgrade to v3.0 from v2.x + +`astro:assets` is no longer behind an experimental flag in Astro v3.0. + +`` is now a built-in component and the previous `@astrojs/image` integration has been removed. + +These and other accompanying changes to using images in Astro may cause some breaking changes when you upgrade your Astro project from an earlier version. + +Please follow the instructions below as appropriate to upgrade an Astro v2.x project to v3.0. + +### Upgrade from `experimental.assets` + +If you had previously enabled the experimental flag for `astro:assets`, you will need to update your project for Astro v3.0 which now includes assets features by default. + +#### Remove `experimental.assets` flag + +Remove the experimental flag: + +```js title="astro.config.mjs" del={4-6} +import { defineConfig } from 'astro/config'; + +export default defineConfig({ + experimental: { + assets: true + } +}); +``` + +If necessary, also update your `src/env.d.ts` file to replace the `astro/client-image` reference with `astro/client`: + +```ts title="src/env.d.ts" del={1} ins={2} +/// +/// +``` + +#### Remove the `~/assets` import alias + +This import alias is no longer included by default with `astro:assets`. If you were using this alias with experimental assets, you must convert them to relative file paths, or [create your own import aliases](/en/guides/aliases/). + +```astro title="src/pages/posts/post-1.astro" del={2} ins={3} +--- +import rocket from '~/assets/rocket.png' +import rocket from '../../assets/rocket.png'; +--- +``` + +#### Add simple asset support for Cloudflare, Deno, Vercel Edge and Netlify Edge + + Astro v3.0 allows `astro:assets` to work without errors in Cloudflare, Deno, Vercel Edge and Netlify Edge, which do not support Astro's built-in Squoosh and Sharp image optimization. Note that Astro does not perform any image transformation and processing in these environments. However, you can still enjoy the other benefits of using `astro:assets`, including no Cumulative Layout Shift (CLS), the enforced `alt` attribute, and a consistent authoring experience. + + If you previously avoided using `astro:assets` because of these constraints, you can now use them without issues. You can configure the no-op image service to explicitly opt-in to this behavior: + +```js title="astro.config.mjs" ins={4-8} +import { defineConfig } from 'astro/config'; + +export default defineConfig({ + image: { + service: { + entrypoint: 'astro/assets/services/noop' + } + } +}); +``` + +### Decide where to store your images + +See the Images guide to help you decide [where to store your images](#where-to-store-images). You may wish to take advantage of new options for storing your images with the added flexibility `astro:assets` brings. For example, relative images from your project `src/` can now be referenced in Markdown, MDX, and Markdoc using standard Markdown `![alt](src)` syntax. + +### Update existing `` tags + +Previously, importing an image would return a simple `string` with the path of the image. Now, imported image assets match the following signature: + +```ts +interface ImageMetadata { + src: string; + width: number; + height: number; + format: string; +} +``` + +You must update the `src` attribute of any existing `` tags (including any [images in UI framework components](#images-in-ui-framework-components)) and you may also update other attributes that are now available to you from the imported image. + +```astro title="src/components/MyComponent.astro" ".src" ".width" ".height" del={4} ins={6} +--- +import rocket from '../images/rocket.svg'; +--- +A rocketship in space. + +A rocketship in space. +``` + +### Update your Markdown, MDX, and Markdoc files + +Relative images from your project `src/` can now be referenced in Markdown, MDX, and Markdoc using standard Markdown `![alt](src)` syntax. + +This allows you to move your images from the `public/` directory to your project `src/` where they will now be processed and optimized. Your existing images in `public/` and remote images are still valid but are not optimized by Astro's build process. + +```md title="src/pages/posts/post-1.md" "/_astro" ".hash" "../../assets/" +# My Markdown Page + + +![A starry night sky.](../../images/stars.png) + + +![A starry night sky.](./stars.png) +``` + +If you require more control over your image attributes, we recommend using the `.mdx` file format, which allows you to include Astro's `` component or a JSX `` tag in addition to the Markdown syntax. Use the [MDX integration](/en/guides/integrations-guide/mdx/) to add support for MDX to Astro. + +### Remove `@astrojs/image` + + +If you were using the image integration in Astro v2.x, complete the following steps: + +1. Remove the `@astrojs/image` integration. + + You must [remove the integration](/en/guides/integrations-guide/#removing-an-integration) by uninstalling and then removing it from your `astro.config.mjs` file. + + ```js del={3,7} + // astro.config.mjs + import { defineConfig } from 'astro/config'; + import image from '@astrojs/image'; + + export default defineConfig({ + integrations: [ + image(), + ] + }) + ``` + +2. Migrate any existing `` components. + + Change all `import` statements from `@astrojs/image/components` to `astro:assets` in order to use the new built-in `` component. + + Remove any component attributes that are not [currently supported image asset properties](/en/guides/images/#properties). + + For example, `aspectRatio` is no longer supported, as it is now automatically inferred from the `width` and `height` attributes. + + ```astro title="src/components/MyComponent.astro" del= {2,11} ins={3} + --- + import { Image } from '@astrojs/image/components'; + import { Image } from 'astro:assets' + import localImage from "../assets/logo.png"; + const localAlt = "The Astro Logo"; + --- + + {localAlt} + ``` + +3. Remove any existing `` components. + + Currently, the built-in assets feature does not include a `` component. + + Instead, you can use the HTML image attributes `srcset` and `sizes` or the `` tag [for art direction or to create responsive images](https://developer.mozilla.org/en-US/docs/Learn/HTML/Multimedia_and_embedding/Responsive_images#art_direction). + +4. Choose a default image service. + + [Sharp](https://github.com/lovell/sharp) is now the default image service used for `astro:assets`. If you would like to use Sharp, no configuration is required. + + If you would prefer to use [Squoosh](https://github.com/GoogleChromeLabs/squoosh) to transform your images, update your config with the following `image.service` option: + + ```js title="astro.config.mjs" ins={4-6} + import { defineConfig, squooshImageService } from 'astro/config'; + + export default defineConfig({ + image: { + service: squooshImageService(), + }, + }); + ``` + +### Update Content Collections schemas + +You can now declare an associated image for a content collections entry, such as a blog post's cover image, in your frontmatter using its path relative to the current folder. + +The new `image` helper for content collections lets you validate the image metadata using Zod. Learn more about [how to use images in content collections](/en/guides/images/#images-in-content-collections) diff --git a/src/content/docs/en/guides/integrations-guide.mdx b/src/content/docs/en/guides/integrations-guide.mdx index 2a512ca2dd279..b95b5f0fd4160 100644 --- a/src/content/docs/en/guides/integrations-guide.mdx +++ b/src/content/docs/en/guides/integrations-guide.mdx @@ -126,17 +126,17 @@ To remove an integration, first uninstall the integration from your project ```shell - npm uninstall @astrojs/image + npm uninstall @astrojs/react ``` ```shell - pnpm uninstall @astrojs/image + pnpm uninstall @astrojs/react ``` ```shell - yarn remove @astrojs/image + yarn remove @astrojs/react ``` @@ -146,11 +146,11 @@ Next, remove the integration from your `astro.config.*` file: ```js title="astro.config.mjs" del={3,7} import { defineConfig } from 'astro/config' -import image from "@astrojs/image"; +import react from "@astrojs/react"; export default defineConfig({ integrations: [ - image() + react() ] }) ``` diff --git a/src/content/docs/en/guides/integrations-guide/cloudflare.mdx b/src/content/docs/en/guides/integrations-guide/cloudflare.mdx index a000c5203b6cb..9f2dc2e005b4f 100644 --- a/src/content/docs/en/guides/integrations-guide/cloudflare.mdx +++ b/src/content/docs/en/guides/integrations-guide/cloudflare.mdx @@ -65,23 +65,37 @@ export default defineConfig({ default `"advanced"` -Cloudflare Pages has 2 different modes for deploying functions, `advanced` mode which picks up the `_worker.js` in `dist`, or a directory mode where pages will compile the worker out of a functions folder in the project root. +Cloudflare Pages has 2 different modes for deploying functions, `advanced` mode which picks up the `_worker.js` in `dist`, or a directory mode where pages will compile the worker out of a functions folder in the project root. For most projects the adapter default of `advanced` will be sufficient; the `dist` folder will contain your compiled project. -For most projects the adapter default of `advanced` will be sufficient; the `dist` folder will contain your compiled project. Switching to directory mode allows you to use [pages plugins](https://developers.cloudflare.com/pages/platform/functions/plugins/) such as [Sentry](https://developers.cloudflare.com/pages/platform/functions/plugins/sentry/) or write custom code to enable logging. +#### `mode:directory` -In directory mode, the adapter will compile the client side part of your app the same way by default, but moves the worker script into a `functions` folder in the project root. In this case, the adapter will only ever place a `[[path]].js` in that folder, allowing you to add additional plugins and pages middleware which can be checked into version control. - -With the build configuration `split: true`, the adapter instead compiles a separate bundle for each page. This option requires some manual maintenance of the `functions` folder. Files emitted by Astro will overwrite existing `functions` files with identical names, so you must choose unique file names for each file you manually add. Additionally, the adapter will never empty the `functions` folder of outdated files, so you must clean up the folder manually when you remove pages. - -Note that this adapter does not support using [Cloudflare Pages Middleware](https://developers.cloudflare.com/pages/platform/functions/middleware/). Astro will bundle the [Astro middleware](/en/guides/middleware/) into each page. +Switching to directory mode allows you to use [pages plugins](https://developers.cloudflare.com/pages/platform/functions/plugins/) such as [Sentry](https://developers.cloudflare.com/pages/platform/functions/plugins/sentry/) or write custom code to enable logging. ```ts -// directory mode +// astro.config.mjs export default defineConfig({ adapter: cloudflare({ mode: 'directory' }), }); ``` +In `directory` mode, the adapter will compile the client-side part of your app the same way as in `advanced` mode by default, but moves the worker script into a `functions` folder in the project root. In this case, the adapter will only ever place a `[[path]].js` in that folder, allowing you to add additional plugins and pages middleware which can be checked into version control. + +To instead compile a separate bundle for each page, set the `functionPerPath` option in your Cloudflare adapter config. This option requires some manual maintenance of the `functions` folder. Files emitted by Astro will overwrite existing `functions` files with identical names, so you must choose unique file names for each file you manually add. Additionally, the adapter will never empty the `functions` folder of outdated files, so you must clean up the folder manually when you remove pages. + +```diff +import {defineConfig} from "astro/config"; +import cloudflare from '@astrojs/cloudflare'; + +export default defineConfig({ + adapter: cloudflare({ + mode: 'directory', ++ functionPerRoute: true + }) +}) +``` + +Note that this adapter does not support using [Cloudflare Pages Middleware](https://developers.cloudflare.com/pages/platform/functions/middleware/). Astro will bundle the [Astro middleware](/en/guides/middleware/) into each page. + ## Enabling Preview In order for preview to work you must install `wrangler` @@ -156,7 +170,7 @@ See Cloudflare's documentation for [working with environment variables](https:// ```js // pages/[id].json.js -export function get({ params }) { +export function GET({ params }) { // Access environment variables per request inside a function const serverUrl = import.meta.env.SERVER_URL; const result = await fetch(serverUrl + "/user/" + params.id); diff --git a/src/content/docs/en/guides/integrations-guide/image.mdx b/src/content/docs/en/guides/integrations-guide/image.mdx deleted file mode 100644 index eacbc72045017..0000000000000 --- a/src/content/docs/en/guides/integrations-guide/image.mdx +++ /dev/null @@ -1,750 +0,0 @@ ---- -# NOTE: This file is auto-generated from 'scripts/generate-integration-pages.ts' -# and pulls content directly from the package’s README. -# DO NOT MAKE EDITS TO THIS FILE DIRECTLY, THEY WILL BE OVERWRITTEN! -# For corrections, please edit the package README at -# https://github.com/withastro/astro/tree/main/packages/integrations/image/ -# -# TRANSLATORS: please remove this note and the component. - -type: integration -title: '@astrojs/image' -description: Learn how to use the @astrojs/image integration in your Astro project. -githubURL: 'https://github.com/withastro/astro/tree/main/packages/integrations/image/' -hasREADME: true -category: other -i18nReady: true ---- - -import Video from '~/components/Video.astro'; -import DontEditWarning from '~/components/DontEditWarning.astro'; - - - -> ⚠️ This integration will be deprecated in Astro v3.0 (Fall 2023) in favor of the `astro:assets` module. Please see the [Assets documentation](/en/guides/assets/) for more information. - -This **[Astro integration][astro-integration]** optimizes images in your [Astro project](https://astro.build/). It is supported in Astro v2 only for all static sites and for [some server-side rendering deploy hosts](#installation). - -## Why `@astrojs/image`? - -Images play a big role in overall site performance and usability. Serving properly sized images makes all the difference but is often tricky to automate. - -This integration provides `` and `` components as well as a basic image transformer, with full support for static sites and server-side rendering. The built-in image transformer is also replaceable, opening the door for future integrations that work with your favorite hosted image service. - -## Installation - -Along with our integration, we recommend installing [sharp](https://sharp.pixelplumbing.com/) when appropriate. - -The `@astrojs/image` default image transformer is based on [Squoosh](https://github.com/GoogleChromeLabs/squoosh) and uses WebAssembly libraries to support most deployment environments, including those that do not support sharp, such as StackBlitz. - -For faster builds and more fine-grained control of image transformations, install sharp in addition to `@astrojs/image` if - -* You are building a static site with Astro. -* You are using an SSR deployment host that supports NodeJS using `@astrojs/netlify/functions`, `@astrojs/vercel/serverless` or `@astrojs/node`. - -Note that `@astrojs/image` is not currently supported on - -* Cloudflare SSR -* `@astrojs/deno` -* `@astrojs/netlify/edge-functions` -* `@astrojs/vercel/edge` - -### Quick Install - -The `astro add` command-line tool automates the installation for you. Run one of the following commands in a new terminal window. (If you aren't sure which package manager you're using, run the first command.) Then, follow the prompts, and type "y" in the terminal (meaning "yes") for each one. - -```sh -# Using NPM -npx astro add image -# Using Yarn -yarn astro add image -# Using PNPM -pnpm astro add image -``` - -If you run into any issues, [feel free to report them to us on GitHub](https://github.com/withastro/astro/issues) and try the manual installation steps below. - -### Manual Install - -First, install the `@astrojs/image` package using your package manager. If you're using npm or aren't sure, run this in the terminal: - -```sh -npm install @astrojs/image -``` - -Then, apply this integration to your `astro.config.*` file using the `integrations` property: - -```js ins={3} "image()" -// astro.config.mjs -import { defineConfig } from 'astro/config'; -import image from '@astrojs/image'; - -export default defineConfig({ - // ... - integrations: [image()], -}); -``` - -### Installing `sharp` (optional) - -First, install the `sharp` package using your package manager. If you're using npm or aren't sure, run this in the terminal: - -```sh -npm install sharp -``` - -Then, update the integration in your `astro.config.*` file to use the built-in `sharp` image transformer. - -```js ins={8} -// astro.config.mjs -import { defineConfig } from 'astro/config'; -import image from '@astrojs/image'; - -export default defineConfig({ - // ... - integrations: [ - image({ - serviceEntryPoint: '@astrojs/image/sharp', - }), - ], -}); -``` - -### Update `env.d.ts` - -For the best development experience, add the integrations type definitions to your project's `env.d.ts` file. - -```typescript -// Replace `astro/client` with `@astrojs/image/client` -/// -``` - -Or, alternatively if your project is using the types through a `tsconfig.json` - -```json -{ - "compilerOptions": { - // Replace `astro/client` with `@astrojs/image/client` - "types": ["@astrojs/image/client"] - } -} -``` - -## Usage - -```astro title="src/pages/index.astro" ---- -import { Image, Picture } from '@astrojs/image/components'; -import heroImage from '../assets/hero.png'; ---- - -// optimized image, keeping the original width, height, and image format -descriptive text - -// specify multiple sizes for responsive images or art direction - ---- -``` - -The included image transformers support resizing images and encoding them to different image formats. Third-party image services will be able to add support for custom transformations as well (ex: `blur`, `filter`, `rotate`, etc). - -Astro’s `` and `` components require the `alt` attribute, which provides descriptive text for images. A warning will be logged if alt text is missing, and a future release of the integration will throw an error if no alt text is provided. - -If the image is merely decorative (i.e. doesn’t contribute to the understanding of the page), set `alt=""` so that the image is properly understood and ignored by screen readers. - -### `` - -The built-in `` component is used to create an optimized `` for both remote images accessed by URL as well as local images imported from your project's `src/` directory. - -In addition to the component-specific properties, any valid HTML attribute for the `` included in the `` component will be included in the built ``. - -#### src - -

- -**Type:** `string` | `ImageMetadata` | `Promise`
-**Required:** `true` - -

- -Source for the original image file. - -For remote images, provide the full URL. (e.g. `src="https://astro.build/assets/blog/astro-1-release-update.avif"`) - -For images located in your project's `src/`: use the file path relative to the `src/` directory. (e.g. `src="../assets/source-pic.png"`) - -For images located in your `public/` directory: use the URL path relative to the `public/` directory. (e.g. `src="/images/public-image.jpg"`). These work like remote images. - -#### alt - -

- -**Type:** `string`
-**Required:** `true` - -

- -Defines an alternative text description of the image. - -Set to an empty string (`alt=""`) if the image is not a key part of the content (e.g. it's decoration or a tracking pixel). - -#### format - -

- -**Type:** `'avif' | 'jpeg' | 'jpg' | 'png' | 'svg' | 'webp'`
-**Default:** `undefined` - -

- -The output format to be used in the optimized image. The original image format will be used if `format` is not provided. - -This property is required for remote images when using the default image transformer Squoosh, this is because the original format cannot be inferred. - -Added in v0.15.0: You can use the `` component when working with SVG images, but the `svg` option can only be used when the original image is a `.svg` file. Other image formats (like `.png` or `.jpg`) cannot be converted into vector images. The `.svg` image itself will not be transformed, but the final `` will be properly optimized by the integration. - -#### quality - -

- -**Type:** `number`
-**Default:** `undefined` - -

- -The compression quality used during optimization. The image service will use its own default quality depending on the image format if not provided. - -#### width - -

- -**Type:** `number`
-**Default:** `undefined` - -

- -The desired width of the output image. Combine with `height` to crop the image to an exact size, or `aspectRatio` to automatically calculate and crop the height. - -Dimensions are optional for local images, the original image size will be used if not provided. - -For remote images, including images in `public/`, the integration needs to be able to calculate dimensions for the optimized image. This can be done by providing `width` and `height` or by providing one dimension and an `aspectRatio`. - -#### height - -

- -**Type:** `number`
-**Default:** `undefined` - -

- -The desired height of the output image. Combine with `width` to crop the image to an exact size, or `aspectRatio` to automatically calculate and crop the width. - -Dimensions are optional for local images, the original image size will be used if not provided. - -For remote images, including images in `public/`, the integration needs to be able to calculate dimensions for the optimized image. This can be done by providing `width` and `height` or by providing one dimension and an `aspectRatio`. - -#### aspectRatio - -

- -**Type:** `number` | `string`
-**Default:** `undefined` - -

- -The desired aspect ratio of the output image. Combine with either `width` or `height` to automatically calculate and crop the other dimension. - -A `string` can be provided in the form of `{width}:{height}`, ex: `16:9` or `3:4`. - -A `number` can also be provided, useful when the aspect ratio is calculated at build time. This can be an inline number such as `1.777` or inlined as a JSX expression like `aspectRatio={16/9}`. - -For remote images, including images in `public/`, the integration needs to be able to calculate dimensions for the optimized image. This can be done by providing `width` and `height` or by providing one dimension and an `aspectRatio`. - -#### background - -

- -**Type:** `ColorDefinition`
-**Default:** `undefined` - -

- -> This is not supported by the default Squoosh service. See the [installation section](#installing-sharp-optional) for details on using the `sharp` service instead. - -The background color is used to fill the remaining background when using `contain` for the `fit` property. - -The background color is also used for replacing the alpha channel with `sharp`'s `flatten` method. In case the output format -doesn't support transparency (i.e. `jpeg`), it's advisable to include a background color, otherwise black will be used -as default replacement for transparent pixels. - -The parameter accepts a `string` as value. - -The parameter can be a [named HTML color](https://www.w3schools.com/tags/ref_colornames.asp), a hexadecimal -color representation with 3 or 6 hexadecimal characters in the form `#123[abc]`, an RGB definition in the form -`rgb(100,100,100)`, an RGBA definition in the form `rgba(100,100,100, 0.5)`. - -#### fit - -

- -**Type:** `'cover' | 'contain' | 'fill' | 'inside' | 'outside'`
-**Default:** `'cover'` - -

- -> This is not supported by the default Squoosh service. See the [installation section](#installing-sharp-optional) for details on using the `sharp` service instead. Read more about [how `sharp` resizes images](https://sharp.pixelplumbing.com/api-resize). - -How the image should be resized to fit both `height` and `width`. - -#### position - -

- -**Type:** `'top' | 'right top' | 'right' | 'right bottom' | 'bottom' | 'left bottom' | 'left' | 'left top' | 'north' | 'northeast' | 'east' | 'southeast' | 'south' | 'southwest' | 'west' | 'northwest' | 'center' | 'centre' | 'cover' | 'entropy' | 'attention'`
-**Default:** `'centre'` - -

- -> This is not supported by the default Squoosh service. See the [installation section](#installing-sharp-optional) for details on using the `sharp` service instead. Read more about [how `sharp` resizes images](https://sharp.pixelplumbing.com/api-resize). - -Position of the crop when fit is `cover` or `contain`. - -### `` - -The built-in `` component is used to create an optimized `` for both remote images accessed by URL as well as local images imported from your project's `src/` directory. - -In addition to the component-specific properties, any valid HTML attribute for the `` included in the `` component will be included in the built ``. - -#### src - -

- -**Type:** `string` | `ImageMetadata` | `Promise`
-**Required:** `true` - -

- -Source for the original image file. - -For remote images, provide the full URL. (e.g. `src="https://astro.build/assets/blog/astro-1-release-update.avif"`) - -For images located in your project's `src/`: use the file path relative to the `src/` directory. (e.g. `src="../assets/source-pic.png"`) - -For images located in your `public/` directory: use the URL path relative to the `public/` directory. (e.g. `src="/images/public-image.jpg"`). These work like remote images. - -#### alt - -

- -**Type:** `string`
-**Required:** `true` - -

- -Defines an alternative text description of the image. - -Set to an empty string (`alt=""`) if the image is not a key part of the content (e.g. it's decoration or a tracking pixel). - -#### sizes - -

- -**Type:** `string`
-**Required:** `true` - -

- -The HTMLImageElement property `sizes` allows you to specify the layout width of the image for each of a list of media conditions. - -See [MDN](https://developer.mozilla.org/en-US/docs/Web/API/HTMLImageElement/sizes) for more details. - -#### widths - -

- -**Type:** `number[]`
-**Required:** `true` - -

- -The list of sizes that should be built for responsive images. This is combined with `aspectRatio` to calculate the final dimensions of each built image. - -```astro -// Builds three images: 400x400, 800x800, and 1200x1200 - -``` - -#### aspectRatio - -

- -**Type:** `number` | `string`
-**Default:** `undefined` - -

- -The desired aspect ratio of the output image. This is combined with `widths` to calculate the final dimensions of each built image. - -A `string` can be provided in the form of `{width}:{height}`, ex: `16:9` or `3:4`. - -A `number` can also be provided, useful when the aspect ratio is calculated at build time. This can be an inline number such as `1.777` or inlined as a JSX expression like `aspectRatio={16/9}`. - -For remote images, including images in `public/`, `aspectRatio` is required to ensure the correct `height` can be calculated at build time. - -#### formats - -

- -**Type:** `Array<'avif' | 'jpeg' | 'png' | 'webp'>`
-**Default:** `undefined` - -

- -The output formats to be used in the optimized image. If not provided, `webp` and `avif` will be used in addition to the original image format. - -For remote images, including images in `public/`, the original image format is unknown. If not provided, only `webp` and `avif` will be used. - -#### background - -

- -**Type:** `ColorDefinition`
-**Default:** `undefined` - -

- -> This is not supported by the default Squoosh service. See the [installation section](#installing-sharp-optional) for details on using the `sharp` service instead. - -The background color to use for replacing the alpha channel with `sharp`'s `flatten` method. In case the output format -doesn't support transparency (i.e. `jpeg`), it's advisable to include a background color, otherwise black will be used -as default replacement for transparent pixels. - -The parameter accepts a `string` as value. - -The parameter can be a [named HTML color](https://www.w3schools.com/tags/ref_colornames.asp), a hexadecimal -color representation with 3 or 6 hexadecimal characters in the form `#123[abc]`, or an RGB definition in the form -`rgb(100,100,100)`. - -#### fit - -

- -**Type:** `'cover' | 'contain' | 'fill' | 'inside' | 'outside'`
-**Default:** `'cover'` - -

- -> This is not supported by the default Squoosh service. See the [installation section](#installing-sharp-optional) for details on using the `sharp` service instead. Read more about [how `sharp` resizes images](https://sharp.pixelplumbing.com/api-resize). - -How the image should be resized to fit both `height` and `width`. - -#### position - -

- -**Type:** `'top' | 'right top' | 'right' | 'right bottom' | 'bottom' | 'left bottom' | 'left' | 'left top' | - 'north' | 'northeast' | 'east' | 'southeast' | 'south' | 'southwest' | 'west' | 'northwest' | - 'center' | 'centre' | 'cover' | 'entropy' | 'attention'`
-**Default:** `'centre'` - -

- -> This is not supported by the default Squoosh service. See the [installation section](#installing-sharp-optional) for details on using the `sharp` service instead. Read more about [how `sharp` resizes images](https://sharp.pixelplumbing.com/api-resize). - -Position of the crop when fit is `cover` or `contain`. - -### `getImage` - -This is the helper function used by the `` component to build `` attributes for the transformed image. This helper can be used directly for more complex use cases that aren't currently supported by the `` component. - -This helper takes in an object with the same properties as the `` component and returns an object with attributes that should be included on the final `` element. - -This can be helpful if you need to add preload links to a page's ``. - -```astro ---- -import { getImage } from '@astrojs/image'; - -const { src } = await getImage({ - src: import('../assets/hero.png'), - alt: 'My hero image', -}); ---- - - - - - - -``` - -### `getPicture` - -This is the helper function used by the `` component to build multiple sizes and formats for responsive images. This helper can be used directly for more complex use cases that aren't currently supported by the `` component. - -This helper takes in an object with the same properties as the `` component and returns an object attributes that should be included on the final `` element **and** a list of sources that should be used to render all ``s for the `` element. - -## Configuration - -The integration can be configured to run with a different image service, either a hosted image service or a full image transformer that runs locally in your build or SSR deployment. - -> During development, local images may not have been published yet and would not be available to hosted image services. Local images will always use the built-in image service when using `astro dev`. - -### config.serviceEntryPoint - -The `serviceEntryPoint` should resolve to the image service installed from NPM. The default entry point is `@astrojs/image/squoosh`, which resolves to the entry point exported from this integration's `package.json`. - -```js -// astro.config.mjs -import { defineConfig } from 'astro/config'; -import image from '@astrojs/image'; - -export default defineConfig({ - integrations: [ - image({ - // Example: The entrypoint for a third-party image service installed from NPM - serviceEntryPoint: 'my-image-service/astro.js', - }), - ], -}); -``` - -### config.logLevel - -The `logLevel` controls can be used to control how much detail is logged by the integration during builds. This may be useful to track down a specific image or transformation that is taking a long time to build. - -```js -// astro.config.mjs -import { defineConfig } from 'astro/config'; -import image from '@astrojs/image'; - -export default defineConfig({ - integrations: [ - image({ - // supported levels: 'debug' | 'info' | 'warn' | 'error' | 'silent' - // default: 'info' - logLevel: 'debug', - }), - ], -}); -``` - -### config.cacheDir - -During static builds, the integration will cache transformed images to avoid rebuilding the same image for every build. This can be particularly helpful if you are using a hosting service that allows you to cache build assets for future deployments. - -Local images will be cached for 1 year and invalidated when the original image file is changed. Remote images will be cached based on the `fetch()` response's cache headers, similar to how a CDN would manage the cache. - -By default, transformed images will be cached to `./node_modules/.astro/image`. This can be configured in the integration's config options. - -```js -// astro.config.mjs -import { defineConfig } from 'astro/config'; -import image from '@astrojs/image'; - -export default defineConfig({ - integrations: [ - image({ - // may be useful if your hosting provider allows caching between CI builds - cacheDir: './.cache/image', - }), - ], -}); -``` - -Caching can also be disabled by using `cacheDir: false`. - -## Examples - -### Local images - -Image files in your project's `src/` directory can be imported in frontmatter and passed directly to the `` component as the `src=` attribute value. `alt` is also required. - -All other properties are optional and will default to the original image file's properties if not provided. - -```astro ---- -import { Image } from '@astrojs/image/components'; -import heroImage from '../assets/hero.png'; ---- - -// optimized image, keeping the original width, height, and image format -descriptive text - -// height will be recalculated to match the original aspect ratio -descriptive text - -// cropping to a specific width and height -descriptive text - -// cropping to a specific aspect ratio and converting to an avif format -descriptive text - -// image imports can also be inlined directly -descriptive text -``` - -#### Images in `/public` - -The `` component can also be used with images stored in the `public/` directory and the `src=` attribute is relative to the public folder. It will be treated as a remote image, which requires either both `width` and `height`, or one dimension and an `aspectRatio` attribute. - -Your original image will be copied unprocessed to the build folder, like all files located in public/, and Astro’s image integration will also return optimized versions of the image. - -For example, use an image located at `public/social.png` in either static or SSR builds like so: - -```astro title="src/pages/page.astro" ---- -import { Image } from '@astrojs/image/components'; -import socialImage from '/social.png'; ---- - -// In static builds: the image will be built and optimized to `/dist`. // In SSR builds: the image -will be optimized by the server when requested by a browser. -descriptive text -``` - -### Remote images - -Remote images can be transformed with the `` component. The `` component needs to know the final dimensions for the `` element to avoid content layout shifts. For remote images, this means you must either provide `width` and `height`, or one of the dimensions plus the required `aspectRatio`. - -```astro ---- -import { Image } from '@astrojs/image/components'; - -const imageUrl = 'https://astro.build/assets/press/full-logo-dark.png'; ---- - -// cropping to a specific width and height -descriptive text - -// height will be recalculated to match the aspect ratio -descriptive text -``` - -### Responsive pictures - -The `` component can be used to automatically build a `` with multiple sizes and formats. Check out [MDN](https://developer.mozilla.org/en-US/docs/Learn/HTML/Multimedia_and_embedding/Responsive_images#art_direction) for a deep dive into responsive images and art direction. - -By default, the picture will include formats for `avif` and `webp`. For local images only, the image's original format will also be included. - -For remote images, an `aspectRatio` is required to ensure the correct `height` can be calculated at build time. - -```astro ---- -import { Picture } from '@astrojs/image/components'; -import hero from '../assets/hero.png'; - -const imageUrl = - 'https://www.google.com/images/branding/googlelogo/2x/googlelogo_color_272x92dp.png'; ---- - -// Local image with multiple sizes - - -// Remote image (aspect ratio is required) - - -// Inlined imports are supported - -``` - -### Setting Default Values - -Currently, there is no way to specify default values for all `` and `` components. Required attributes should be set on each individual component. - -As an alternative, you can wrap these components in another Astro component for reuse. For example, you could create a component for your blog post images: - -```astro title="src/components/BlogPostImage.astro" ---- -import { Picture } from '@astrojs/image/components'; - -const { src, ...attrs } = Astro.props; ---- - - - - -``` - -### Using `` with the Image Integration - -The official image integration will change image imports to return an object rather than a source string. -The object has the following properties, derived from the imported file: - -```ts -{ - src: string; - width: number; - height: number; - format: 'avif' | 'gif' | 'heic' | 'heif' | 'jpeg' | 'jpg' | 'png' | 'tiff' | 'webp'; -} -``` - -If you have the image integration installed, refer to the `src` property of the object when using ``. - -```astro ".src" ---- -import rocket from '../images/rocket.svg'; ---- - -A rocketship in space. -``` - -Alternatively, add `?url` to your imports to tell them to return a source string. - -```astro "?url" ---- -import rocket from '../images/rocket.svg?url'; ---- - -A rocketship in space. -``` - -## Troubleshooting - -* If your installation doesn't seem to be working, try restarting the dev server. -* If you edit and save a file and don't see your site update accordingly, try refreshing the page. -* If refreshing the page doesn't update your preview, or if a new installation doesn't seem to be working, then restart the dev server. - -For help, check out the `#support` channel on [Discord](https://astro.build/chat). Our friendly Support Squad members are here to help! - -You can also check our [Astro Integration Documentation][astro-integration] for more on integrations. - -[astro-integration]: /en/guides/integrations-guide/ - -## Contributing - -This package is maintained by Astro's Core team. You're welcome to submit an issue or PR! - -## Changelog - -See [CHANGELOG.md](https://github.com/withastro/astro/tree/main/packages/integrations/image/CHANGELOG.md) for a history of changes to this integration. diff --git a/src/content/docs/en/guides/integrations-guide/markdoc.mdx b/src/content/docs/en/guides/integrations-guide/markdoc.mdx index 8eab45a82a823..0358456dfeb63 100644 --- a/src/content/docs/en/guides/integrations-guide/markdoc.mdx +++ b/src/content/docs/en/guides/integrations-guide/markdoc.mdx @@ -356,6 +356,36 @@ Now, you can call this function from any Markdoc content entry: 📚 [See the Markdoc documentation](https://markdoc.dev/docs/functions#creating-a-custom-function) for more on using variables or functions in your content. +### Markdoc Language Server + +If you are using VS Code, there is an official [Markdoc language extension](https://marketplace.visualstudio.com/items?itemName=Stripe.markdoc-language-support) that includes syntax highlighting and autocomplete for configured tags. [See the language server on GitHub](https://github.com/markdoc/language-server.git) for more information. + +To set up the extension, create a `markdoc.config.json` file into the project root with following content: + +```json +[ + { + "id": "my-site", + "path": "src/content", + "schema": { + "path": "markdoc.config.mjs", + "type": "esm", + "property": "default", + "watch": true + } + } +] +``` + +The `schema` property contains all information to configure the language server for Astro content collections. It accepts following properties: + +* `path`: The path to the configuration file. +* `type`: The type of module your configuration file uses (`esm` allows `import` syntax). +* `property`: The exported property name that contains the configuration object. +* `watch`: Tell the server to watch for changes in the configuration. + +The top-level `path` property tells the server where content is located. Since Markdoc is specific to content collections, you can use `src/content`. + ### Pass Markdoc variables You may need to pass [variables][markdoc-variables] to your content. This is useful when passing SSR parameters like A/B tests. diff --git a/src/content/docs/en/guides/integrations-guide/mdx.mdx b/src/content/docs/en/guides/integrations-guide/mdx.mdx index 26d448b44e146..7e0c7a418df19 100644 --- a/src/content/docs/en/guides/integrations-guide/mdx.mdx +++ b/src/content/docs/en/guides/integrations-guide/mdx.mdx @@ -81,7 +81,7 @@ export default defineConfig({ With the Astro MDX integration, you can [add MDX pages to your project](/en/guides/markdown-content/#markdown-and-mdx-pages) by adding `.mdx` files within your `src/pages/` directory. You can also [import `.mdx` files](/en/guides/markdown-content/#importing-markdown) into `.astro` files. -Astro's MDX integration adds extra features to standard MDX, including Markdown-style frontmatter. This allows you to use most of Astro's built-in Markdown features like a [special frontmatter `layout` property](/en/guides/markdown-content/#frontmatter-layout) and a [property for marking a page as a draft](/en/guides/markdown-content/#draft-pages). +Astro's MDX integration adds extra features to standard MDX, including Markdown-style frontmatter. This allows you to use most of Astro's built-in Markdown features like a [special frontmatter `layout` property](/en/guides/markdown-content/#frontmatter-layout). See how MDX works in Astro with examples in our [Markdown & MDX guide](/en/guides/markdown-content/). diff --git a/src/content/docs/en/guides/integrations-guide/netlify.mdx b/src/content/docs/en/guides/integrations-guide/netlify.mdx index cac5f43d478d8..128bb3e32038d 100644 --- a/src/content/docs/en/guides/integrations-guide/netlify.mdx +++ b/src/content/docs/en/guides/integrations-guide/netlify.mdx @@ -69,28 +69,11 @@ If you prefer to install the adapter manually instead, complete the following tw }); ``` -### Edge Functions - -Netlify has two serverless platforms, [Netlify Functions](https://docs.netlify.com/functions/overview/) and [Netlify Edge Functions](https://docs.netlify.com/edge-functions/overview/). With Edge Functions your code is distributed closer to your users, lowering latency. - -To deploy with Edge Functions, use `netlify/edge-functions` in the Astro config file instead of `netlify/functions`. - -```js ins={3} -// astro.config.mjs -import { defineConfig } from 'astro/config'; -import netlify from '@astrojs/netlify/edge-functions'; - -export default defineConfig({ - output: 'server', - adapter: netlify(), -}); -``` - ### Run middleware in Edge Functions When deploying to Netlify Functions, you can choose to use an Edge Function to run your Astro middleware. -To enable this, set the `build.excludeMiddleware` Astro config option to `true`: +To enable this, set the `edgeMiddleware` config option to `true`: ```js ins={9} // astro.config.mjs @@ -99,10 +82,9 @@ import netlify from '@astrojs/netlify/functions'; export default defineConfig({ output: 'server', - adapter: netlify(), - build: { - excludeMiddleware: true, - }, + adapter: netlify({ + edgeMiddleware: true, + }), }); ``` @@ -148,10 +130,9 @@ import netlify from '@astrojs/netlify/functions'; export default defineConfig({ output: 'server', - adapter: netlify(), - build: { - split: true, - }, + adapter: netlify({ + functionPerRoute: true, + }), }); ``` @@ -276,7 +257,7 @@ We check for common mime types for audio, image, and video files. To include spe import fs from 'node:fs'; -export function get() { +export function GET() { const buffer = fs.readFileSync('../image.jpg'); // Return the buffer directly, @astrojs/netlify will base64 encode the body diff --git a/src/content/docs/en/guides/integrations-guide/node.mdx b/src/content/docs/en/guides/integrations-guide/node.mdx index 6390c8d9fbeee..4708c89af5163 100644 --- a/src/content/docs/en/guides/integrations-guide/node.mdx +++ b/src/content/docs/en/guides/integrations-guide/node.mdx @@ -174,7 +174,7 @@ For standalone mode the server handles file servering in addition to the page an You can override the host and port the standalone server runs on by passing them as environment variables at runtime: ```shell -HOST=0.0.0.0 PORT=3000 node ./dist/server/entry.mjs +HOST=0.0.0.0 PORT=4321 node ./dist/server/entry.mjs ``` #### HTTPS diff --git a/src/content/docs/en/guides/integrations-guide/preact.mdx b/src/content/docs/en/guides/integrations-guide/preact.mdx index 4aa862623bcf9..3d02d9e0f22cf 100644 --- a/src/content/docs/en/guides/integrations-guide/preact.mdx +++ b/src/content/docs/en/guides/integrations-guide/preact.mdx @@ -128,6 +128,41 @@ Check out the [`pnpm` overrides](https://pnpm.io/package_json#pnpmoverrides) and Currently, the `compat` option only works for React libraries that export code as ESM. If an error happens during build-time, try adding the library to `vite.ssr.noExternal: ['the-react-library']` in your `astro.config.mjs` file. ::: +## Options + +### Combining multiple JSX frameworks + +When you are using multiple JSX frameworks (React, Preact, Solid) in the same project, Astro needs to determine which JSX framework-specific transformations should be used for each of your components. If you have only added one JSX framework integration to your project, no extra configuration is needed. + +Use the `include` (required) and `exclude` (optional) configuration options to specify which files belong to which framework. Provide an array of files and/or folders to `include` for each framework you are using. Wildcards may be used to include multiple file paths. + +We recommend placing common framework components in the same folder (e.g. `/components/react/` and `/components/solid/`) to make specifying your includes easier, but this is not required: + +```js +import { defineConfig } from 'astro/config'; +import preact from '@astrojs/preact'; +import react from '@astrojs/react'; +import svelte from '@astrojs/svelte'; +import vue from '@astrojs/vue'; +import solid from '@astrojs/solid-js'; + +export default defineConfig({ + // Enable many frameworks to support all different kinds of components. + // No `include` is needed if you are only using a single JSX framework! + integrations: [ + preact({ + include: ['**/preact/*'], + }), + react({ + include: ['**/react/*'], + }), + solid({ + include: ['**/solid/*'], + }), + ], +}); +``` + ## Examples * The [Astro Preact example](https://github.com/withastro/astro/tree/latest/examples/framework-preact) shows how to use an interactive Preact component in an Astro project. diff --git a/src/content/docs/en/guides/integrations-guide/react.mdx b/src/content/docs/en/guides/integrations-guide/react.mdx index 0fdf9257fbcfe..633f6b417dde0 100644 --- a/src/content/docs/en/guides/integrations-guide/react.mdx +++ b/src/content/docs/en/guides/integrations-guide/react.mdx @@ -84,6 +84,39 @@ To use your first React component in Astro, head to our [UI framework documentat ## Options +### Combining multiple JSX frameworks + +When you are using multiple JSX frameworks (React, Preact, Solid) in the same project, Astro needs to determine which JSX framework-specific transformations should be used for each of your components. If you have only added one JSX framework integration to your project, no extra configuration is needed. + +Use the `include` (required) and `exclude` (optional) configuration options to specify which files belong to which framework. Provide an array of files and/or folders to `include` for each framework you are using. Wildcards may be used to include multiple file paths. + +We recommend placing common framework components in the same folder (e.g. `/components/react/` and `/components/solid/`) to make specifying your includes easier, but this is not required: + +```js +import { defineConfig } from 'astro/config'; +import preact from '@astrojs/preact'; +import react from '@astrojs/react'; +import svelte from '@astrojs/svelte'; +import vue from '@astrojs/vue'; +import solid from '@astrojs/solid-js'; + +export default defineConfig({ + // Enable many frameworks to support all different kinds of components. + // No `include` is needed if you are only using a single JSX framework! + integrations: [ + preact({ + include: ['**/preact/*'], + }), + react({ + include: ['**/react/*'], + }), + solid({ + include: ['**/solid/*'], + }), + ], +}); +``` + ### Children parsing Children passed into a React component from an Astro component are parsed as plain strings, not React nodes. @@ -101,7 +134,7 @@ import ReactComponent from './ReactComponent'; ``` -If you are using a library that *expects* more than one child element element to be passed, for example so that it can slot certain elements in different places, you might find this to be a blocker. +If you are using a library that *expects* more than one child element to be passed, for example so that it can slot certain elements in different places, you might find this to be a blocker. You can set the experimental flag `experimentalReactChildren` to tell Astro to always pass children to React as React vnodes. There is some runtime cost to this, but it can help with compatibility. diff --git a/src/content/docs/en/guides/integrations-guide/solid-js.mdx b/src/content/docs/en/guides/integrations-guide/solid-js.mdx index 68c766632aea8..b4d9baf047a2a 100644 --- a/src/content/docs/en/guides/integrations-guide/solid-js.mdx +++ b/src/content/docs/en/guides/integrations-guide/solid-js.mdx @@ -82,6 +82,41 @@ To use your first SolidJS component in Astro, head to our [UI framework document * 💧 client-side hydration options, and * 🤝 opportunities to mix and nest frameworks together +## Options + +### Combining multiple JSX frameworks + +When you are using multiple JSX frameworks (React, Preact, Solid) in the same project, Astro needs to determine which JSX framework-specific transformations should be used for each of your components. If you have only added one JSX framework integration to your project, no extra configuration is needed. + +Use the `include` (required) and `exclude` (optional) configuration options to specify which files belong to which framework. Provide an array of files and/or folders to `include` for each framework you are using. Wildcards may be used to include multiple file paths. + +We recommend placing common framework components in the same folder (e.g. `/components/react/` and `/components/solid/`) to make specifying your includes easier, but this is not required: + +```js +import { defineConfig } from 'astro/config'; +import preact from '@astrojs/preact'; +import react from '@astrojs/react'; +import svelte from '@astrojs/svelte'; +import vue from '@astrojs/vue'; +import solid from '@astrojs/solid-js'; + +export default defineConfig({ + // Enable many frameworks to support all different kinds of components. + // No `include` is needed if you are only using a single JSX framework! + integrations: [ + preact({ + include: ['**/preact/*'], + }), + react({ + include: ['**/react/*'], + }), + solid({ + include: ['**/solid/*'], + }), + ], +}); +``` + ## Troubleshooting For help, check out the `#support` channel on [Discord](https://astro.build/chat). Our friendly Support Squad members are here to help! diff --git a/src/content/docs/en/guides/integrations-guide/vercel.mdx b/src/content/docs/en/guides/integrations-guide/vercel.mdx index 2e3c88f528f71..2bf9dc3d1e185 100644 --- a/src/content/docs/en/guides/integrations-guide/vercel.mdx +++ b/src/content/docs/en/guides/integrations-guide/vercel.mdx @@ -73,18 +73,12 @@ If you prefer to install the adapter manually instead, complete the following tw You can deploy to different targets: -* `edge`: SSR inside an [Edge function](https://vercel.com/docs/concepts/functions/edge-functions). * `serverless`: SSR inside a [Node.js function](https://vercel.com/docs/concepts/functions/serverless-functions). * `static`: generates a static website following Vercel's output formats, redirects, etc. -:::note -deploying to the Edge has [its limitations](https://vercel.com/docs/concepts/functions/edge-functions#known-limitations). An edge function can't be more than 1 MB in size and they don't support native Node.js APIs, among others. -::: - You can change where to target by changing the import: ```js -import vercel from '@astrojs/vercel/edge'; import vercel from '@astrojs/vercel/serverless'; import vercel from '@astrojs/vercel/static'; ``` @@ -107,7 +101,7 @@ To configure this adapter, pass an object to the `vercel()` function call in `as ### analytics **Type:** `boolean`
-**Available for:** Serverless, Edge, Static
+**Available for:** Serverless, Static
**Added in:** `@astrojs/vercel@3.1.0` You can enable [Vercel Analytics](https://vercel.com/analytics) (including Web Vitals and Audiences) by setting `analytics: true`. This will inject Vercel’s tracking scripts into all your pages. @@ -128,7 +122,7 @@ export default defineConfig({ ### imagesConfig **Type:** `VercelImageConfig`
-**Available for:** Edge, Serverless, Static +**Available for:** Serverless, Static **Added in:** `@astrojs/vercel@3.3.0` Configuration options for [Vercel's Image Optimization API](https://vercel.com/docs/concepts/image-optimization). See [Vercel's image configuration documentation](https://vercel.com/docs/build-output-api/v3/configuration#images) for a complete list of supported parameters. @@ -151,7 +145,7 @@ export default defineConfig({ ### imageService **Type:** `boolean`
-**Available for:** Edge, Serverless, Static +**Available for:** Serverless, Static **Added in:** `@astrojs/vercel@3.3.0` When enabled, an [Image Service](/en/reference/image-service-reference/) powered by the Vercel Image Optimization API will be automatically configured and used in production. In development, a built-in Squoosh-based service will be used instead. @@ -192,7 +186,7 @@ import astroLogo from '../assets/logo.png'; ### includeFiles **Type:** `string[]`
-**Available for:** Edge, Serverless +**Available for:** Serverless Use this property to force files to be bundled with your function. This is helpful when you notice missing files. @@ -209,10 +203,6 @@ export default defineConfig({ }); ``` -:::note -When building for the Edge, all the dependencies get bundled in a single file to save space. **No extra file will be bundled**. So, if you *need* some file inside the function, you have to specify it in `includeFiles`. -::: - ### excludeFiles **Type:** `string[]`
@@ -233,9 +223,11 @@ export default defineConfig({ }); ``` -### Per-page functions +### Function bundling configuration -The Vercel adapter builds to a single function by default. Astro 2.7 added support for splitting your build into separate entry points per page. If you use this configuration the Vercel adapter will generate a separate function for each page. This can help reduce the size of each function so they are only bundling code used on that page. +The Vercel adapter splits builds into a separate function per route by default. This helps reduce the size of each function, as it only bundles code used on that page. + +You can disable this and build to a single function by setting the `functionPerRoute` configuration option to `false`: ```js // astro.config.mjs @@ -244,10 +236,9 @@ import vercel from '@astrojs/vercel/serverless'; export default defineConfig({ output: 'server', - adapter: vercel(), - build: { - split: true, - }, + adapter: vercel({ + functionPerRoute: false, + }), }); ``` @@ -286,7 +277,7 @@ You can use Vercel Edge middleware to intercept a request and redirect before se The `@astrojs/vercel/serverless` adapter can automatically create the Vercel Edge middleware from an Astro middleware in your code base. -This is an opt-in feature, and the `build.excludeMiddleware` option needs to be set to `true`: +This is an opt-in feature, and the `edgeMiddleware` option needs to be set to `true`: ```js // astro.config.mjs @@ -294,10 +285,9 @@ import { defineConfig } from 'astro/config'; import vercel from '@astrojs/vercel'; export default defineConfig({ output: 'server', - adapter: vercel(), - build: { - excludeMiddleware: true, - }, + adapter: vercel({ + edgeMiddleware: true, + }), }); ``` diff --git a/src/content/docs/en/guides/markdown-content.mdx b/src/content/docs/en/guides/markdown-content.mdx index b4e9b0d231ddd..76db95a487c68 100644 --- a/src/content/docs/en/guides/markdown-content.mdx +++ b/src/content/docs/en/guides/markdown-content.mdx @@ -60,64 +60,6 @@ It probably isn't styled much, but Markdown does support: 📚 Read more about Astro's [file-based routing](/en/core-concepts/routing/) or options for creating [dynamic routes](/en/core-concepts/routing/#dynamic-routes). -### Draft Pages - -`draft: true` is an optional frontmatter value that will mark an individual Markdown or MDX page or post as "unpublished." By default, this page will be: -- excluded from the site build (**no page will be built**) -- returned by [`Astro.glob()`](/en/reference/api-reference/#astroglob) (**visible in lists of posts**) - -```markdown {5} ---- -# src/pages/post/blog-post.md -layout: ../../layouts/BaseLayout.astro -title: My Blog Post -draft: true ---- - -This is my in-progress blog post. - -No page will be built for this post. - -To build and publish this post: - -- update the frontmatter to `draft: false` or -- remove the `draft` property entirely. - -But, this page _will_ be returned by any matching `Astro.glob()` request. -``` - -To exclude draft posts from being included in a post archive, or list of most recent posts, you can filter the results returned by `Astro.glob()`: - -```js -const posts = await Astro.glob('../pages/post/*.md'); -const nonDraftPosts = posts.filter((post) => !post.frontmatter.draft); -``` - -:::note[Using content collections?] -This feature is not supported for content collections, however you can use a [collection query filter](/en/guides/content-collections/#filtering-collection-queries) to filter your draft posts. -::: - -#### Enable building draft pages - -To enable building draft pages by default, update `astro.config.mjs` by adding `drafts: true` to `markdown` or to the `mdx` integration: - -```js title="astro.config.mjs" ins={5, 8} -import { defineConfig } from 'astro/config'; - -export default defineConfig({ - markdown: { - drafts: true, - }, - integrations: [mdx({ - drafts: true, - })], -}); -``` - -:::tip -You can also pass the `--drafts` flag when running `astro build` to build draft pages! -::: - ## Markdown Features Astro provides some extra, built-in Markdown features available when using Markdown and MDX files. @@ -187,7 +129,7 @@ For example, to prevent `<` being interpreted as the beginning of an HTML elemen Adding the Astro [MDX integration](/en/guides/integrations-guide/mdx/) enhances your Markdown authoring with JSX variables, expressions and components. -It also adds extra features to standard MDX, including support for [Markdown-style frontmatter in MDX](https://mdxjs.com/guides/frontmatter/). This allows you to use most of Astro's built-in Markdown features like a [frontmatter `layout`](#frontmatter-layout) property and a setting for [draft pages](#draft-pages). +It also adds extra features to standard MDX, including support for [Markdown-style frontmatter in MDX](https://mdxjs.com/guides/frontmatter/). This allows you to use most of Astro's built-in Markdown features like a [frontmatter `layout`](#frontmatter-layout) property. `.mdx` files must be written in [MDX syntax](https://mdxjs.com/docs/what-is-mdx/#mdx-syntax) rather than Astro’s HTML-like syntax. diff --git a/src/content/docs/en/guides/middleware.mdx b/src/content/docs/en/guides/middleware.mdx index d7a6688a4c8b0..4657879ff0a8d 100644 --- a/src/content/docs/en/guides/middleware.mdx +++ b/src/content/docs/en/guides/middleware.mdx @@ -45,7 +45,7 @@ You can import and use the utility function `defineMiddleware()` to take advanta ```ts // src/middleware.ts -import { defineMiddleware } from "astro/middleware"; +import { defineMiddleware } from "astro:middleware"; // `context` and `next` are automatically typed export const onRequest = defineMiddleware((context, next) => { @@ -137,7 +137,7 @@ export const onRequest = async (context, next) => { Multiple middlewares can be joined in a specified order using [`sequence()`](#sequence): ```js title="src/middleware.js" -import { sequence } from "astro/middleware"; +import { sequence } from "astro:middleware"; async function validation(_, next) { console.log("validation request"); @@ -218,4 +218,4 @@ This function can be used by integrations/adapters to programmatically execute t ### `trySerializeLocals` -A low-level API that takes in any value and tries to return a serialized version (a string) of it. If the value cannot be serialized, the function will throw a runtime error. \ No newline at end of file +A low-level API that takes in any value and tries to return a serialized version (a string) of it. If the value cannot be serialized, the function will throw a runtime error. diff --git a/src/content/docs/en/guides/migrate-to-astro/from-gatsby.mdx b/src/content/docs/en/guides/migrate-to-astro/from-gatsby.mdx index 2e7e82bd866e2..9496bc43dbbd3 100644 --- a/src/content/docs/en/guides/migrate-to-astro/from-gatsby.mdx +++ b/src/content/docs/en/guides/migrate-to-astro/from-gatsby.mdx @@ -87,8 +87,6 @@ You may find it useful to install some of [Astro's optional integrations](/en/gu - **@astrojs/react**: to reuse some existing React UI components in your new Astro site or keep writing with React components. -- **@astrojs/image**: to replace Gatsby's Image plugin with Astro's own image-optimizing components. (Experimental: works in `.astro` and `.mdx` files only.) - - **@astrojs/mdx**: to bring existing MDX files from your Gatsby project, or to use MDX in your new Astro site. @@ -321,36 +319,29 @@ See more about [Styling in Astro](/en/guides/styling/). ### Gatsby Image Plugin to Astro -:::note -Astro v3.0 will include a new `astro:assets` module and will deprecate the existing `@astrojs/image` integration. - -Access to `astro:assets` is currently available under an experimental flag, and is the recommended way to begin a new Astro project. If you are migrating to Astro pre-v3.0, we recommend [enabling the experimental flag to use assets](/en/guides/assets/) as an image solution. -::: - -Convert Gatsby's `` and `` components with [Astro's own image integration components](/en/guides/images/#astros-image-integration), or with a standard HTML `` / JSX `` tag as appropriate. +Convert Gatsby's `` and `` components to [Astro's own image integration components](/en/guides/images/#image--astroassets), or to a [standard HTML `` / JSX ``](/en/guides/images/#images-in-ui-framework-components) tag as appropriate in your React components. ```astro title="src/pages/index.astro" --- -import { Image } from '@astrojs/image/components'; -import localImage from "../images/brand/logo.png"; -import rocket from '../images/rocket.svg'; +import { Image } from 'astro:assets'; +import rocket from '../assets/rocket.png'; --- -The Astro Logo -A rocketship in space. +A rocketship in space. +A rocketship in space. ``` -Astro's `` and `` components are experimental and currently work in `.astro` and `.mdx` files only. See a [full list of component attributes](/en/guides/integrations-guide/image/#usage) available for these components, and note that several will differ from Gatsby's attributes. +Astro's `` component works in `.astro` and `.mdx` files only. See a [full list of its component attributes](/en/guides/images/#properties) and note that several will differ from Gatsby's attributes. -To continue using local images in Markdown (`.md`) files using standard Markdown syntax (`![]()`), move your images into your `public/` folder. You may need to update the link to the relative URL. You can also use the standard `` tag in these files. Note that these [images in `public/` will not be optimized by Astro](/en/guides/images/#public). +To continue using [images in Markdown (`.md`) files](/en/guides/images/#images-in-markdown-files) using standard Markdown syntax (`![]()`), you may need to update the link. Using the HTML `` tag directy is not supported in `.md` files for local images, and must be converted to Markdown syntax. ```md # My Markdown Page - -![A starry night sky.](/assets/stars.png) -A starry night sky. + +![A starry night sky.](../assets/stars.png) + ``` In React (`.jsx`) components, use standard JSX image syntax (``). Astro will not optimize these images, but you can install and use NPM packages for more flexibility. diff --git a/src/content/docs/en/guides/migrate-to-astro/from-nextjs.mdx b/src/content/docs/en/guides/migrate-to-astro/from-nextjs.mdx index 20b13d4dfa781..6dfd7798e88d8 100644 --- a/src/content/docs/en/guides/migrate-to-astro/from-nextjs.mdx +++ b/src/content/docs/en/guides/migrate-to-astro/from-nextjs.mdx @@ -83,8 +83,6 @@ You may find it useful to install some of [Astro's optional integrations](/en/gu - **@astrojs/react**: to reuse some existing React UI components in your new Astro site, or keep writing with React components. -- **@astrojs/image**: to replace Next's Image plugin with Astro's own image-optimizing components. (Experimental: works in `.astro` and `.mdx` files only.) - - **@astrojs/mdx**: to bring existing MDX files from your Next project, or to use MDX in your new Astro site. ### Put your source code in `src` @@ -419,22 +417,17 @@ See more about [Styling in Astro](/en/guides/styling/). ### Next Image Plugin to Astro -:::note -Astro v3.0 will include a new `astro:assets` module and will deprecate the existing `@astrojs/image` integration. - -Access to `astro:assets` is currently available under an experimental flag, and is the recommended way to begin a new Astro project. If you are migrating to Astro pre-v3.0, we recommend [enabling the experimental flag to use assets](/en/guides/assets/) as an image solution. -::: +Convert any Next `` components to [Astro's own image component](/en/guides/images/#image--astroassets) in `.astro` or `.mdx` files, or to a [standard HTML `` / JSX ``](/en/guides/images/#images-in-ui-framework-components) tag as appropriate in your React components. -Convert any Next `` components with [Astro's own image integration components](/en/guides/images/#astros-image-integration), or with a standard HTML ``. See a [full list of component attributes](/en/guides/integrations-guide/image/#usage) available for Astro's `` and `` components, and note that several will differ from Next's attributes. +Astro's `` component works in `.astro` and `.mdx` files only. See a [full list of its component attributes](/en/guides/images/#properties) and note that several will differ from Next's attributes. ```astro title="src/pages/index.astro" --- -import { Image } from '@astrojs/image/components'; -import localImage from "../images/brand/logo.png"; -import rocket from '../images/rocket.svg'; +import { Image } from 'astro:assets'; +import rocket from '../assets/rocket.png'; --- -The Astro Logo -A rocketship in space. +A rocketship in space. +A rocketship in space. ``` In React (`.jsx`) components, use standard JSX image syntax (``). Astro will not optimize these images, but you can install and use NPM packages for more flexibility. diff --git a/src/content/docs/en/guides/migrate-to-astro/from-nuxtjs.mdx b/src/content/docs/en/guides/migrate-to-astro/from-nuxtjs.mdx index 296ed93cf8930..d95736d2148ca 100644 --- a/src/content/docs/en/guides/migrate-to-astro/from-nuxtjs.mdx +++ b/src/content/docs/en/guides/migrate-to-astro/from-nuxtjs.mdx @@ -85,8 +85,6 @@ You may find it useful to install some of [Astro's optional integrations](/en/gu - **@astrojs/vue**: to reuse some existing Vue UI components in your new Astro site, or keep writing with Vue components. -- **@astrojs/image**: to replace Nuxt's Image plugin with Astro's own image-optimizing components. - - **@astrojs/mdx**: to bring existing MDX files from your Nuxt project, or to use MDX in your new Astro site. ### Put your source code in `src` @@ -489,24 +487,17 @@ See more about [Styling in Astro](/en/guides/styling/). ### Nuxt Image Plugin to Astro -:::note -Astro v3.0 will include a new `astro:assets` module and will deprecate the existing `@astrojs/image` integration. - -Access to `astro:assets` is currently available under an experimental flag, and is the recommended way to begin a new Astro project. If you are migrating to Astro pre-v3.0, we recommend [enabling the experimental flag to use assets](/en/guides/assets/) as an image solution. -::: - -Convert any [Nuxt `` or `` components](https://image.nuxtjs.org/components/nuxt-img) to [Astro's own image integration components](/en/guides/images/#astros-image-integration), or to a standard HTML `` tag. +Convert any [Nuxt `` or `` components](https://image.nuxtjs.org/components/nuxt-img) to [Astro's own image component](/en/guides/images/#image--astroassets) in `.astro` or `.mdx` files, or to a [standard HTML ``](/en/guides/images/#images-in-ui-framework-components) or `` tag as appropriate in your Vue components. -See a [full list of component attributes](/en/guides/integrations-guide/image/#usage) available for Astro's `` and `` components, and note that several will differ from Nuxt's attributes. +Astro's `` component works in `.astro` and `.mdx` files only. See a [full list of its component attributes](/en/guides/images/#properties) and note that several will differ from Nuxt's attributes. ```astro title="src/pages/index.astro" --- -import { Image } from '@astrojs/image/components'; -import localImage from "../images/brand/logo.png"; -import rocket from '../images/rocket.svg'; +import { Image } from 'astro:assets'; +import rocket from '../assets/rocket.png'; --- -The Astro Logo -A rocketship in space. +A rocketship in space. +A rocketship in space. ``` In Vue (`.vue`) components within your Astro app, use standard JSX image syntax (``). Astro will not optimize these images, but you can install and use NPM packages for more flexibility. diff --git a/src/content/docs/en/guides/rss.mdx b/src/content/docs/en/guides/rss.mdx index ed5d221fc82fb..20915062a0dd8 100644 --- a/src/content/docs/en/guides/rss.mdx +++ b/src/content/docs/en/guides/rss.mdx @@ -47,7 +47,7 @@ The example file below `src/pages/rss.xml.js` will create an RSS feed at `site/r ```js title="src/pages/rss.xml.js" import rss from '@astrojs/rss'; -export function get(context) { +export function GET(context) { return rss({ // `` field in output xml title: 'Buzz’s Blog', @@ -81,7 +81,7 @@ To create an RSS feed of pages managed in [content collections](/en/guides/conte import rss from '@astrojs/rss'; import { getCollection } from 'astro:content'; -export async function get(context) { +export async function GET(context) { const blog = await getCollection('blog'); return rss({ title: 'Buzz’s Blog', @@ -128,7 +128,7 @@ This function assumes, but does not verify, that all necessary feed properties a ```js title="src/pages/rss.xml.js" "pagesGlobToRssItems" "await pagesGlobToRssItems(" import rss, { pagesGlobToRssItems } from '@astrojs/rss'; -export async function get(context) { +export async function GET(context) { return rss({ title: 'Buzz’s Blog', description: 'A humble Astronaut’s guide to the stars', @@ -166,7 +166,7 @@ import sanitizeHtml from 'sanitize-html'; import MarkdownIt from 'markdown-it'; const parser = new MarkdownIt(); -export async function get(context) { +export async function GET(context) { const blog = await getCollection('blog'); return rss({ title: 'Buzz’s Blog', @@ -188,7 +188,7 @@ When using glob imports with Markdown, you may use the `compiledContent()` helpe import rss from '@astrojs/rss'; import sanitizeHtml from 'sanitize-html'; -export function get(context) { +export function GET(context) { const postImportResult = import.meta.glob('../posts/**/*.md', { eager: true }); const posts = Object.values(postImportResult); return rss({ diff --git a/src/content/docs/en/guides/server-side-rendering.mdx b/src/content/docs/en/guides/server-side-rendering.mdx index 7b225bf73cb61..89a06dd874257 100644 --- a/src/content/docs/en/guides/server-side-rendering.mdx +++ b/src/content/docs/en/guides/server-side-rendering.mdx @@ -172,7 +172,7 @@ And for an endpoint: ```js title="src/pages/myendpoint.js" {1} export const prerender = true; -export async function get() { +export async function GET() { return { body: JSON.stringify({ message: `This is my static endpoint` }), }; @@ -186,7 +186,7 @@ For a mostly static site configured as `output: hybrid`, add `export const prere ```js title="src/pages/randomnumber.js" {1} export const prerender = false; -export async function get() { +export async function GET() { let number = Math.random(); return { body: JSON.stringify({ number, message: `Here's a random number: ${number}` }), diff --git a/src/content/docs/en/guides/styling.mdx b/src/content/docs/en/guides/styling.mdx index 129240181a1e8..19bc77b32f38b 100644 --- a/src/content/docs/en/guides/styling.mdx +++ b/src/content/docs/en/guides/styling.mdx @@ -41,11 +41,11 @@ This CSS: Compiles to this: ```astro <style> - h1:where(.astro-HHNQFKH6) { + h1[data-astro-cid-hhnqfkh6] { color: red; } - .text:where(.astro-HHNQFKH6) { + .text[data-astro-cid-hhnqfkh6] { color: blue; } </style> @@ -159,8 +159,7 @@ import MyComponent from "../components/MyComponent.astro" <MyComponent class="red">This will be red!</MyComponent> ``` -This pattern lets you style child components directly. Astro will pass the parent’s scoped class name (e.g. `astro-HHNQFKH6`) through the `class` prop automatically, including the child in its parent’s scope. - +This pattern lets you style child components directly. Astro will pass the parent’s scoped class name (e.g. `astro-hhnqfkh6`) through the `class` prop automatically, including the child in its parent’s scope. Note this pattern only works when your [`scopedStyleStrategy` option](/en/reference/configuration-reference/#scopedstylestrategy) is either `'where'` or `'class'`. :::note[Scoped classes from parent components] Because the `class` prop includes the child in its parent’s scope, it is possible for styles to cascade from parent to child. To avoid this having unintended side effects, ensure you use unique class names in the child component. ::: @@ -531,24 +530,36 @@ If you are using Tailwind, the [typography plugin](https://tailwindcss.com/docs/ ### Bundle control -When Astro builds your site for production deployment it combines your CSS into chunks. Each page on your site is its own chunk, and additionally, CSS that is shared between multiple pages is further split off into their own chunks for reuse. +When Astro builds your site for production deployment, it minifies and combines your CSS into chunks. Each page on your site gets its own chunk, and additionally, CSS that is shared between multiple pages is further split off into their own chunks for reuse. + +However, when you have several pages sharing styles, some shared chunks can become really small. If all of them were sent separately, it would lead to many stylesheets requests and affect site performance. Therefore, by default Astro will link only those in your HTML above 4kB in size as `<link rel="stylesheet">` tags, while inlining smaller ones into `<style type="text/css">`. This approach provides a balance between the number of additional requests and the volume of CSS that can be cached between pages. + +You can configure the size at which stylesheets will be linked externally (in bytes) using the `assetsInlineLimit` vite build option. Note that this option affects script and image inlining as well. + +```js +import { defineConfig } from 'astro/config'; -In each of your HTML files there will be `<link rel="stylesheet">` tags added, one for each of the chunks that the pages needs. +export default defineConfig({ + vite: { + build: { + assetsInlineLimit: 1024, + } + }; +}); +``` -Sites with a large number of pages and many different shared styles can lead to many stylesheet requests and affect site performance. You can configure the `inlineStylesheets` option to reduce the number of these requests by putting (minimized) stylesheets into a `<style>` tag rather than request them externally. +If you would rather all project styles remain external, you can configure the `inlineStylesheets` build option. ```js import { defineConfig } from 'astro/config'; export default defineConfig({ build: { - inlineStylesheets: 'auto' + inlineStylesheets: 'never' } }); ``` -The `'auto'` option will inline only the stylesheets that are below the `vite.build.assetsInlineLimit` threshold, reducing the number of requests for smaller sheets. Larger stylesheets, such as global ones used by all pages, will still be fetched externally and cached. This option provides a balance between the number of stylesheets loaded and the styles that can be cached between pages. - You can also set this option to `'always'` which will inline all stylesheets. ## Advanced diff --git a/src/content/docs/en/guides/troubleshooting.mdx b/src/content/docs/en/guides/troubleshooting.mdx index 1d80ed7c8edb6..8d51a7beec1f9 100644 --- a/src/content/docs/en/guides/troubleshooting.mdx +++ b/src/content/docs/en/guides/troubleshooting.mdx @@ -198,7 +198,7 @@ To help you debug your Astro components, Astro provides a built-in [`<Debug />`] ```astro {2,7} --- -import { Debug } from 'astro/components'; +import { Debug } from 'astro:components'; const sum = (a, b) => a + b; --- @@ -210,7 +210,7 @@ The Debug component supports a variety of syntax options for even more flexible ```astro {2,7-9} --- -import { Debug } from 'astro/components'; +import { Debug } from 'astro:components'; const sum = (a, b) => a + b; const answer = sum(2, 4); --- diff --git a/src/content/docs/en/guides/upgrade-to/v3.mdx b/src/content/docs/en/guides/upgrade-to/v3.mdx new file mode 100644 index 0000000000000..fd3fba8213159 --- /dev/null +++ b/src/content/docs/en/guides/upgrade-to/v3.mdx @@ -0,0 +1,640 @@ +--- +title: Upgrade to Astro v3 +description: How to upgrade your project to the latest version of Astro (v3.0). +i18nReady: true +--- +import PackageManagerTabs from '~/components/tabs/PackageManagerTabs.astro' +import FileTree from '~/components/FileTree.astro' + + +This guide will help you migrate from Astro v2 to Astro v3. + +Need to upgrade an older project to v2? See our [older migration guide](/en/guides/upgrade-to/v2/). + +## Upgrade Astro + +Update your project's version of Astro to the latest version using your package manager. If you're using Astro integrations, please also update those to the latest version. + +<PackageManagerTabs> + <Fragment slot="npm"> + ```shell + # Upgrade to Astro v3.x + npm install astro@latest + + # Example: upgrade React and Tailwind integrations + npm install @astrojs/react@latest @astrojs/tailwind@latest + ``` + </Fragment> + <Fragment slot="pnpm"> + ```shell + # Upgrade to Astro v3.x + pnpm install astro@latest + + # Example: upgrade React and Tailwind integrations + pnpm install @astrojs/react@latest @astrojs/tailwind@latest + ``` + </Fragment> + <Fragment slot="yarn"> + ```shell + # Upgrade to Astro v3.x + yarn add astro@latest + + # Example: upgrade React and Tailwind integrations + yarn add @astrojs/react@latest @astrojs/tailwind@latest + ``` + </Fragment> +</PackageManagerTabs> + +:::note[Need to continue?] +After upgrading Astro to the latest version, you may not need to make any changes to your project at all! + +But, if you notice errors or unexpected behavior, please check below for what has changed that might need updating in your project. +::: + +## Astro v3.0 Experimental Flags Removed + +Remove the following experimental flags from `astro.config.mjs`: + +```js del={5-8} +// astro.config.mjs +import { defineConfig } from 'astro/config'; + +export default defineConfig({ + experimental: { + assets: true, + viewTransitions: true, + }, +}) +``` + +These features are now available by default: + +- View Transitions for animated page transitions and persistent islands. See [view transitions API breaking changes and upgrading advice](/en/guides/view-transitions/#upgrade-to-v30-from-v2x) if you were using this experimental flag. +- A new image services API `astro:assets` for using images in Astro, including a new `<Image />` component and `getImage()` function. Please read the detailed [image upgrade advice](/en/guides/images/#upgrade-to-v30-from-v2x) **whether or not you were using this experimental flag** to see how this might affect your project. + +Read more about these two exciting features and more in the 3.0 Blog post! + + + +## Astro v3.0 Breaking Changes + +Astro v3.0 includes some breaking changes, as well as the removal of some previously deprecated features. If your project doesn't work as expected after upgrading to v3.0, check this guide for an overview of all breaking changes and instructions on how to update your codebase. + +See [the changelog](https://github.com/withastro/astro/blob/main/packages/astro/CHANGELOG.md) for full release notes. + +### Removed: Support for Node 16 + +Node 16 is scheduled to reach its End of Life in September 2023. + +Astro v3.0 drops Node 16 support entirely so that all Astro users can take advantage of Node's more modern features. + +#### What should I do? + + Check that both your development environment and your deployment environment are using **Node `18.14.1` or higher**. + +1. Check your local version of Node using: + + ```sh + node -v + ``` + + + +2. Check your [deployment environment's](/en/guides/deploy/) own documentation to verify that they support Node 18. + + You can specify Node `18.14.1` for your Astro project either in a dashboard configuration setting or a `.nvmrc` file. + +```bash title=".nvmrc" +18.14.1 +``` +### Removed: Support for TypeScript 4 + +In Astro v2.x, the `tsconfig.json` presets include support for both TypeScript 4.x and 5.x. + +Astro v3.0 updates the `tsconfig.json` presets to only support TypeScript 5.x. Astro now assumes that you use TypeScript 5.0 (March 2023), or that your editor includes it (e.g. VS Code 1.77). + +#### What should I do? + +If you have installed TypeScript locally, update to at least v5.0. + +```bash +npm install typescript@latest --save-dev +``` + +### Removed: `@astrojs/image` + +In Astro v2.x, Astro offered an official image integration that included Astro `<Image />` and `<Picture />` components. + +Astro v3.0 removes this integration from the codebase entirely. Astro's new solution for images is a built-in image services API: `astro:assets`. + +#### What should I do? + +Remove the `@astrojs/image` integration from your project. You will need to not only uninstall the integration but also update or remove any import statements and existing `<Image />` and `<Picture />` components. You might also need to configure a preferred default image processing service. + +You will find [complete, step-by-step instructions for removing the old image integration](/en/guides/images/#remove-astrojsimage) in our Images guide. + +Migrating to `astro:assets` will also bring some new image options and features that you may now wish to use. Please see the full [v3.0 Image Upgrade Advice](/en/guides/images/#upgrade-to-v30-from-v2x) for full details! + +```js del={3,7} +// astro.config.mjs +import { defineConfig } from 'astro/config'; +import image from '@astrojs/image'; + +export default defineConfig({ + integrations: [ + image(), + ] +}) +``` + +### Removed: `<Markdown />` component + +In Astro v1.x, Astro deprecated the `<Markdown />` component and moved it to an external package. + +Astro v3.0 completely removes the package `@astrojs/markdown-component`. Astro's `<Markdown />` component will no longer work in your project. + +#### What should I do? + +Remove all instances of the `@astrojs/markdown-component`. + +```astro del={2} title="src/components/MyAstroComponent.astro" +--- +import Markdown from '@astrojs/markdown-component'; +--- +``` + +To continue using a similar `<Markdown />` component in your code, consider using [community integrations](https://astro.build/integrations/) such as [`astro-remote`](https://github.com/natemoo-re/astro-remote). Be sure to update your `<Markdown />` component imports and attributes as necessary, according to the integration's own documentation. + +Otherwise, delete all references to importing Astro's `<Markdown />` component and the component itself in your `.astro` files. You will need to rewrite your content as HTML directly or [import Markdown](/en/guides/markdown-content/#importing-markdown) from a `.md` file. + +### Removed: deprecated 1.x APIs + +In Astro v1.x, Astro deprecated config options as well as script/style `global` and `hoist` attributes types. These were kept for backwards compatibility. + +Astro v3.0 removes these deprecated APIs entirely. They can no longer be used in your Astro project. + +#### What should I do? + +If you are continuing to use v1.x APIs, use the new APIs for each feature instead: + +- Deprecated config options: See [the 0.26 migration guide](/en/guides/upgrade-to/v1/#new-configuration-api) +- Deprecated script/style attribute types: See [the 0.26 migration guide](/en/guides/upgrade-to/v1/#new-default-script-behavior) + +### Removed: `image` from `astro:content` in content collections schema + +In Astro v2.x, the content collections API deprecated an `image` export from `astro:content` for use in your content collections schemas. + +Astro v3.0 removes this export entirely. + +#### What should I do? + +If you are using the deprecated `image()` from `astro:content`, remove it as this no longer exists. Validate images through [the `image` helper from `schema`](/en/guides/images/#update-content-collections-schemas) instead: + + ```ts title="astro.config.mjs" del={1} ins={2} "({ image })" +import { defineCollection, z, image } from "astro:content"; +import { defineCollection, z } from "astro:content"; + + defineCollection({ + schema: ({ image }) => + z.object({ + image: image(), + }), +}); +``` + +### Removed: pre-0.14 Shiki theme names + +In Astro v2.x, some Shiki theme names had been renamed, but the original names were kept for backwards compatibility. + +Astro v3.0 removes the original names in favor of the renamed theme names. + +#### What should I do? + +If your project uses any of the themes below, rename them to their updated name: + +- `material-darker` -> `material-theme-darker` +- `material-default` -> `material-theme` +- `material-lighter` -> `material-theme-lighter` +- `material-ocean` -> `material-theme-ocean` +- `material-palenight` -> `material-theme-palenight` + +### Removed: `class:list` features + +In Astro v2.x, the [`class:list` directive](/en/reference/directives-reference/#classlist) used a custom implementation inspired by [`clsx`](https://github.com/lukeed/clsx) with a few extra features like deduplication and `Set` support. + +Astro v3.0 now uses `clsx` directly for `class:list`, which does not support deduplication or `Set` values. + +#### What should I do? + +Replace any `Set` elements passed to the `class:list` directive with a plain `Array`. + +```astro title="src/components/MyAstroComponent.astro" del={4} ins={5} +<Component class:list={[ + 'a', + 'b', + new Set(['c', 'd']) + ['c', 'd'] +]} /> +``` + +### Removed: passing `class:list` as a prop + +In Astro v2.x, [`class:list` values](/en/reference/directives-reference/#classlist) were sent to components via [`Astro.props['class:list']`](/en/reference/api-reference/#astroprops). + +Astro v3.0 normalizes `class:list` values into a string before being sent to components via `Astro.props['class']` + +#### What should I do? + +Remove any code that expects to receive the `class:list` prop. + +```astro title="src/components/MyAstroComponent.astro" del={2,3,7} ins={4,8} "classList" "'class:list': classList" +--- +import { clsx } from 'clsx'; +const { class: className, 'class:list': classList } = Astro.props; +const { class: className } = Astro.props; +--- +<div + class:list={[className, classList]} + class:list={[className]} +/> +``` + +### Removed: kebab-case transform for camelCase CSS variables + +In Astro v2.x, camelCase [CSS variables](/en/guides/styling/#css-variables) passed to the `style` attribute were rendered as both camelCase (as written) and kebab-case (kept for backwards compatibility). + +Astro v3.0 removes the kebab-case transform for these camelCase CSS variable names, and only the original camelCase CSS variable is rendered. + +```astro "my-value" +--- +// src/components/MyAstroComponent.astro +const myValue = "red" +--- +<!-- input --> +<div style={{ "--myValue": myValue }}></div> + +<!-- output (Astro 2.x) --> +<div style="--my-value:var(--myValue);--myValue:red"></div> +<!-- output (Astro 3.0) --> +<div style="--myValue:red"></div> +``` + +#### What should I do? + +If you were relying on Astro to transform kebab-case in your styles, update your existing styles to camelCase to prevent missing styles. For example: + +```astro del={3} ins={4} title="src/components/MyAstroComponent.astro" +<style> + div { + color: var(--my-value); + color: var(--myValue); + } +</style> +``` + +### Removed: automatic flattening of `getStaticPaths()`'s return value + +In Astro v2.x, the return value of [`getStaticPaths()`](/en/reference/api-reference/#getstaticpaths) was automatically flattened to allow you to return an array of arrays without errors. + +Astro v3.0 removes automatic flattening of `getStaticPaths()`'s result. + +#### What should I do? + +If you're returning an array of arrays instead of an array of _objects_ (as is expected), `.flatMap` and `.flat` should now be used to ensure that you are returning a flat array. + +An [error message indicating that `getStaticPath()`'s return value must be an array of objects](/en/reference/errors/invalid-get-static-paths-entry/#what-went-wrong) will be provided if you need to update your code. + +### Moved: `astro check` now requires an external package + +In Astro v2.x, [`astro check`](/en/reference/cli-reference/#astro-check) was included in Astro by default, and its dependencies were bundled in Astro. This meant a larger package whether or not you ever used `astro check`. This also prevented you from having control over the version of TypeScript and the Astro Language Server to use. + + +Astro v3.0 moves the `astro check` command out of Astro core and now requires an external package `@astrojs/check`. Additionally, you must install `typescript` in your project to use the `astro check` command. + +#### What should I do? + +Run the `astro check` command after upgrading to Astro v3.0 and follow the prompts to install the required dependencies, or manually install `@astrojs/check` and `typescript` into your project. + +### Deprecated: `build.excludeMiddleware` and `build.split` + +In Astro v2.x, `build.excludeMiddleware` and `build.split` were used to change how specific files were emitted when using an adapter in SSR mode. + +Astro v3.0 replaces these build config options with new [SSR adapter configuration options](/en/guides/integrations-guide/#official-integrations) to perform the same tasks: `edgeMiddleware` and `functionPerRoute`. + +#### What should I do? + +Update the Astro config file to now use the new options **in the adapter configuration** directly. + +```js title="astro.config.mjs" del={5-7} ins={9} +import { defineConfig } from "astro/config"; +import vercel from "@astrojs/vercel/serverless"; + +export default defineConfig({ + build: { + excludeMiddleware: true + }, + adapter: vercel({ + edgeMiddleware: true + }), +}); +``` + +```js title="astro.config.mjs" del={5-7} ins={9} +import { defineConfig } from "astro/config"; +import netlify from "@astrojs/netlify/functions"; + +export default defineConfig({ + build: { + split: true + }, + adapter: netlify({ + functionPerRoute: true + }), +}); +``` + +### Deprecated: `markdown.drafts` + +In Astro v2.x, the `markdown.drafts` configuration allowed you to have draft pages that were available in when running the dev server, but not built in production. + +Astro v3.0 deprecates this feature in favor of the content collections method of handling draft pages by filtering manually instead, which gives more control over the feature. + +#### What should I do? + +To continue to mark some pages in your project as drafts, [migrate to content collections](/en/guides/content-collections/#migrating-from-file-based-routing) and [manually filter out pages](/en/guides/content-collections/#filtering-collection-queries) with the `draft: true` frontmatter property instead. + +### Deprecated: returning simple object in endpoints + +In Astro v2.x, endpoints could return a simple object, which would be converted to a JSON response. + +Astro v3.0 deprecates this behavior in favor of returning a `Response` object directly. + +#### What should I do? + +Update your endpoints to return a `Response` object directly. + +```ts title="endpoint.json.ts" del={2} ins={3} +export async function GET() { + return { body: { "title": "Bob's blog" }}; + return new Response(JSON.stringify({ "title": "Bob's blog" })); +} +``` + +If you really need to keep the previous format, you can use the `ResponseWithEncoding` object but will be deprecated in the future. + +```ts title="endpoint.json.ts" del={2} ins={3} +export async function GET() { + return { body: { "title": "Bob's blog" } }; + return new ResponseWithEncoding({ body: { "title": "Bob's blog" }}); +} +``` + +### Changed default: port `3000` + +In Astro v2.x, Astro ran on port `3000` by default. + +Astro v3.0 changes the [default port](/en/reference/cli-reference/#--port-number) to `4321`. 🚀 + +#### What should I do? + +Update any existing references to `localhost:3000`, for example in tests or in your `README`, to reflect the new port `localhost:4321`. + + +### Changed default: import.meta.env.BASE_URL `trailingSlash` + +In Astro v2.x, `import.meta.env.BASE_URL` appended your [`base`](/en/reference/configuration-reference/#base) setting with a [trailingSlash](/en/reference/configuration-reference/#trailingslash) by default. `trailingSlash: "ignore"` also appended a trailing slash. + +Astro v3.0 no longer appends `import.meta.env.BASE_URL` with a trailing slash by default, nor when `trailingSlash: "ignore"` is set. (The existing behavior of `base` in combination with `trailingSlash: "always"` or `trailingSlash: "never"` is unchanged.) + +#### What should I do? + +If your `base` already has a trailing slash, no change is needed. + +If your `base` does not have a trailing slash, add one if you wish to preserve the previous default (or `trailingSlash: "ignore"`) behavior: + +```js title="astro.config.mjs" del={4} ins={5} +import { defineConfig } from "astro/config"; + +export default defineConfig({ + base: 'my-base', + base: 'my-base/', +}); +``` + +### Changed default: `compressHTML` + +In Astro v2.x, Astro only compressed your emitted HTML when [`compressHTML`](/en/reference/configuration-reference/#compresshtml) was explicitly set to `true`. The default value was `false`. + +Astro v3.0 now compresses emitted HTML by default. + +#### What should I do? + +You can now remove `compressHTML: true` from your configuration as this is the new default behavior. + +```js title="astro.config.mjs" del={4} +import { defineConfig } from "astro/config"; + +export default defineConfig({ + compressHTML: true +}) +``` + +You must now set `compressHTML: false` to opt out of HTML compression. + +### Changed default: `scopedStyleStrategy` + +In Astro v2.x, the default value of [`scopedStyleStrategy`](/en/reference/configuration-reference/#scopedstylestrategy) was `"where"`. + +Astro v3.0 introduces a new, default value: `"attribute"`. By default, styles are now applied using `data-*` attributes. + +#### What should I do? + +To retain your project's current [style scoping](/en/guides/styling/#scoped-styles), update the configuration file to the previous default value: + + +```js title="astro.config.mjs" ins={4} +import { defineConfig } from "astro/config"; + +export default defineConfig({ + scopedStyleStrategy: "where" +}) +``` + +### Changed default: `inlineStyleSheets` + +In Astro v2.x, all project stylesheets were sent as link tags by default. You could opt in to inlining them into `<style>` tags every time with `"always"`, or to inlining only stylesheets below a certain size with `"auto"` by setting the [`build.inlineStylesheets`](/en/reference/configuration-reference/#buildinlinestylesheets) configuration. The default setting was `"never"`. + +Astro v3.0 changes the default value of `inlineStylesheets` to `"auto"`. Stylesheets smaller than `ViteConfig.build.assetsInlineLimit` (default: 4kb) are inlined by default. Otherwise, project styles are sent in external stylesheets. + +#### What should I do? +If you want to keep your project's current behavior, set `build.inlineStylesheets` to the previous default, `"never"`: + + +```js title="astro.config.mjs" ins={4-6} +import { defineConfig } from "astro/config"; + +export default defineConfig({ + build: { + inlineStylesheets: "never" + } +}) +``` + +### Changed default: image service + +In Astro v2.x, Squoosh was the [default image processing service](/en/guides/images/#default-image-service). + +Astro v3.0 now includes Sharp as the default image processing service and instead provides a configuration option to use Squoosh. + +#### What should I do? + +If you would prefer to continue to use Squoosh to transform your images, update your config with the following: + +```ts title="astro.config.mjs" ins={4-6} +import { defineConfig, squooshImageService } from "astro/config"; + +export default defineConfig({ + image: { + service: squooshImageService(), + } +}) +``` + +### Changed: HTTP request methods case + +In Astro v2.x, [HTTP request methods](/en/core-concepts/endpoints/#http-methods) were written using lowercase function names: `get`, `post`, `put`, `all`, and `del`. + +Astro v3.0 uses uppercase function names, including `DELETE` instead of `del`. + +#### What should I do? + +Rename all functions to their uppercase equivalent: + +- `get` to `GET` +- `post` to `POST` +- `put` to `PUT` +- `all` to `ALL` +- `del` to `DELETE` + +```js title="endpoint.ts" del={1} ins={2} +export function get() { +export function GET() { + return new Response(JSON.stringify({ "title": "Bob's blog" })); +} +``` + +### Changed: Multiple JSX framework configuration + +In Astro v2.x, you could use [multiple JSX framework integrations](/en/guides/integrations-guide/#official-integrations) (React, Solid, Preact) in the same project without needing to identify which files belonged to which framework. + +Astro v3.0 now requires you to specify which framework to use for your files with new `include` and `exclude` integration config options when you have multiple JSX framework integrations installed. This allows Astro to better support single-framework usage, as well as advanced features like React Fast Refresh. + +#### What should I do? + +If you are using multiple JSX frameworks in the same project, set `include` (and optionally `exclude`) to an array of files and/or folders. Wildcards may be used to include multiple file paths. + +We recommend placing common framework components in the same folder (e.g. `/components/react/` and `/components/solid/`) to make specifying your includes easier, but this is not required: + +```js ins={13,16,19} +import { defineConfig } from 'astro/config'; +import preact from '@astrojs/preact'; +import react from '@astrojs/react'; +import svelte from '@astrojs/svelte'; +import vue from '@astrojs/vue'; +import solid from '@astrojs/solid-js'; + +export default defineConfig({ + // Enable many frameworks to support all different kinds of components. + // No `include` is needed if you are only using a single framework! + integrations: [ + preact({ + include: ['**/preact/*'] + }), + react({ + include: ['**/react/*'] + }), + solid({ + include: ['**/solid/*'], + }), + ] +}); +``` + +### Changed: `Astro.cookies.get(key)` can return `undefined` + +In Astro v2.x, [`Astro.cookies.get(key)`](/en/reference/api-reference/#astrocookies) would always return an [`AstroCookie` object](/en/reference/api-reference/#astrocookie), even if the cookie did not exist. To check for its existence, you needed to use `Astro.cookies.has(key)`. + +Astro v3.0 returns `undefined` for `Astro.cookies.get(key)` if the cookie does not exist. + +#### What should I do? + +This change will not break any code that checks for the existence of the `Astro.cookie` object before using `Astro.cookies.get(key)`, but is now no longer required. + +You can safely remove any code that uses `has()` to check if the value of `Astro.cookies` is `undefined`: + +```js del={1-3} ins={5-7} +if (Astro.cookies.has(id)) { + const id = Astro.cookies.get(id)!; +} + +const id = Astro.cookies.get(id); +if (id) { +} +``` + +### Changed: running the Astro CLI programmatically + +In Astro v2.x, the `"astro"` package entrypoint exported and ran the Astro CLI directly. It is not recommended to run Astro this way in practice. + +Astro v3.0 removes the CLI from the entrypoint, and exports a new set of experimental JavaScript APIs, including `dev()`, `build()`, `preview()`, and `sync()`. + +#### What should I do? + +To [run the Astro CLI programatically](/en/reference/cli-reference/#advanced-apis-experimental), use the new experimental JavaScript APIs: + +```js +import { dev, build } from "astro"; + +// Start the Astro dev server +const devServer = await dev(); +await devServer.stop(); + +// Build your Astro project +await build(); +``` + + +### Changed: internal Astro API entry point export paths + +In Astro v2.x, you could import internal Astro APIs from `astro/internal/*` and `astro/runtime/server/*`. + +Astro v3.0 removes the two entry points in favor of the existing `astro/runtime/*` entrypoint. Additionally, a new `astro/compiler-runtime` export has been added for compiler-specific runtime code. + +#### What should I do? + +These are entry points for Astro's internal API and should not affect your project. But if you do use these entrypoints, update as shown below: + +```js del={1,4,10} ins={2,5,11} +import 'astro/internal/index.js'; +import 'astro/runtime/server/index.js'; + +import 'astro/server/index.js'; +import 'astro/runtime/server/index.js'; +``` + +```js ins={5} del={4} +import { transform } from '@astrojs/compiler'; + +const result = await transform(source, { + internalURL: 'astro/runtime/server/index.js', + internalURL: 'astro/compiler-runtime', + // ... +}); +``` + + + +## Known Issues + +There are currently no known issues. + diff --git a/src/content/docs/en/guides/view-transitions.mdx b/src/content/docs/en/guides/view-transitions.mdx index e70eb38d63f71..81193b5cc1b92 100644 --- a/src/content/docs/en/guides/view-transitions.mdx +++ b/src/content/docs/en/guides/view-transitions.mdx @@ -1,52 +1,56 @@ --- -title: View Transitions (Experimental) +title: View Transitions description: >- - How to enable experimental support for view transitions in your Astro site. + Enable seamless navigation between pages in Astro with view transitions. i18nReady: true --- import Since from '~/components/Since.astro' -Support for **opt-in, per-page, view transitions** in Astro projects can be enabled behind an experimental flag. View transitions update your page content without the browser's normal, full-page navigation refresh and provide seamless animations between pages. +Astro supports **opt-in, per-page, view transitions** with just a few lines of code. View transitions update your page content without the browser's normal, full-page navigation refresh and provide seamless animations between pages. -Astro provides a `<ViewTransitions />` routing component that can be added to a single page's `<head>` to control page transitions as you navigate away to another page. It provides a lightweight client-side router that intercepts navigation and allows you to customize the transition between pages. Add this component to a reusable `.astro` component, such as a common head or layout, for animated page transitions across your entire site (SPA mode). +Astro provides a `<ViewTransitions />` routing component that can be added to a single page's `<head>` to control page transitions as you navigate away to another page. It provides a lightweight client-side router that [intercepts navigation](#client-side-navigation-process) and allows you to customize the transition between pages. + +Add this component to a reusable `.astro` component, such as a common head or layout, for [animated page transitions across your entire site (SPA mode)](#full-site-view-transitions-spa-mode). Astro's view transitions support is powered by the new [View Transitions](https://developer.chrome.com/docs/web-platform/view-transitions/) browser API and also includes: -- A few [built-in animations](#built-in-animation-directives), such as `slide` and `fade`. +- A few [built-in animation options](#built-in-animation-directives), such as `fade`, `slide`, and `none`. - Support for both forwards and backwards navigation animations. - The ability to fully [customize all aspects of transition animation](#customizing-animations), and build your own animations. +- The option to [prevent client-side navigation for non-page links](#preventing-client-side-navigation). - [Control over fallback behavior](#fallback-control) for browsers that do not yet support the View Transition APIs. +- Automatic support for [`prefers-reduced-motion`](#prefers-reduced-motion). -:::caution -View transitions is an experimental feature enabled in Astro 2.9. The API is subject to change before it is marked as stable. -::: -## Enabling View Transitions in your Project +:::note +By default, every page will use regular, full-page, browser navigation. You must opt in to view transitions and can use them either on a per-page basis or site-wide. +::: -You can enable support for animated page transitions through the experimental `viewTransitions` flag in your Astro config: +## Adding View Transitions to a Page -```js title="astro.config.mjs" ins={4-6} -import { defineConfig } from 'astro/config'; +Opt in to using view transitions on individual pages by importing and adding the `<ViewTransitions />` routing component to `<head>` on every desired page. -export default defineConfig({ - experimental: { - viewTransitions: true - } -}); +```astro title="src/pages/index.astro" ins={2,7} +--- +import { ViewTransitions } from 'astro:transitions'; +--- +<html lang="en"> + <head> + <title>My Homepage + + + +

Welcome to my website!

+ + ``` -:::note -Enabling view transitions support does not automatically convert your entire site into a SPA (Single-page App). By default, every page will still use regular, full-page, browser navigation. - -Add page transitions in Astro with the `` routing component on a per-page basis, or site-wide. -::: - ## Full site view transitions (SPA mode) -Import and add the `` component to your common `` or shared layout component. Astro will create default page animations based on the similiarities between the old and new page, and will also provide fallback behavior for unsupported browsers. +Import and add the `` component to your common `` or shared layout component. Astro will create default page animations based on the similarities between the old and new page, and will also provide fallback behavior for unsupported browsers. -The example below shows adding view transitions site-wide by importing and adding this component to a `` Astro component: +The example below shows adding Astro's default page navigation animations site-wide, including the default fallback control option for non-supporting browsers, by importing and adding this component to a `` Astro component: ```astro title="components/CommonHead.astro" ins={2,12} --- @@ -63,7 +67,9 @@ import { ViewTransitions } from 'astro:transitions'; ``` -You can also add view transitions on a per-page basis. Import the `` component and place it directly inside of a page's ``. +No other configuration is necessary to enable Astro's default client-side navigation! + +Use [transition directives](#transition-directives) or [override default client-side navigation](#preventing-client-side-navigation) on individual elements for finer control. ## Transition Directives @@ -76,7 +82,7 @@ Use optional `transition:*` directives on page elements in your `.astro` compone - `transition:persist`: Allows you to override Astro's default replacing old elements for new ones and instead [persist components and HTML elements](#maintaining-state) when navigating to another page. -## Naming a transition +### Naming a transition In some cases, you may want or need to identify the corresponding view transition elements yourself. You can specify a name for a pair of elements using the `transition:name` directive. @@ -88,9 +94,9 @@ In some cases, you may want or need to identify the corresponding view transitio