Skip to content

Commit

Permalink
Docs: remaining integration READMEs (#2885)
Browse files Browse the repository at this point in the history
* docs: partytown README

* docs: sitemap README

* docs: tailwind README

* docs: turbolinks README

* chore: changeset

* update: make partytown 10% less fun

Co-authored-by: Nate Moore <natemoo-re@users.noreply.github.com>

* docs: add summaries for each integration

Co-authored-by: Nate Moore <natemoo-re@users.noreply.github.com>
  • Loading branch information
bholmesdev and natemoo-re committed Mar 25, 2022
1 parent 145e418 commit 6b00436
Show file tree
Hide file tree
Showing 5 changed files with 299 additions and 0 deletions.
14 changes: 14 additions & 0 deletions .changeset/swift-pets-lick.md
@@ -0,0 +1,14 @@
---
'@astrojs/partytown': patch
'@astrojs/sitemap': patch
'@astrojs/tailwind': patch
'@astrojs/turbolinks': patch
'@astrojs/lit': patch
'@astrojs/preact': patch
'@astrojs/react': patch
'@astrojs/solid-js': patch
'@astrojs/svelte': patch
'@astrojs/vue': patch
---

Add README across Astro built-in integrations
65 changes: 65 additions & 0 deletions packages/integrations/partytown/README.md
@@ -0,0 +1,65 @@
# @astrojs/partytown 🎉

This **[Astro integration][astro-integration]** enables [Partytown](https://partytown.builder.io/) in your Astro project.

Partytown is a lazy-loaded library to help relocate resource intensive scripts into a [web worker](https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API), and off of the [main thread](https://developer.mozilla.org/en-US/docs/Glossary/Main_thread).

## Installation

There are two ways to add integrations to your project. Let's try the most convenient option first!

### (experimental) `astro add` command

Astro includes a CLI tool for adding first party integrations: `astro add`. This command will:
1. (Optionally) Install all necessary dependencies and peer dependencies
2. (Also optionally) Update your `astro.config.*` file to apply this integration

To install `@astrojs/partytown`, run the following from your project directory and follow the prompts:

```sh
# Using NPM
npx astro add partytown
# Using Yarn
yarn astro add partytown
# Using PNPM
pnpx astro add partytown
```

If you run into any hiccups, [feel free to log an issue on our GitHub](https://github.com/withastro/astro/issues) and try the manual installation steps below.

### Install dependencies manually

First, install the `@astrojs/partytown` integration like so:

```
npm install @astrojs/partytown
```

Then, apply this integration to your `astro.config.*` file using the `integrations` property:

__astro.config.mjs__

```js
import partytown from '@astrojs/partytown';

export default {
// ...
integrations: [partytown()],
}
```

## Getting started

Partytown should be ready-to-use with zero config. If you have an existing 3rd party script on your site, try adding the `type="text/partytown"` attribute:

```diff
- <script src="fancy-analytics.js"></script>
+ <script type="text/partytown" src="fancy-analytics.js"></script>
```

If you open the "Network" tab from [your browser's dev tools](https://developer.chrome.com/docs/devtools/open/), you should see the `partytown` proxy intercepting this request.

[Head to the Partytown docs](https://partytown.builder.io/configuration) for configuration options and more usage examples. You can also check our [Astro Integration Documentation][astro-integration] for more on integrations.

[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
74 changes: 74 additions & 0 deletions packages/integrations/sitemap/README.md
@@ -0,0 +1,74 @@
# @astrojs/sitemap 🗺

This **[Astro integration][astro-integration]** generates a sitemap for your Astro project.

Sitemaps outline all of the pages, videos, and files on your site. Search engines like Google read this file to crawl your site more efficiently. [See Google's own advice on sitemaps](https://developers.google.com/search/docs/advanced/sitemaps/overview) to learn more.

## Installation

There are two ways to add integrations to your project. Let's try the most convenient option first!

### (experimental) `astro add` command

Astro includes a CLI tool for adding first party integrations: `astro add`. This command will:
1. (Optionally) Install all necessary dependencies and peer dependencies
2. (Also optionally) Update your `astro.config.*` file to apply this integration

To install `@astrojs/sitemap`, run the following from your project directory and follow the prompts:

```sh
# Using NPM
npx astro add sitemap
# Using Yarn
yarn astro add sitemap
# Using PNPM
pnpx astro add sitemap
```

If you run into any hiccups, [feel free to log an issue on our GitHub](https://github.com/withastro/astro/issues) and try the manual installation steps below.

### Install dependencies manually

First, install the `@astrojs/sitemap` integration like so:

```
npm install @astrojs/sitemap
```

Then, apply this integration to your `astro.config.*` file using the `integrations` property:

__astro.config.mjs__

```js
import sitemap from '@astrojs/sitemap';

export default {
// ...
integrations: [sitemap()],
}
```

## Getting started

`@astrojs/sitemap` requires a deployment / site URL for generation. Add your site's URL under your `astro.config.*` using the `buildOptions.site` property:

__astro.config.mjs__

```js
import sitemap from '@astrojs/sitemap';

export default {
// ...
buildOptions: {
site: 'https://stargazers.club',
},
integrations: [sitemap()],
}
```

Now, [build your site for production](https://docs.astro.build/en/reference/cli-reference/#astro-build) via the `astro build` command. You should find your sitemap under `dist/sitemap.xml`!

You can also check our [Astro Integration Documentation][astro-integration] for more on integrations.

[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
88 changes: 88 additions & 0 deletions packages/integrations/tailwind/README.md
@@ -0,0 +1,88 @@
# @astrojs/tailwind 💨

This **[Astro integration][astro-integration]** brings [Tailwind CSS](https://tailwindcss.com/) to your Astro project.

Tailwind brings utility CSS classes for fonts, colors, layouts, transforms, and more to every Astro page or [UI component](https://docs.astro.build/en/core-concepts/framework-components/) in your project. It also includes extensive theming options for unifying your styles.

## Installation

There are two ways to add integrations to your project. Let's try the most convenient option first!

### (experimental) `astro add` command

Astro includes a CLI tool for adding first party integrations: `astro add`. This command will:
1. (Optionally) Install all necessary dependencies and peer dependencies
2. (Also optionally) Update your `astro.config.*` file to apply this integration

To install `@astrojs/tailwind`, run the following from your project directory and follow the prompts:

```sh
# Using NPM
npx astro add tailwind
# Using Yarn
yarn astro add tailwind
# Using PNPM
pnpx astro add tailwind
```

If you run into any hiccups, [feel free to log an issue on our GitHub](https://github.com/withastro/astro/issues) and try the manual installation steps below.

### Install dependencies manually

First, install the `@astrojs/tailwind` integration like so:

```
npm install @astrojs/tailwind
```

Then, apply this integration to your `astro.config.*` file using the `integrations` property:

__astro.config.mjs__

```js
import tailwind from '@astrojs/tailwind';

export default {
// ...
integrations: [tailwind()],
}
```

## Getting started

Tailwind's utility classes should be ready-to-use with zero config, including [preprocessor setup](https://tailwindcss.com/docs/using-with-preprocessors) and [production optimization](https://tailwindcss.com/docs/optimizing-for-production). Head to the [Tailwind docs](https://tailwindcss.com/docs/utility-first) to learn all of the options and features available!

## Configuration

Have a [custom theme](https://tailwindcss.com/docs/configuration)? Try adding a `tailwind.config.(js|cjs|mjs)` file to the base of your project. You can also specify a custom config file using this integration's `config.path` option:

__astro.config.mjs__

```js
import tailwind from '@astrojs/tailwind';

export default {
// ...
integrations: [tailwind({
config: { path: './custom-config.js' },
})],
}
```

We will provide a `content` property to your config to enable Tailwind across all Astro files and [UI framework components](https://docs.astro.build/en/core-concepts/framework-components/). To remove this default, opt-out via the `config.applyAstroPreset` integration option:

__astro.config.mjs__

```js
export default {
// ...
integrations: [tailwind({
config: { applyAstroPreset: false },
})],
}
```

You can also check our [Astro Integration Documentation][astro-integration] for more on integrations.

[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
58 changes: 58 additions & 0 deletions packages/integrations/turbolinks/README.md
@@ -0,0 +1,58 @@
# @astrojs/turbolinks ⚡️

This **[Astro integration][astro-integration]** brings [Turbo](https://github.com/hotwired/turbo) to your Astro project.

Turbolinks is a plug-and-play solution to bring single page app (SPA) routing to your site. This brings performant navigation without the added complexity of a client-side JavaScript framework.

## Installation

There are two ways to add integrations to your project. Let's try the most convenient option first!

### (experimental) `astro add` command

Astro includes a CLI tool for adding first party integrations: `astro add`. This command will:
1. (Optionally) Install all necessary dependencies and peer dependencies
2. (Also optionally) Update your `astro.config.*` file to apply this integration

To install `@astrojs/turbolinks`, run the following from your project directory and follow the prompts:

```sh
# Using NPM
npx astro add turbolinks
# Using Yarn
yarn astro add turbolinks
# Using PNPM
pnpx astro add turbolinks
```

If you run into any hiccups, [feel free to log an issue on our GitHub](https://github.com/withastro/astro/issues) and try the manual installation steps below.

### Install dependencies manually

First, install the `@astrojs/turbolinks` integration like so:

```
npm install @astrojs/turbolinks
```

Then, apply this integration to your `astro.config.*` file using the `integrations` property:

__astro.config.mjs__

```js
import turbolinks from '@astrojs/turbolinks';

export default {
// ...
integrations: [turbolinks()],
}
```

## Getting started

Turbo links, frames, and more should be ready-to-use with zero config. For instance, try navigating between different pages via links. You should no longer see browser refreshes! You will also find each page request passing through `turbolinks` under the "Network" tab in [your browser's dev tools](https://developer.chrome.com/docs/devtools/).

Head to [the Turbo handbook](https://turbo.hotwired.dev/handbook/introduction) for all options and features available. You can also check our [Astro Integration Documentation][astro-integration] for more on integrations.

[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

0 comments on commit 6b00436

Please sign in to comment.