diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 3ba8a385a4e8d..c0127b063d4bc 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -156,7 +156,7 @@ pnpm install pnpm start ``` -If you’re copying these instructions, remember to [configure this project as a fork](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/configuring-a-remote-for-a-fork). +If you’re copying these instructions, remember to [configure this project as a fork](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/configuring-a-remote-repository-for-a-fork). ```shell git remote add upstream git@github.com:withastro/docs.git diff --git a/package.json b/package.json index 5274777cc5830..ebbde7951cef7 100644 --- a/package.json +++ b/package.json @@ -77,8 +77,8 @@ "p-retry": "^5.1.1", "parse-numeric-range": "^1.3.0", "preact": "^10.10.1", - "prettier": "^2.8.1", - "prettier-plugin-astro": "^0.7.0", + "prettier": "^2.8.8", + "prettier-plugin-astro": "^0.8.0", "prompts": "^2.4.2", "rehype": "^12.0.1", "remark": "^14.0.2", diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml index aed1bb8f91a7e..00937088e561f 100644 --- a/pnpm-lock.yaml +++ b/pnpm-lock.yaml @@ -178,11 +178,11 @@ devDependencies: specifier: ^10.10.1 version: 10.10.1 prettier: - specifier: ^2.8.1 - version: 2.8.1 + specifier: ^2.8.8 + version: 2.8.8 prettier-plugin-astro: - specifier: ^0.7.0 - version: 0.7.0 + specifier: ^0.8.0 + version: 0.8.0 prompts: specifier: ^2.4.2 version: 2.4.2 @@ -422,7 +422,7 @@ packages: dependencies: '@vscode/emmet-helper': 2.8.4 events: 3.3.0 - prettier: 2.8.1 + prettier: 2.8.8 prettier-plugin-astro: 0.7.0 source-map: 0.7.4 vscode-css-languageservice: 6.0.1 @@ -5352,13 +5352,23 @@ packages: engines: {node: ^14.15.0 || >=16.0.0, npm: '>=6.14.0'} dependencies: '@astrojs/compiler': 0.29.13 - prettier: 2.8.1 + prettier: 2.8.8 sass-formatter: 0.7.5 synckit: 0.8.4 dev: true - /prettier@2.8.1: - resolution: {integrity: sha512-lqGoSJBQNJidqCHE80vqZJHWHRFoNYsSpP9AjFhlhi9ODCJA541svILes/+/1GM3VaL/abZi7cpFzOpdR9UPKg==} + /prettier-plugin-astro@0.8.0: + resolution: {integrity: sha512-kt9wk33J7HvFGwFaHb8piwy4zbUmabC8Nu+qCw493jhe96YkpjscqGBPy4nJ9TPy9pd7+kEx1zM81rp+MIdrXg==} + engines: {node: ^14.15.0 || >=16.0.0, pnpm: '>=7.14.0'} + dependencies: + '@astrojs/compiler': 1.3.2 + prettier: 2.8.8 + sass-formatter: 0.7.5 + synckit: 0.8.4 + dev: true + + /prettier@2.8.8: + resolution: {integrity: sha512-tdN8qQGvNjw4CHbY+XXk0JgCXn9QiF21a55rBe5LJAU+kDyC4WQn4+awm2Xfk2lQMk5fKup9XgzTZtGkjBdP9Q==} engines: {node: '>=10.13.0'} hasBin: true dev: true diff --git a/src/components/PageContent/PageContent.astro b/src/components/PageContent/PageContent.astro index 7e4360ad3ab38..da4dab73c551f 100644 --- a/src/components/PageContent/PageContent.astro +++ b/src/components/PageContent/PageContent.astro @@ -20,14 +20,13 @@ const title = content.title .replace('@astrojs/', '@astrojs/') .replaceAll('-', '⁠-⁠'); const isFallback = !!Astro.params.fallback || undefined; -const outdated = - Astro.params.lang === 'en' || Astro.params.fallback - ? false - : await isOutdated( - ( - await getEntryBySlug('docs', `${Astro.params.lang}/${Astro.params.slug}`) - )?.id! - ); +let outdated: boolean; +if (Astro.params.lang === 'en' || Astro.params.fallback) { + outdated = false; +} else { + const currentEntry = await getEntryBySlug('docs', `${Astro.params.lang}/${Astro.params.slug}`); + outdated = await isOutdated(currentEntry?.id!); +} const lang = getLanguageFromURL(Astro.url.pathname); const bcpLang = normalizeLangTag(lang); const direction = rtlLanguages.has(lang) ? 'rtl' : 'ltr'; diff --git a/src/components/RecipeLinks.astro b/src/components/RecipeLinks.astro index 9eb664d4beaa5..af3dca0df5a5d 100644 --- a/src/components/RecipeLinks.astro +++ b/src/components/RecipeLinks.astro @@ -1,6 +1,7 @@ --- import { recipePages } from '~/content'; import { getLanguageFromURL, stripLangFromSlug } from '~/util'; +import UIString from './UIString.astro'; export interface Props { slugs: string[]; @@ -24,7 +25,7 @@ const recipes = Astro.props.slugs.map((slug) => { }); const isList = recipes.length > 1; -const noun = isList ? 'recipes' : 'recipe'; +const labelKey = isList ? 'recipesLink.plural' : 'recipesLink.singular'; const firstRecipe = recipes[0]; if (!firstRecipe) { throw new Error('No slugs passed to `` component. Make sure you pass at least one.'); @@ -34,7 +35,7 @@ if (!firstRecipe) {
- Related {noun}: + { !isList && ( diff --git a/src/components/tabs/AstroJSXTabs.astro b/src/components/tabs/AstroJSXTabs.astro index 275ae9f7d63b2..5832006548ecf 100644 --- a/src/components/tabs/AstroJSXTabs.astro +++ b/src/components/tabs/AstroJSXTabs.astro @@ -6,12 +6,12 @@ import Tabs from './Tabs'; JSX Astro - + + - + + diff --git a/src/components/tabs/AstroVueTabs.astro b/src/components/tabs/AstroVueTabs.astro index 009f82488401f..f1dc5c7284842 100644 --- a/src/components/tabs/AstroVueTabs.astro +++ b/src/components/tabs/AstroVueTabs.astro @@ -6,12 +6,12 @@ import Tabs from './Tabs'; Vue Astro - + + - + + diff --git a/src/components/tutorial/TutorialNav.astro b/src/components/tutorial/TutorialNav.astro index f769c45108d28..269cae9c28482 100644 --- a/src/components/tutorial/TutorialNav.astro +++ b/src/components/tutorial/TutorialNav.astro @@ -19,7 +19,7 @@ const tutorialPages = getTutorialPages(pages, lang); const units = getTutorialUnits(tutorialPages); const makeUnitId = (index: number) => `${Astro.props.id}__tutorial-unit-nav-panel-${index}`; -const isCurrentUnit = (unit: typeof units[number]) => +const isCurrentUnit = (unit: (typeof units)[number]) => unit.lessons.some((lesson) => currentUrl.endsWith(lesson.slug)); --- diff --git a/src/content/docs/en/core-concepts/project-structure.mdx b/src/content/docs/en/core-concepts/project-structure.mdx index 1b0550f28d2d3..7f4faec74131e 100644 --- a/src/content/docs/en/core-concepts/project-structure.mdx +++ b/src/content/docs/en/core-concepts/project-structure.mdx @@ -62,12 +62,20 @@ Astro processes, optimizes, and bundles your `src/` files to create the final we Some files (like Astro components) are not even sent to the browser as written but are instead rendered to static HTML. Other files (like CSS) are sent to the browser but may be optimized or bundled with other CSS files for performance. +### `src/assets` + +The [`src/assets`](/en/guides/assets/) directory is the recommended folder to use for storing assets (e.g. images) that are processed by Astro. This is not required, and this is not a special reserved folder. + ### `src/components` **Components** are reusable units of code for your HTML pages. These could be [Astro components](/en/core-concepts/astro-components/), or [UI framework components](/en/core-concepts/framework-components/) like React or Vue. It is common to group and organize all of your project components together in this folder. This is a common convention in Astro projects, but it is not required. Feel free to organize your components however you like! +### `src/content` + +The `src/content/` directory is reserved to store [content collections](/en/guides/content-collections/) and an optional collections configuration file. No other files are allowed inside this folder. + ### `src/layouts` [Layouts](/en/core-concepts/layouts/) are a special kind of component that wrap some content in a larger page layout. These are most often used by [Astro pages](/en/core-concepts/astro-pages/) and [Markdown or MDX pages](/en/guides/markdown-content/) to define the layout of the page. diff --git a/src/content/docs/en/editor-setup.mdx b/src/content/docs/en/editor-setup.mdx index 69411824004ff..2133846cfd39d 100644 --- a/src/content/docs/en/editor-setup.mdx +++ b/src/content/docs/en/editor-setup.mdx @@ -53,6 +53,12 @@ In addition to local editors, Astro also runs well on in-browser hosted editors, See [the project's User Guide](https://ota-meshi.github.io/eslint-plugin-astro/user-guide/) for more information on how to install and set up ESLint for your project. +### Stylelint + +[Stylelint](https://stylelint.io/) is a popular linter for CSS. [A community maintained Stylelint configuration](https://github.com/ota-meshi/stylelint-config-html) provides Astro support. + +Installation instructions, editor integration, and additional information can be found in the project's README. + ### Prettier [Prettier](https://prettier.io/) is a popular formatter for JavaScript, HTML, CSS, and more. If you're using the [Astro VS Code Extension](https://marketplace.visualstudio.com/items?itemName=astro-build.astro-vscode) or [the Astro language server within another editor](#other-code-editors), code formatting with Prettier is included. diff --git a/src/content/docs/en/guides/backend.mdx b/src/content/docs/en/guides/backend.mdx index 2ea3eee920a7c..6954aaf156a6e 100644 --- a/src/content/docs/en/guides/backend.mdx +++ b/src/content/docs/en/guides/backend.mdx @@ -20,8 +20,8 @@ A backend service is a cloud-based system that helps you build and manage your b ## Why would I use a backend service? You might want to consider a backend service if your project has complex server-side needs, for example: -- user signups and authentication -- persistant data storage +- user sign-ups and authentication +- persistent data storage - user-uploaded asset storage - API generation - realtime communication diff --git a/src/content/docs/en/guides/backend/google-firebase.mdx b/src/content/docs/en/guides/backend/google-firebase.mdx index 71d5bbffe6c23..4ca50e555ee37 100644 --- a/src/content/docs/en/guides/backend/google-firebase.mdx +++ b/src/content/docs/en/guides/backend/google-firebase.mdx @@ -112,7 +112,7 @@ const firebaseConfig = { apiKey: "my-public-api-key", authDomain: "my-auth-domain", projectId: "my-project-id", - storageBucket: "my-storage-bucket, + storageBucket: "my-storage-bucket", messagingSenderId: "my-sender-id", appId: "my-app-id", }; @@ -186,7 +186,7 @@ Create three endpoints related to authentication in a new directory `src/pages/a ```ts title="src/pages/api/auth/signin.ts" import type { APIRoute } from "astro"; -import { app } from "../../../lib/firebase/server"; +import { app } from "../../../firebase/server"; import { getAuth } from "firebase-admin/auth"; export const get: APIRoute = async ({ request, cookies, redirect }) => { @@ -196,35 +196,29 @@ export const get: APIRoute = async ({ request, cookies, redirect }) => { const idToken = request.headers.get("Authorization")?.split("Bearer ")[1]; if (!idToken) { return new Response( - JSON.stringify({ - error: "No token found", - }), + "No token found", { status: 401 } ); } - /* Verify the token */ - const decodedToken = await auth.verifyIdToken(idToken).catch(() => null); - - if (!decodedToken) { + /* Verify id token */ + try { + await auth.verifyIdToken(idToken); + } catch (error) { return new Response( - JSON.stringify({ - error: "Invalid token", - }), + "Invalid token", { status: 401 } ); } - const fiveDays = 60 * 60 * 24 * 5 * 1000; - /* Create and set session cookie */ + const fiveDays = 60 * 60 * 24 * 5 * 1000; const sessionCookie = await auth.createSessionCookie(idToken, { expiresIn: fiveDays, }); cookies.set("session", sessionCookie, { path: "/", - // more options }); return redirect("/dashboard"); @@ -270,9 +264,7 @@ export const post: APIRoute = async ({ request, redirect }) => { if (!email || !password || !name) { return new Response( - JSON.stringify({ - error: "Missing data", - }), + "Missing form data", { status: 400 } ); } @@ -286,9 +278,7 @@ export const post: APIRoute = async ({ request, redirect }) => { }); } catch (error: any) { return new Response( - JSON.stringify({ - error: error.code, - }), + "Something went wrong", { status: 400 } ); } @@ -333,18 +323,19 @@ The example `src/pages/register.astro` below includes a form that will send a `P --- import Layout from "../layouts/Layout.astro"; --- + -

Register

+

Register

Already have an account? Sign in

-
+ - + - - -
+ + + ``` @@ -372,44 +363,53 @@ if (sessionCookie) { --- -

Sign in

+

Sign in

New here? Create an account

-
+ - + - - -
+ + + @@ -442,14 +442,14 @@ if (!user) { return Astro.redirect("/signin"); } --- + -

Welcome {user.displayName}

-

We are happy to see you here

+

Welcome {user.displayName}

+

We are happy to see you here

 - ``` ### Adding OAuth providers @@ -460,12 +460,11 @@ In the Firebase console, go to the **Authentication** section and click on the * The example below uses the **Google** provider. - Edit the `signin.astro` page to add: - a button to sign in with Google underneath the existing form - an event listener on the button to handle the sign in process in the existing ` ``` @@ -566,18 +570,14 @@ In this recipe, the Firestore collection will be called **friends** and will con - `age`: a number field - `isBestFriend`: a boolean field - ### Creating the server endpoints Create two new files in a new directory `src/pages/api/friends/`: `index.ts` and `[id].ts`. These will create two server endpoints to interact with the Firestore database in the following ways: - `POST /api/friends`: to create a new document in the friends collection. -- `GET /api/friends/:id`: to get a document in the friends collection. - `POST /api/friends/:id`: to update a document in the friends collection. - `DELETE /api/friends/:id`: to delete a document in the friends collection. - - `index.ts` will contain the code to create a new document in the friends collection: ```ts title="src/pages/api/friends/index.ts" @@ -605,7 +605,9 @@ export const post: APIRoute = async ({ request, redirect }) => { isBestFriend, }); } catch (error) { - console.error(error); + return new Response("Something went wrong", { + status: 500, + }); } return redirect("/dashboard"); }; @@ -650,7 +652,9 @@ export const post: APIRoute = async ({ params, redirect, request }) => { isBestFriend, }); } catch (error) { - console.error(error); + return new Response("Something went wrong", { + status: 500, + }); } return redirect("/dashboard"); }; @@ -665,10 +669,12 @@ export const del: APIRoute = async ({ params, redirect }) => { try { await friendsRef.doc(params.id).delete(); } catch (error) { - console.error(error); + return new Response("Something went wrong", { + status: 500, + }); } return redirect("/dashboard"); -} +}; ``` :::note @@ -733,9 +739,9 @@ If the user clicks the delete button, this page will send a `DELETE` request to ```astro title="src/pages/edit/[id].astro" --- -import Layout from '../../layouts/Layout.astro' -import { app } from '../../firebase/server' -import { getFirestore } from 'firebase-admin/firestore' +import Layout from "../../layouts/Layout.astro"; +import { app } from "../../firebase/server"; +import { getFirestore } from "firebase-admin/firestore"; interface Friend { name: string; @@ -743,22 +749,23 @@ interface Friend { isBestFriend: boolean; } -const { id } = Astro.params +const { id } = Astro.params; if (!id) { - return Astro.redirect('/404') + return Astro.redirect("/404"); } -const db = getFirestore(app) +const db = getFirestore(app); const friendsRef = db.collection("friends"); -const friendSnapshot = await friendsRef.doc(id).get() +const friendSnapshot = await friendsRef.doc(id).get(); if (!friendSnapshot.exists) { - return Astro.redirect('/404') + return Astro.redirect("/404"); } -const friend = friendSnapshot.data() as Friend +const friend = friendSnapshot.data() as Friend; --- +

Edit {friend.name}

Here you can edit or delete your friend's data.

@@ -768,22 +775,29 @@ const friend = friendSnapshot.data() as Friend - + ``` @@ -793,9 +807,9 @@ const friend = friendSnapshot.data() as Friend ```astro title="src/pages/friend/[id].astro" --- -import Layout from '../../layouts/Layout.astro' -import { app } from '../../firebase/server' -import { getFirestore } from 'firebase-admin/firestore' +import Layout from "../../layouts/Layout.astro"; +import { app } from "../../firebase/server"; +import { getFirestore } from "firebase-admin/firestore"; interface Friend { name: string; @@ -803,26 +817,27 @@ interface Friend { isBestFriend: boolean; } -const { id } = Astro.params +const { id } = Astro.params; if (!id) { - return Astro.redirect('/404') + return Astro.redirect("/404"); } -const db = getFirestore(app) +const db = getFirestore(app); const friendsRef = db.collection("friends"); -const friendSnapshot = await friendsRef.doc(id).get() +const friendSnapshot = await friendsRef.doc(id).get(); if (!friendSnapshot.exists) { - return Astro.redirect('/404') + return Astro.redirect("/404"); } -const friend = friendSnapshot.data() as Friend +const friend = friendSnapshot.data() as Friend; --- +

{friend.name}

Age: {friend.age}

-

Is best friend: {friend.isBestFriend ? 'Yes' : 'No'}

+

Is best friend: {friend.isBestFriend ? "Yes" : "No"}

 ``` @@ -843,7 +858,7 @@ interface Friend { isBestFriend: boolean; } -const db = getFirestore(app) +const db = getFirestore(app); const friendsRef = db.collection("friends"); const friendsSnapshot = await friendsRef.get(); const friends = friendsSnapshot.docs.map((doc) => ({ @@ -858,9 +873,7 @@ const friends = friendsSnapshot.docs.map((doc) => ({ { friends.map((friend) => (
  • - - {friend.name} - + {friend.name} ({friend.age}) {friend.isBestFriend ? "Bestie" : "Friend"} Edit @@ -869,6 +882,7 @@ const friends = friendsSnapshot.docs.map((doc) => ({ } + ``` After creating all the pages, you should have the following file structure: diff --git a/src/content/docs/en/guides/cms/decap-cms.mdx b/src/content/docs/en/guides/cms/decap-cms.mdx index 764ce482b9988..bec6d5a5c382e 100644 --- a/src/content/docs/en/guides/cms/decap-cms.mdx +++ b/src/content/docs/en/guides/cms/decap-cms.mdx @@ -20,7 +20,8 @@ i18nReady: false ## Production Sites -The following sites use Astro + Netlify CMS in production: +The following sites use Astro + Decap CMS in production: -- [yunielacosta.com](https://www.yunielacosta.com/) by Yuniel Acosta — [source code on GitHub](https://github.com/yacosta738/yacosta738.github.io) +- [yunielacosta.com](https://www.yunielacosta.com/) by Yuniel Acosta — [source code on GitHub](https://github.com/yacosta738/yacosta738.github.io) (Netlify CMS) +- [portfolioris.nl](https://www.portfolioris.nl/) by Joris Hulsbosch – [source code on GitHub](https://github.com/portfolioris/portfolioris.nl) diff --git a/src/content/docs/en/guides/cms/tina-cms.mdx b/src/content/docs/en/guides/cms/tina-cms.mdx index 291555e211cd9..a607974e48322 100644 --- a/src/content/docs/en/guides/cms/tina-cms.mdx +++ b/src/content/docs/en/guides/cms/tina-cms.mdx @@ -143,3 +143,11 @@ To get started, you'll need an existing Astro project. Learn more about Tina collections [in the Tina docs](https://tina.io/docs/reference/collections/). 5. In production, TinaCMS can commit changes directly to your GitHub repository. To set up TinaCMS for production, you can choose to use [Tina Cloud](https://tina.io/docs/tina-cloud/) or self-host the [Tina Data Layer](https://tina.io/docs/self-hosted/overview/). You can [read more about registering for Tina Cloud](https://app.tina.io/register) in the Tina Docs. + +## Official Resources + +- [TinaCMS Astro integration guide](https://tina.io/docs/frameworks/astro/). + +## Community Resources + +- [Astro Tina Starter](https://github.com/tombennet/astro-tina-starter/tree/main) by Tom Bennet diff --git a/src/content/docs/en/guides/imports.mdx b/src/content/docs/en/guides/imports.mdx index d39a0b0988d0e..357bd67347ca1 100644 --- a/src/content/docs/en/guides/imports.mdx +++ b/src/content/docs/en/guides/imports.mdx @@ -200,6 +200,11 @@ Additionally, glob patterns must begin with one of the following: [Read more about the glob pattern syntax](https://github.com/mrmlnc/fast-glob#pattern-syntax). + +#### `Astro.glob()` vs `getCollection()` + +[Content collections](/en/guides/content-collections/) provide a [`getCollection()` API](/en/reference/api-reference/#getcollection) for loading multiple files instead of `Astro.glob()`. If your content files (e.g. Markdown, MDX, Markdoc) are located in collections within the `src/content/` directory, use `getCollection()` to [query a collection](/en/guides/content-collections/#querying-collections) and return content entries. + ## WASM ```js diff --git a/src/content/docs/en/guides/middleware.mdx b/src/content/docs/en/guides/middleware.mdx index e47df2937ced0..a2f304ad30323 100644 --- a/src/content/docs/en/guides/middleware.mdx +++ b/src/content/docs/en/guides/middleware.mdx @@ -157,7 +157,6 @@ This is an optional argument of `onRequest()`; however, your middleware **must** ### `locals` An object containing data from a response that can be manipulated inside middleware. -9 This `locals` object is forwarded across the request handling process and is available as a property to `APIContext` and `AstroGlobal`. This allows data to be shared between middlewares, API routes, and .astro pages. This is useful for storing request-specific data, such as user data, across the rendering step. `locals` is an object that lives and dies within a single Astro route; when your route page is rendered, `locals` won't exist anymore and a new one will be created. Information that needs to persist across multiple page requests must be stored elsewhere. @@ -168,4 +167,4 @@ In `dev` mode, Astro perform checks and will throw an error if the following con ### `sequence()` -A function that accepts middleware functions as arguments, and will execute them in the order in which they are passed. \ No newline at end of file +A function that accepts middleware functions as arguments, and will execute them in the order in which they are passed. diff --git a/src/content/docs/en/install/manual.mdx b/src/content/docs/en/install/manual.mdx index b6cd2be695c5f..cd66409005f2c 100644 --- a/src/content/docs/en/install/manual.mdx +++ b/src/content/docs/en/install/manual.mdx @@ -59,6 +59,10 @@ Once you are in your new directory, create your project `package.json` file. Thi First, install the Astro project dependencies inside your project. +:::note[Important] +Astro must be installed locally, not globally. Make sure you are *not* running `npm install -g astro` `pnpm add -g astro` or `yarn add global astro`. +::: + ```shell diff --git a/src/content/docs/es/core-concepts/astro-pages.mdx b/src/content/docs/es/core-concepts/astro-pages.mdx index 803d99335c411..53b78baae82f0 100644 --- a/src/content/docs/es/core-concepts/astro-pages.mdx +++ b/src/content/docs/es/core-concepts/astro-pages.mdx @@ -12,7 +12,7 @@ Astro es compatible con los siguientes tipos de archivos en el directorio `src/p - [`.astro`](#páginas-de-astro) - [`.md`](#páginas-markdownmdx) -- `.mdx` (con la [integración de MDX](/es/guides/integrations-guide/mdx/#installation)) instalada +- `.mdx` (con la [integración de MDX](/es/guides/integrations-guide/mdx/#instalación)) instalada - [`.html`](#páginas-html) - [`.js`/`.ts`] (como [endpoints](/es/core-concepts/endpoints/)) @@ -61,7 +61,7 @@ import MySiteLayout from '../layouts/MySiteLayout.astro'; ## Páginas Markdown/MDX -Astro trata archivos Markdown (`.md`) dentro de `src/pages/` como páginas en tu proyecto. Si tienes la [integración de MDX instalada](/es/guides/integrations-guide/mdx/#installation), también procesa los archivos MDX (`.mdx`) de la misma manera. Estos se usan comúnmente para páginas con mucho texto, como artículos de blog y documentación. +Astro trata los archivos Markdown (`.md`) dentro de `src/pages/` como páginas en tu proyecto. Si tienes la [integración de MDX instalada](/es/guides/integrations-guide/mdx/#instalación), también procesa los archivos MDX (`.mdx`) de la misma manera. Estos se usan comúnmente para páginas con mucho texto, como artículos de blog y documentación. [Las colecciones de contenido de páginas Markdown o MDX](/es/guides/content-collections/) en `src/content/` pueden ser usadas para [generar páginas dinámicamente](/es/core-concepts/routing/#rutas-dinámicas). diff --git a/src/content/docs/es/guides/integrations-guide/mdx.mdx b/src/content/docs/es/guides/integrations-guide/mdx.mdx new file mode 100644 index 0000000000000..d9df737beddf7 --- /dev/null +++ b/src/content/docs/es/guides/integrations-guide/mdx.mdx @@ -0,0 +1,207 @@ +--- +type: integration +title: '@astrojs/mdx' +description: Aprende como usar la integración @astrojs/mdx en tu proyecto de Astro. +githubURL: 'https://github.com/withastro/astro/tree/main/packages/integrations/mdx/' +hasREADME: true +category: other +i18nReady: true +--- + +import Video from '~/components/Video.astro'; + +Esta **[integración de Astro][astro-integration]** permite el uso de componentes [MDX](https://mdxjs.com/) y te permite crear páginas como archivos `.mdx`. + +## ¿Por qué MDX? + +MDX te permite [usar variables, expresiones JSX y componentes dentro del contenido Markdown](/es/guides/markdown-content/#características-de-mdx-únicamente) en Astro. Si tienes contenido existente escrito en MDX, esta integración te permite traer esos archivos a tu proyecto de Astro. + +## Instalación + +### Instalación rápida + +La herramienta de línea de comandos `astro add` automatiza la instalación por ti. Ejecuta uno de los siguientes comandos en una nueva ventana de terminal. (Si no estás seguro de qué gestor de paquetes estás usando, ejecuta el primer comando.) Luego, sigue las instrucciones y escribe "y" en la terminal (es decir, "sí") para cada uno. + +```sh +# Usando NPM +npx astro add mdx +# Usando Yarn +yarn astro add mdx +# Usando PNPM +pnpm astro add mdx +``` + +Si tienes algún problema, [no dudes en informarnos en GitHub](https://github.com/withastro/astro/issues) y prueba los pasos de instalación manual a continuación. + +### Instalación Manual + +Primero, instala el paquete `@astrojs/mdx` usando tu gestor de paquetes. Si estás usando npm o no estás seguro, ejecuta lo siguiente en la terminal: + +```sh +npm install @astrojs/mdx +``` + +Luego, aplica esta integración a tu archivo `astro.config.*` usando la propiedad `integrations`: + +**`astro.config.mjs`** + +```js ins={2} "mdx()" +import { defineConfig } from 'astro/config'; +import mdx from '@astrojs/mdx'; + +export default defineConfig({ + // ... + integrations: [mdx()], +}); +``` + +### Integración del Editor + +[VS Code](https://code.visualstudio.com/) admite Markdown de forma predeterminada. Sin embargo, para el soporte del editor MDX, es posible que desees agregar la siguiente configuración en tu archivo de configuración de VSCode. Esto asegura que la autoría de archivos MDX proporcione una experiencia de edición similar a Markdown. + +```json title=".vscode/settings.json" +"files.associations": { + "*.mdx": "markdown" +} +``` + +## Uso + +Con la integración MDX de Astro, puedes [añadir páginas MDX a tu proyecto](/es/guides/markdown-content/#páginas-de-markdown-y-mdx) añadiendo archivos `.mdx` dentro de tu directorio `src/pages/`. También puedes [importar archivos `.mdx`](/es/guides/markdown-content/#importando-markdown) en archivos `.astro`. + +La integración MDX de Astro agrega características adicionales a MDX estándar, incluyendo el frontmatter estilo Markdown. Esto te permite utilizar la mayoría de las características de Markdown incorporadas en Astro, como una [propiedad especial de frontmatter `layout`](/es/guides/markdown-content/#layout-en-el-frontmatter) y una [propiedad para marcar una página como borrador](/es/guides/markdown-content/#páginas-de-borrador). + +Consulta cómo funciona MDX en Astro con ejemplos en nuestra [guía de Markdown y MDX](/es/guides/markdown-content/). + +Visita la [documentación de MDX](https://mdxjs.com/docs/what-is-mdx/) para aprender sobre el uso de las características estándar de MDX. + +## Configuración + +Una vez que la integración MDX esté instalada, no es necesario ninguna configuración adicional para utilizar archivos `.mdx` en tu proyecto Astro. + +Puedes configurar cómo se renderiza tu MDX con las siguientes opciones: + +* [Opciones heredadas de la configuración de Markdown](#opciones-heredadas-de-la-configuración-de-markdown) +* [`extendMarkdownConfig`](#extendmarkdownconfig) +* [`recmaPlugins`](#recmaplugins) + +### Opciones heredadas de la configuración de Markdown + +Todas las [opciones de configuración de `markdown`](/es/reference/configuration-reference/#opciones-de-markdown) excepto `drafts` pueden ser configuradas por separado en la integración MDX. Esto incluye plugins de remark y rehype, resaltado de sintaxis y más. Las opciones se establecerán por defecto con las de tu configuración de Markdown ([consulta la opción `extendMarkdownConfig`](#extendmarkdownconfig) para modificar esto). + +:::note +No hay una configuración de MDX separada para [incluir páginas marcadas como borrador en la compilación](/es/reference/configuration-reference/#markdowndrafts). Esta configuración de Markdown será respetada tanto por archivos de Markdown como de MDX y no se puede anular específicamente para archivos de MDX. +::: + +**`astro.config.mjs`** + +```js +import { defineConfig } from 'astro/config'; +import mdx from '@astrojs/mdx'; +import remarkToc from 'remark-toc'; +import rehypeMinifyHtml from 'rehype-minify-html'; + +export default defineConfig({ + integrations: [ + mdx({ + syntaxHighlight: 'shiki', + shikiConfig: { theme: 'dracula' }, + remarkPlugins: [remarkToc], + rehypePlugins: [rehypeMinifyHtml], + remarkRehype: { footnoteLabel: 'Footnotes' }, + gfm: false, + }) + ] +}) +``` + +:::caution +MDX no admite pasar plugins de remark y rehype como una cadena. En su lugar, debes instalar, importar y aplicar la función del plugin. +::: + +📚 Consulta la [referencia de opciones de Markdown](/es/reference/configuration-reference/#opciones-de-markdown) para ver una lista completa de opciones. + +### `extendMarkdownConfig` + +* **Tipo:** `boolean` +* **Por defecto:** `true` + +Por defecto, MDX extenderá [la configuración de Markdown existente en tu proyecto](/es/reference/configuration-reference/#opciones-de-markdown). Para anular opciones individuales, puedes especificar su equivalente en la configuración de MDX. + +Por ejemplo, digamos que necesitas desactivar el Markdown con formato de GitHub y aplicar un conjunto diferente de plugins de remark para archivos MDX. Puedes aplicar estas opciones de la siguiente manera, con `extendMarkdownConfig` habilitado de forma predeterminada: + +**`astro.config.mjs`** + +```js +import { defineConfig } from 'astro/config'; +import mdx from '@astrojs/mdx'; + +export default defineConfig({ + markdown: { + syntaxHighlight: 'prism', + remarkPlugins: [remarkPlugin1], + gfm: true, + }, + integrations: [ + mdx({ + // `syntaxHighlight` se hereda de Markdown + + // Markdown `remarkPlugins` ignorados, + // Solo se aplicó `remarkPlugin2`. + remarkPlugins: [remarkPlugin2], + // `gfm` se anuló y se estableció en `false` + gfm: false, + }) + ] +}); +``` + +También es posible que necesites deshabilitar la extensión de configuración `markdown` en MDX. Para ello, establece `extendMarkdownConfig` en `false`: + +**`astro.config.mjs`** + +```js +import { defineConfig } from 'astro/config'; +import mdx from '@astrojs/mdx'; + +export default defineConfig({ + markdown: { + remarkPlugins: [remarkPlugin1], + }, + integrations: [ + mdx({ + // La configuración de Markdown ahora se ignora + extendMarkdownConfig: false, + // No se aplicaron `remarkPlugins` + }) + ] +}); +``` + +### `recmaPlugins` + +Estos son plugins que modifican directamente la salida [estree](https://github.com/estree/estree). Esto es útil para modificar o inyectar variables JavaScript en tus archivos MDX. + +Sugerimos [utilizar AST Explorer](https://astexplorer.net/) para experimentar con las salidas de estree y probar [`estree-util-visit`](https://unifiedjs.com/explore/package/estree-util-visit/) para buscar entre nodos de JavaScript. + +## Ejemplos + +* La [plantilla de inicio Astro MDX](https://github.com/withastro/astro/tree/latest/examples/with-mdx) muestra cómo utilizar archivos MDX en tu proyecto Astro. + +## Solución de problemas + +Para obtener ayuda, consulta el canal `#support` en [Discord](https://astro.build/chat). ¡Nuestros amables miembros del Equipo de Soporte están aquí para ayudar! + +También puedes consultar nuestra [documentación de integración de Astro][astro-integration] para obtener más información sobre las integraciones. + +## Contribuyendo + +Este paquete es mantenido por el equipo central de Astro. ¡Estás invitado a enviar un issue o una PR! + +## Changelog + +Consulta el [CHANGELOG.md](https://github.com/withastro/astro/tree/main/packages/integrations/mdx/CHANGELOG.md) para un historial de cambios en esta integración. + +[astro-integration]: /es/guides/integrations-guide/ + +[astro-ui-frameworks]: /es/core-concepts/framework-components/#usando-componente-de-framework \ No newline at end of file diff --git a/src/content/docs/es/guides/migrate-to-astro/from-nuxtjs.mdx b/src/content/docs/es/guides/migrate-to-astro/from-nuxtjs.mdx new file mode 100644 index 0000000000000..6da0eecd8fddb --- /dev/null +++ b/src/content/docs/es/guides/migrate-to-astro/from-nuxtjs.mdx @@ -0,0 +1,701 @@ +--- +title: Migrando desde NuxtJS +description: Consejos para migrar un proyecto existente de NuxtJS a Astro +type: migration +stub: false +framework: NuxtJS +i18nReady: true +--- +import AstroVueTabs from '~/components/tabs/AstroVueTabs.astro' +import PackageManagerTabs from '~/components/tabs/PackageManagerTabs.astro' +import FileTree from '~/components/FileTree.astro' + +Aquí hay algunos conceptos clave y estragias de migración para ayudarte a comenzar. ¡Usa el resto de nuestra documentación y nuestra [comunidad de Discord](https://astro.build/chat) para continuar! + +> Esta guía se refiere a [Nuxt 2](https://nuxtjs.org/), no a la nueva versión Nuxt 3. Si bien algunos de los conceptos son similares, Nuxt 3 es una versión más nueva del framework y puede requerir estrategias diferentes para partes de tu migración. + +## Principales similitudes entre Nuxt y Astro + +Nuxt y Astro comparten algunas similitudes que te ayudarán a migrar tu proyecto: + +- Los proyectos de Astro también pueden ser SSG o [SSR con prerenderizado a nivel de página](/es/guides/server-side-rendering/#renderizado-híbrido). +- Astro usa un enrutamiento basado en archivos y [permite que las páginas con nombres creen rutas dinámicas](/es/core-concepts/routing/#rutas-dinámicas) +- Astro es [basado en componentes](/es/core-concepts/astro-components/) y la estructura de tu marcado será similar antes y después de tu migración. +- Astro tiene [una integración oficial para usar componentes de Vue](/es/guides/integrations-guide/vue/). +- Astro tiene soporte para [instalar paquetes de NPM](/es/guides/imports/#paquetes-npm), incluyendo librerías de Vue. Puedes mantener algunos o todos tus componentes y dependencias de Vue existentes. + +## Principales diferencias entre Nuxt y Astro + +Cuando reconstruyas tu sitio Nuxt en Astro, notarás algunas diferencias importantes: + +- [MPA vs SPA](/es/concepts/mpa-vs-spa/): Nuxt es una SPA basada en Vue (aplicación de una sola página). Los sitios de Astro son aplicaciones multipágina construidas usando componentes `.astro`, pero también pueden admitir React, Preact, Vue.js, Svelte, SolidJS, AlpineJS, Lit y plantillas HTML sin procesar. + +- [Enrutamiento de Página](/es/core-concepts/astro-pages/#enrutamiento-basado-en-archivos): Nuxt usa `vue-router` para el enrutamiento SPA, y `vue-meta` para administrar ``. En Astro, crearás rutas de página HTML separadas y controlarás tu `` directamente o en un componente plantilla. + +- [Enfocado a contenido](/es/concepts/why-astro/): Astro fue diseñado para sobresalir en hacer sitios enfocados en el contenido. Mientras Nuxt puede hacer sitios enfocados en el contenido a través de `@nuxt/content`, una aplicación Nuxt existente puede estar construida para una alta interactividad del lado del cliente. Astro tiene capacidades integradas para trabajar con tu contenido, como la generación de páginas, pero puede ser difícil replicar elementos con un estado compartido complejo, como los paneles, usando componentes `.astro`. + +## Migrar tu proyecto de NuxtJS + +Cada migración de proyecto se verá diferente, pero hay algunas acciones comunes que realizarás al convertir de Nuxt a Astro. + +### Crea un nuevo proyecto Astro +Utiliza el comando `create astro` en tu gestor de paquetes para lanzar el asistente de linea de comandos de Astro o elige un tema de la comunidad del [catálogo de temas de Astro](https://astro.build/themes). + + + + ```shell + # lanzar el Asistente de línea de comandos de Astro + npm create astro@latest + ``` + + + ```shell + # lanzar el Asistente de línea de comandos de Astro + pnpm create astro@latest + ``` + + + ```shell + # lanzar el Asistente de línea de comandos de Astro + yarn create astro@latest + ``` + + + +Puedes pasar un argumento `--template` al comando `create astro` para iniciar un nuevo proyecto Astro con uno de nuestros ejemplos oficiales (por ejemplo, `docs`, `blog`, `portfolio`). O, puedes [iniciar un nuevo proyecto desde cualquier repositorio Astro existente en GitHub](/es/install/auto/#plantillas-de-inicio). + + + + ```shell + # lanzar el Asistente de línea de comandos de Astro + npm create astro@latest + + # crear un nuevo proyecto con un ejemplo oficial + npm create astro@latest -- --template + ``` + + + ```shell + # lanzar el Asistente de línea de comandos de Astro + pnpm create astro@latest + + # crear un nuevo proyecto con un ejemplo oficial + pnpm create astro@latest --template + ``` + + + ```shell + # lanzar el Asistente de línea de comandos de Astro + yarn create astro@latest + + # crear un nuevo proyecto con un ejemplo oficial + yarn create astro@latest --template + ``` + + + +Luego, copia tus archivos de proyecto Nuxt existentes a tu nuevo proyecto Astro en una carpeta separada fuera de `src`. + +:::tip +Visita https://astro.new para ver la lista completa de plantillas de inicio oficiales y enlaces para abrir un nuevo proyecto en StackBlitz, CodeSandbox o Gitpod. +::: + +### Instalar integraciones (opcional) + +Puede resultarte útil instalar algunas de las [integraciones opcionales de Astro](/es/guides/integrations-guide/) para usar mientras estes migrando tu proyecto de Nuxt a Astro: + +- **@astrojs/vue**: para reutilizar algunos componentes de interfaz de usuario Vue existentes en tu nuevo sitio Astro, o seguir escribiendo con componentes Vue. + +- **@astrojs/image**: para reemplazar el plugin de imagen de Nuxt con los propios componentes de optimización de imagen de Astro. + +- **@astrojs/mdx**: para traer archivos MDX existentes de tu proyecto Nuxt, o para usar MDX en tu nuevo sitio Astro. + +### Coloca tu código fuente en `src` + +1. **Mueve** el contenido de la carpeta `static/` de Nuxt a `public/`. + + Astro usa el directorio `public/` para los activos estáticos, similar a la carpeta `static/` de Nuxt. + +2. **Copia o mueve** los otros archivos y carpetas de Nuxt (por ejemplo, `pages`, `layouts`, etc.) a la carpeta `src/` de Astro. + + Como Nuxt, la carpeta `src/pages/` de Astro es una carpeta especial utilizada para el enrutamiento basado en archivos. Todas las demás carpetas son opcionales, y puedes organizar el contenido de tu carpeta `src/` de la forma que desees. Otras carpetas comunes en los proyectos Astro incluyen `src/layouts/`, `src/components`, `src/styles`, `src/scripts`. + +### Convertir páginas Vue SFC a archivos `.astro` + +Aqui hay algunos consejos para convertir un componente `.vue` de Nuxt en un componente `.astro`: + +1. Usa la etiqueta `