diff --git a/.changeset/soft-sheep-glow.md b/.changeset/soft-sheep-glow.md new file mode 100644 index 000000000000..90b26828a350 --- /dev/null +++ b/.changeset/soft-sheep-glow.md @@ -0,0 +1,18 @@ +--- +'@astrojs/alpinejs': patch +'@astrojs/lit': patch +'@astrojs/markdoc': patch +'@astrojs/mdx': patch +'@astrojs/node': patch +'@astrojs/partytown': patch +'@astrojs/preact': patch +'@astrojs/react': patch +'@astrojs/sitemap': patch +'@astrojs/solid-js': patch +'@astrojs/svelte': patch +'@astrojs/tailwind': patch +'@astrojs/vercel': patch +'@astrojs/vue': patch +--- + +Updates README diff --git a/packages/integrations/alpinejs/README.md b/packages/integrations/alpinejs/README.md index 38732b501ded..78f0a8ba145f 100644 --- a/packages/integrations/alpinejs/README.md +++ b/packages/integrations/alpinejs/README.md @@ -2,109 +2,37 @@ This **[Astro integration][astro-integration]** adds [Alpine.js](https://alpinejs.dev/) to your project so that you can use Alpine.js anywhere on your page. -- [Installation](#installation) -- [Usage](#usage) -- [Configuration](#configuration) -- [Examples](#examples) -- [Troubleshooting](#troubleshooting) -- [Contributing](#contributing) -- [Changelog](#changelog) +## Documentation -## Installation +Read the [`@astrojs/alpinejs` docs][docs] -### Quick Install +## Support -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. +- Get help in the [Astro Discord][discord]. Post questions in our `#support` forum, or visit our dedicated `#dev` channel to discuss current development and more! -```sh -# Using NPM -npx astro add alpinejs -# Using Yarn -yarn astro add alpinejs -# Using PNPM -pnpm astro add alpinejs -``` +- Check our [Astro Integration Documentation][astro-integration] for more on integrations. -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. +- Submit bug reports and feature requests as [GitHub issues][issues]. -### Manual Install - -First, install the `@astrojs/alpinejs` package using your package manager. If you're using npm or aren't sure, run this in the terminal: - -```sh -npm install @astrojs/alpinejs -``` - -Most package managers will install associated peer dependencies as well. However, if you see a "Cannot find package 'alpinejs'" (or similar) warning when you start up Astro, you'll need to manually install Alpine.js yourself: - -```sh -npm install alpinejs @types/alpinejs -``` - -Then, apply this integration to your `astro.config.*` file using the `integrations` property: - -```diff lang="js" "alpine()" - // astro.config.mjs - import { defineConfig } from 'astro/config'; -+ import alpine from '@astrojs/alpinejs'; - - export default defineConfig({ - // ... - integrations: [alpine()], - // ^^^^^^^^ - }); -``` - -## Usage - -Once the integration is installed, you can use [Alpine.js](https://alpinejs.dev/) directives and syntax inside any Astro component. The Alpine.js script is automatically added and enabled on every page of your website. - -Check our [Astro Integration Documentation][astro-integration] for more on integrations. - -## Limitations - -The Alpine.js integration does not give you control over how the script is loaded or initialized. If you require this control, consider [installing and using Alpine.js manually](https://alpinejs.dev/essentials/installation). Astro supports all officially documented Alpine.js manual setup instructions, using ` -``` - -## Configuration - -The Alpine.js integration does not support any custom configuration at this time. - -## Examples - -- The [Astro Alpine.js example](https://github.com/withastro/astro/tree/latest/examples/framework-alpine) shows how to use Alpine.js in an Astro project. - -## Troubleshooting - -For help, check out the `#support` channel on [Discord](https://astro.build/chat). Our friendly Support Squad members are here to help! +## Contributing -You can also check our [Astro Integration Documentation][astro-integration] for more on integrations. +This package is maintained by Astro's Core team. You're welcome to submit an issue or PR! These links will help you get started: -## Contributing +- [Contributor Manual][contributing] +- [Code of Conduct][coc] +- [Community Guide][community] -This package is maintained by Astro's Core team. You're welcome to submit an issue or PR! +## License -## Changelog +MIT -See [CHANGELOG.md](CHANGELOG.md) for a history of changes to this integration. +Copyright (c) 2023–present [Astro][astro] -[astro-integration]: https://docs.astro.build/en/guides/integrations-guide/ -[astro-ui-frameworks]: https://docs.astro.build/en/core-concepts/framework-components/#using-framework-components +[astro]: https://astro.build/ +[docs]: https://docs.astro.build/en/guides/integrations-guide/alpinejs/ +[contributing]: https://github.com/withastro/astro/blob/main/CONTRIBUTING.md +[coc]: https://github.com/withastro/.github/blob/main/CODE_OF_CONDUCT.md +[community]: https://github.com/withastro/.github/blob/main/COMMUNITY_GUIDE.md +[discord]: https://astro.build/chat/ +[issues]: https://github.com/withastro/astro/issues +[astro-integration]: https://docs.astro.build/en/guides/integrations-guide/ \ No newline at end of file diff --git a/packages/integrations/lit/README.md b/packages/integrations/lit/README.md index 70f15e0a39e8..062f684ae235 100644 --- a/packages/integrations/lit/README.md +++ b/packages/integrations/lit/README.md @@ -2,156 +2,37 @@ This **[Astro integration][astro-integration]** enables server-side rendering and client-side hydration for your [Lit](https://lit.dev/) custom elements. -## Installation +## Documentation -There are two ways to add integrations to your project. Let's try the most convenient option first! +Read the [`@astrojs/lit` docs][docs] -### `astro add` command +## Support -Astro includes a CLI tool for adding first party integrations: `astro add`. This command will: +- Get help in the [Astro Discord][discord]. Post questions in our `#support` forum, or visit our dedicated `#dev` channel to discuss current development and more! -1. (Optionally) Install all necessary dependencies and peer dependencies -2. (Also optionally) Update your `astro.config.*` file to apply this integration +- Check our [Astro Integration Documentation][astro-integration] for more on integrations. -To install `@astrojs/lit`, run the following from your project directory and follow the prompts: +- Submit bug reports and feature requests as [GitHub issues][issues]. -```sh -# Using NPM -npx astro add lit -# Using Yarn -yarn astro add lit -# Using PNPM -pnpm astro add lit -``` - -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. - -### Install dependencies manually - -First, install the `@astrojs/lit` integration like so: - -```sh -npm install @astrojs/lit -``` - -Most package managers will install associated peer dependencies as well. Still, if you see a "Cannot find package 'lit'" (or similar) warning when you start up Astro, you'll need to install `lit` and `@webcomponents/template-shadowroot`: - -```sh -npm install lit @webcomponents/template-shadowroot -``` - -Now, apply this integration to your `astro.config.*` file using the `integrations` property: - -```diff lang="js" "lit()" - // astro.config.mjs - import { defineConfig } from 'astro/config'; -+ import lit from '@astrojs/lit'; - - export default defineConfig({ - // ... - integrations: [lit()], - // ^^^^^ - }); -``` - -## Getting started - -To use your first Lit component in Astro, head to our [UI framework documentation][astro-ui-frameworks]. This explains: - -- 📦 how framework components are loaded, -- 💧 client-side hydration options, and -- 🤝 opportunities to mix and nest frameworks together - -Writing and importing a Lit component in Astro looks like this: - -```js -// src/components/my-element.js -import { LitElement, html } from 'lit'; - -export class MyElement extends LitElement { - render() { - return html`

Hello world! From my-element

`; - } -} - -customElements.define('my-element', MyElement); -``` - -Now, the component is ready to be imported via the Astro frontmatter: - -```astro ---- -// src/pages/index.astro -import { MyElement } from '../components/my-element.js'; ---- - - -``` - -> Note that Lit requires browser globals such as `HTMLElement` and `customElements` to be present. For this reason the Lit renderer shims the server with these globals so Lit can run. You _might_ run into libraries that work incorrectly because of this. - -### Polyfills & Hydration - -The renderer automatically handles adding appropriate polyfills for support in browsers that don't have Declarative Shadow DOM. The polyfill is about _1.5kB_. If the browser does support Declarative Shadow DOM then less than 250 bytes are loaded (to feature detect support). - -Hydration is also handled automatically. You can use the same hydration directives such as `client:load`, `client:idle` and `client:visible` as you can with other libraries that Astro supports. - -```astro ---- -import { MyElement } from '../components/my-element.js'; ---- - - -``` - -The above will only load the element's JavaScript when the user has scrolled it into view. Since it is server rendered they will not see any jank; it will load and hydrate transparently. - -## Troubleshooting - -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. - -Common issues are listed below: - -### Browser globals - -The Lit integration's SSR works by adding a few browser global properties to the global environment. Some of the properties it adds includes `window`, `document`, and `location`. - -These globals _can_ interfere with other libraries that might use the existence of these variables to detect that they are running in the browser, when they are actually running in the server. This can cause bugs with these libraries. - -Because of this, the Lit integration might not be compatible with these types of libraries. One thing that can help is changing the order of integrations when Lit is interfering with other integrations: - -```diff lang="js" - // astro.config.mjs - import { defineConfig } from 'astro/config'; - import vue from '@astrojs/vue'; - import lit from '@astrojs/lit'; - - export default defineConfig({ -- integrations: [vue(), lit()] -+ integrations: [lit(), vue()] - }); -``` - -The correct order might be different depending on the underlying cause of the problem. This is not guaranteed to fix every issue however, and some libraries cannot be used if you are using the Lit integration because of this. - -### Strict package managers - -When using a [strict package manager](https://pnpm.io/pnpm-vs-npm#npms-flat-tree) like `pnpm`, you may get an error such as `ReferenceError: module is not defined` when running your site. To fix this, hoist Lit dependencies with an `.npmrc` file: +## Contributing -```ini -# .npmrc -public-hoist-pattern[]=*lit* -``` +This package is maintained by Astro's Core team. You're welcome to submit an issue or PR! These links will help you get started: -### Limitations +- [Contributor Manual][contributing] +- [Code of Conduct][coc] +- [Community Guide][community] -The Lit integration is powered by `@lit-labs/ssr` which has some limitations. See their [limitations documentation](https://www.npmjs.com/package/@lit-labs/ssr#user-content-notes-and-limitations) to learn more. +## License -## Contributing +MIT -This package is maintained by Astro's Core team. You're welcome to submit an issue or PR! +Copyright (c) 2023–present [Astro][astro] -[astro-integration]: https://docs.astro.build/en/guides/integrations-guide/ -[astro-ui-frameworks]: https://docs.astro.build/en/core-concepts/framework-components/#using-framework-components +[astro]: https://astro.build/ +[docs]: https://docs.astro.build/en/guides/integrations-guide/lit/ +[contributing]: https://github.com/withastro/astro/blob/main/CONTRIBUTING.md +[coc]: https://github.com/withastro/.github/blob/main/CODE_OF_CONDUCT.md +[community]: https://github.com/withastro/.github/blob/main/COMMUNITY_GUIDE.md +[discord]: https://astro.build/chat/ +[issues]: https://github.com/withastro/astro/issues +[astro-integration]: https://docs.astro.build/en/guides/integrations-guide/ \ No newline at end of file diff --git a/packages/integrations/markdoc/README.md b/packages/integrations/markdoc/README.md index fd32b8f971c1..fb961625c087 100644 --- a/packages/integrations/markdoc/README.md +++ b/packages/integrations/markdoc/README.md @@ -2,517 +2,37 @@ This **[Astro integration][astro-integration]** enables the usage of [Markdoc](https://markdoc.dev/) to create components, pages, and content collection entries. -- [Why Markdoc?](#why-markdoc) -- [Installation](#installation) -- [Usage](#usage) -- [Configuration](#configuration) -- [Examples](#examples) -- [Troubleshooting](#troubleshooting) -- [Contributing](#contributing) -- [Changelog](#changelog) +## Documentation -## Why Markdoc? +Read the [`@astrojs/markdoc` docs][docs] -Markdoc allows you to enhance your Markdown with [Astro components][astro-components]. If you have existing content authored in Markdoc, this integration allows you to bring those files to your Astro project using content collections. +## Support -## Installation +- Get help in the [Astro Discord][discord]. Post questions in our `#support` forum, or visit our dedicated `#dev` channel to discuss current development and more! -### Quick Install +- Check our [Astro Integration Documentation][astro-integration] for more on integrations. -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. +- Submit bug reports and feature requests as [GitHub issues][issues]. -```sh -# Using NPM -npx astro add markdoc -# Using Yarn -yarn astro add markdoc -# Using PNPM -pnpm astro add markdoc -``` - -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/markdoc` package using your package manager. If you're using npm or aren't sure, run this in the terminal: - -```sh -npm install @astrojs/markdoc -``` - -Then, apply this integration to your `astro.config.*` file using the `integrations` property: - -```diff lang="js" "markdoc()" - // astro.config.mjs - import { defineConfig } from 'astro/config'; -+ import markdoc from '@astrojs/markdoc'; - export default defineConfig({ - // ... - integrations: [markdoc()], - // ^^^^^^^^^ - }); -``` - -### Editor Integration - -[VS Code](https://code.visualstudio.com/) supports Markdown by default. However, for Markdoc editor support, you may wish to add the following setting in your VSCode config. This ensures authoring Markdoc files provides a Markdown-like editor experience. - -```json title=".vscode/settings.json" -{ - "files.associations": { - "*.mdoc": "markdown" - } -} -``` - -## Usage - -Markdoc files can only be used within content collections. Add entries to any content collection using the `.mdoc` extension: - -```sh -src/content/docs/ - why-markdoc.mdoc - quick-start.mdoc -``` - -Then, query your collection using the [Content Collection APIs](https://docs.astro.build/en/guides/content-collections/#querying-collections): - -```astro ---- -import { getEntryBySlug } from 'astro:content'; - -const entry = await getEntryBySlug('docs', 'why-markdoc'); -const { Content } = await entry.render(); ---- - - -

{entry.data.title}

- - -``` - -📚 See the [Astro Content Collection docs][astro-content-collections] for more information. - -## Markdoc config - -`@astrojs/markdoc` offers configuration options to use all of Markdoc's features and connect UI components to your content. - -### Use Astro components as Markdoc tags - -You can configure [Markdoc tags][markdoc-tags] that map to `.astro` components. You can add a new tag by creating a `markdoc.config.mjs|ts` file at the root of your project and configuring the `tag` attribute. - -This example renders an `Aside` component, and allows a `type` prop to be passed as a string: - -```js -// markdoc.config.mjs -import { defineMarkdocConfig, component } from '@astrojs/markdoc/config'; - -export default defineMarkdocConfig({ - tags: { - aside: { - render: component('./src/components/Aside.astro'), - attributes: { - // Markdoc requires type defs for each attribute. - // These should mirror the `Props` type of the component - // you are rendering. - // See Markdoc's documentation on defining attributes - // https://markdoc.dev/docs/attributes#defining-attributes - type: { type: String }, - }, - }, - }, -}); -``` - -This component can now be used in your Markdoc files with the `{% aside %}` tag. Children will be passed to your component's default slot: - -```md -# Welcome to Markdoc 👋 - -{% aside type="tip" %} - -Use tags like this fancy "aside" to add some _flair_ to your docs. - -{% /aside %} -``` - -### Use Astro components from npm packages and TypeScript files - -You may need to use Astro components exposed as named exports from TypeScript or JavaScript files. This is common when using npm packages and design systems. - -You can pass the import name as the second argument to the `component()` function: - -```js -// markdoc.config.mjs -import { defineMarkdocConfig, component } from '@astrojs/markdoc/config'; - -export default defineMarkdocConfig({ - tags: { - tabs: { - render: component('@astrojs/starlight/components', 'Tabs'), - }, - }, -}); -``` - -This generates the following import statement internally: - -```ts -import { Tabs } from '@astrojs/starlight/components'; -``` - -### Custom headings - -`@astrojs/markdoc` automatically adds anchor links to your headings, and [generates a list of `headings` via the content collections API](https://docs.astro.build/en/guides/content-collections/#rendering-content-to-html). To further customize how headings are rendered, you can apply an Astro component [as a Markdoc node][markdoc-nodes]. - -This example renders a `Heading.astro` component using the `render` property: - -```js -// markdoc.config.mjs -import { defineMarkdocConfig, nodes, component } from '@astrojs/markdoc/config'; - -export default defineMarkdocConfig({ - nodes: { - heading: { - ...nodes.heading, // Preserve default anchor link generation - render: component('./src/components/Heading.astro'), - }, - }, -}); -``` - -All Markdown headings will render the `Heading.astro` component and pass the following `attributes` as component props: - -- `level: number` The heading level 1 - 6 -- `id: string` An `id` generated from the heading's text contents. This corresponds to the `slug` generated by the [content `render()` function](https://docs.astro.build/en/guides/content-collections/#rendering-content-to-html). - -For example, the heading `### Level 3 heading!` will pass `level: 3` and `id: 'level-3-heading'` as component props. - -### Syntax highlighting - -`@astrojs/markdoc` provides [Shiki](https://github.com/shikijs/shiki) and [Prism](https://github.com/PrismJS) extensions to highlight your code blocks. - -#### Shiki - -Apply the `shiki()` extension to your Markdoc config using the `extends` property. You can optionally pass a shiki configuration object: - -```js -// markdoc.config.mjs -import { defineMarkdocConfig } from '@astrojs/markdoc/config'; -import shiki from '@astrojs/markdoc/shiki'; - -export default defineMarkdocConfig({ - extends: [ - shiki({ - // Choose from Shiki's built-in themes (or add your own) - // Default: 'github-dark' - // https://github.com/shikijs/shiki/blob/main/docs/themes.md - theme: 'dracula', - // Enable word wrap to prevent horizontal scrolling - // Default: false - wrap: true, - // Pass custom languages - // Note: Shiki has countless langs built-in, including `.astro`! - // https://github.com/shikijs/shiki/blob/main/docs/languages.md - langs: [], - }), - ], -}); -``` - -#### Prism - -Apply the `prism()` extension to your Markdoc config using the `extends` property. - -```js -// markdoc.config.mjs -import { defineMarkdocConfig } from '@astrojs/markdoc/config'; -import prism from '@astrojs/markdoc/prism'; - -export default defineMarkdocConfig({ - extends: [prism()], -}); -``` - -📚 To learn about configuring Prism stylesheets, [see our syntax highlighting guide](https://docs.astro.build/en/guides/markdown-content/#prism-configuration). - -### Set the root HTML element - -Markdoc wraps documents with an `
` tag by default. This can be changed from the `document` Markdoc node. This accepts an HTML element name or `null` if you prefer to remove the wrapper element: - -```js -// markdoc.config.mjs -import { defineMarkdocConfig, nodes } from '@astrojs/markdoc/config'; - -export default defineMarkdocConfig({ - nodes: { - document: { - ...nodes.document, // Apply defaults for other options - render: null, // default 'article' - }, - }, -}); -``` - -### Custom Markdoc nodes / elements - -You may want to render standard Markdown elements, such as paragraphs and bolded text, as Astro components. For this, you can configure a [Markdoc node][markdoc-nodes]. If a given node receives attributes, they will be available as component props. - -This example renders blockquotes with a custom `Quote.astro` component: - -```js -// markdoc.config.mjs -import { defineMarkdocConfig, nodes, component } from '@astrojs/markdoc/config'; - -export default defineMarkdocConfig({ - nodes: { - blockquote: { - ...nodes.blockquote, // Apply Markdoc's defaults for other options - render: component('./src/components/Quote.astro'), - }, - }, -}); -``` - -📚 [Find all of Markdoc's built-in nodes and node attributes on their documentation.](https://markdoc.dev/docs/nodes#built-in-nodes) - -### Use client-side UI components - -Tags and nodes are restricted to `.astro` files. To embed client-side UI components in Markdoc, [use a wrapper `.astro` component that renders a framework component](https://docs.astro.build/en/core-concepts/framework-components/#nesting-framework-components) with your desired `client:` directive. - -This example wraps a React `Aside.tsx` component with a `ClientAside.astro` component: - -```astro ---- -// src/components/ClientAside.astro -import Aside from './Aside'; ---- - -