michael/astro
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity

update all the readme's for expressive code (#8691)

Browse source 
Co-authored-by: HiDeoo <HiDeoo@users.noreply.github.com>
Co-authored-by: Genteure <Genteure@users.noreply.github.com>
Co-authored-by: Bryce Russell <brycetrussell@gmail.com>
Co-authored-by: Reuben Tier <TheOtterlord@users.noreply.github.com>
Co-authored-by: Hippo <hippotastic@users.noreply.github.com>
Co-authored-by: Sarah Rainsberger <sarah@rainsberger.ca>
Co-authored-by: Kevin Zuniga Cuellar <kevinzunigacuellar@users.noreply.github.com>
This commit is contained in:
Elian ☕️ 2023-09-28 15:48:03 +02:00 committed by GitHub
parent 0ab19ba615
commit ec249f7a98
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
16 changed files with 237 additions and 212 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

5
packages/integrations/alpinejs/README.md
View file

@ -67,7 +67,10 @@ The Alpine.js integration does not give you control over how the script is loade
**It is not currently possible to [extend Alpine.js](https://alpinejs.dev/advanced/extending) when using this component.** If you need this feature, consider following [the manual Alpine.js setup](https://alpinejs.dev/essentials/installation) instead using an Astro script tag:
```astro title="src/pages/index.astro"
```astro
---
// src/pages/index.astro
---
<!-- Example: Load AlpineJS on a single page. -->
<script>
import Alpine from 'alpinejs';

94
packages/integrations/cloudflare/README.md
View file

@ -25,15 +25,15 @@ npm install @astrojs/cloudflare
2. Add the following to your `astro.config.mjs` file:
```js ins={3, 6-7}
// astro.config.mjs
import { defineConfig } from 'astro/config';
import cloudflare from '@astrojs/cloudflare';
```diff lang="ts"
// astro.config.mjs
import { defineConfig } from 'astro/config';
+ import cloudflare from '@astrojs/cloudflare';
export default defineConfig({
output: 'server',
adapter: cloudflare(),
});
export default defineConfig({
+ output: 'server',
+ adapter: cloudflare(),
});
```
## Options
@ -61,16 +61,17 @@ In `directory` mode, the adapter will compile the client-side part of your app t
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';
```diff lang="ts"
// astro.config.mjs
import {defineConfig} from "astro/config";
import cloudflare from '@astrojs/cloudflare';
export default defineConfig({
adapter: cloudflare({
mode: 'directory',
+ functionPerRoute: true
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](https://docs.astro.build/en/guides/middleware/) into each page.
@ -147,18 +148,18 @@ If you want to use the automatic `_routes.json` generation, but want to exclude
The following example automatically generates `_routes.json` while including and excluding additional routes. Note that that is only necessary if you have custom functions in the `functions` folder that are not handled by Astro.
```diff
// astro.config.mjs
export default defineConfig({
```diff lang="ts"
// astro.config.mjs
export default defineConfig({
adapter: cloudflare({
mode: 'directory',
+ routes: {
+ strategy: 'include',
+ include: ['/users/*'], // handled by custom function: functions/users/[id].js
+ exclude: ['/users/faq'], // handled by static page: pages/users/faq.astro
+ },
mode: 'directory',
+ routes: {
+ strategy: 'include',
+ include: ['/users/*'], // handled by custom function: functions/users/[id].js
+ exclude: ['/users/faq'], // handled by static page: pages/users/faq.astro
+ },
}),
});
});
```
## Enabling Preview
@ -287,24 +288,24 @@ Whether or not to import `.wasm` files [directly as ES modules](https://github.c
Add `wasmModuleImports: true` to `astro.config.mjs` to enable in both the Cloudflare build and the Astro dev server.
```diff
// astro.config.mjs
import {defineConfig} from "astro/config";
import cloudflare from '@astrojs/cloudflare';
```diff lang="ts"
// astro.config.mjs
import {defineConfig} from "astro/config";
import cloudflare from '@astrojs/cloudflare';
export default defineConfig({
export default defineConfig({
adapter: cloudflare({
+ wasmModuleImports: true
+ wasmModuleImports: true
}),
output: 'server'
})
output: 'server'
})
```
Once enabled, you can import a web assembly module in Astro with a `.wasm?module` import.
The following is an example of importing a Wasm module that then responds to requests by adding the request's number parameters together.
```javascript
```js
// pages/add/[a]/[b].js
import mod from '../util/add.wasm?module';
@ -366,19 +367,20 @@ You can also check our [Astro Integration Documentation][astro-integration] for
### Meaningful error messages
Currently, errors during running your application in Wrangler are not very useful, due to the minification of your code. For better debugging, you can add `vite.build.minify = false` setting to your `astro.config.js`
Currently, errors during running your application in Wrangler are not very useful, due to the minification of your code. For better debugging, you can add `vite.build.minify = false` setting to your `astro.config.mjs`.
```js
export default defineConfig({
adapter: cloudflare(),
output: 'server',
```diff lang="js"
// astro.config.mjs
export default defineConfig({
adapter: cloudflare(),
output: 'server',
vite: {
build: {
minify: false,
},
},
});
+ vite: {
+ build: {
+ minify: false,
+ },
+ },
});
```
## Contributing

37
packages/integrations/lit/README.md
View file

@ -42,15 +42,16 @@ npm install lit @webcomponents/template-shadowroot
Now, apply this integration to your `astro.config.*` file using the `integrations` property:
```js ins={3} "lit()"
// astro.config.mjs
import { defineConfig } from 'astro/config';
import lit from '@astrojs/lit';
```diff lang="js" "lit()"
// astro.config.mjs
import { defineConfig } from 'astro/config';
+ import lit from '@astrojs/lit';
export default defineConfig({
// ...
integrations: [lit()],
});
export default defineConfig({
// ...
integrations: [lit()],
// ^^^^^
});
```
## Getting started
@ -121,15 +122,16 @@ These globals _can_ interfere with other libraries that might use the existence
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
import { defineConfig } from 'astro/config';
import vue from '@astrojs/vue';
import lit from '@astrojs/lit';
```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()]
});
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.
@ -138,7 +140,8 @@ The correct order might be different depending on the underlying cause of the pr
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:
```ini title=".npmrc"
```ini
# .npmrc
public-hoist-pattern[]=*lit*
```

35
packages/integrations/markdoc/README.md
View file

@ -42,15 +42,15 @@ npm install @astrojs/markdoc
Then, apply this integration to your `astro.config.*` file using the `integrations` property:
```js ins={3} "markdoc()"
// astro.config.mjs
import { defineConfig } from 'astro/config';
import markdoc from '@astrojs/markdoc';
export default defineConfig({
// ...
integrations: [markdoc()],
});
```diff lang="js" "markdoc()"
// astro.config.mjs
import { defineConfig } from 'astro/config';
+ import markdoc from '@astrojs/markdoc';
export default defineConfig({
// ...
integrations: [markdoc()],
// ^^^^^^^^^
});
```
### Editor Integration
@ -443,15 +443,16 @@ By default, Markdoc will not recognize HTML markup as semantic content.
To achieve a more Markdown-like experience, where HTML elements can be included alongside your content, set `allowHTML:true` as a `markdoc` integration option. This will enable HTML parsing in Markdoc markup.
```js {7} "allowHTML: true"
// astro.config.mjs
import { defineConfig } from 'astro/config';
import markdoc from '@astrojs/markdoc';
```diff lang="js" "allowHTML: true"
// astro.config.mjs
import { defineConfig } from 'astro/config';
import markdoc from '@astrojs/markdoc';
export default defineConfig({
// ...
integrations: [markdoc({ allowHTML: true })],
});
export default defineConfig({
// ...
+ integrations: [markdoc({ allowHTML: true })],
// ^^^^^^^^^^^^^^^
});
```
> **Warning**

17
packages/integrations/mdx/README.md
View file

@ -42,15 +42,16 @@ npm install @astrojs/mdx
Then, apply this integration to your `astro.config.*` file using the `integrations` property:
```js ins={3} "mdx()"
// astro.config.mjs
import { defineConfig } from 'astro/config';
import mdx from '@astrojs/mdx';
```diff lang="js" "mdx()"
// astro.config.mjs
import { defineConfig } from 'astro/config';
+ import mdx from '@astrojs/mdx';
export default defineConfig({
// ...
integrations: [mdx()],
});
export default defineConfig({
// ...
integrations: [mdx()],
// ^^^^^
});
```
### Editor Integration

53
packages/integrations/node/README.md
View file

@ -43,17 +43,17 @@ If you prefer to install the adapter manually instead, complete the following tw
1. Add two new lines to your `astro.config.mjs` project configuration file.
```js ins={3, 6-9}
// astro.config.mjs
import { defineConfig } from 'astro/config';
import node from '@astrojs/node';
export default defineConfig({
output: 'server',
adapter: node({
mode: 'standalone',
}),
});
```diff lang="js"
// astro.config.mjs
import { defineConfig } from 'astro/config';
+ import node from '@astrojs/node';
export default defineConfig({
+ output: 'server',
+ adapter: node({
+ mode: 'standalone',
+ }),
});
```
## Configuration
@ -67,6 +67,7 @@ Controls whether the adapter builds to `middleware` or `standalone` mode.
- `middleware` mode allows the built output to be used as middleware for another Node.js server, like Express.js or Fastify.
```js
// astro.config.mjs
import { defineConfig } from 'astro/config';
import node from '@astrojs/node';
@ -91,6 +92,7 @@ The server entrypoint is built to `./dist/server/entry.mjs` by default. This mod
For example, with Express:
```js
// run-server.mjs
import express from 'express';
import { handler as ssrHandler } from './dist/server/entry.mjs';
@ -107,6 +109,7 @@ app.listen(8080);
Or, with Fastify (>4):
```js
// run-server.mjs
import Fastify from 'fastify';
import fastifyMiddie from '@fastify/middie';
import fastifyStatic from '@fastify/static';
@ -128,6 +131,7 @@ app.listen({ port: 8080 });
Additionally, you can also pass in an object to be accessed with `Astro.locals` or in Astro middleware:
```js
// run-server.mjs
import express from 'express';
import { handler as ssrHandler } from './dist/server/entry.mjs';
@ -192,21 +196,20 @@ export $(cat .env.runtime) && astro build
You may see this when running the entry script if it was built with npm or Yarn. This is a known issue that may be fixed in a future release. As a workaround, add `"path-to-regexp"` to the `noExternal` array:
```js ins={9-13}
// astro.config.mjs
import { defineConfig } from 'astro/config';
```diff lang="js"
// astro.config.mjs
import { defineConfig } from 'astro/config';
import node from '@astrojs/node';
import node from '@astrojs/node';
export default defineConfig({
output: 'server',
adapter: node(),
vite: {
ssr: {
noExternal: ['path-to-regexp'],
},
},
});
export default defineConfig({
output: 'server',
adapter: node(),
+ vite: {
+ ssr: {
+ noExternal: ['path-to-regexp'],
+ },
+ },
});
```
For more help, check out the `#support` channel on [Discord](https://astro.build/chat). Our friendly Support Squad members are here to help!

21
packages/integrations/partytown/README.md
View file

@ -46,22 +46,23 @@ npm install @astrojs/partytown
Then, apply this integration to your `astro.config.*` file using the `integrations` property:
```js
// astro.config.mjs
import { defineConfig } from 'astro/config';
import partytown from '@astrojs/partytown';
```diff lang="js" "partytown()"
// astro.config.mjs
import { defineConfig } from 'astro/config';
+ import partytown from '@astrojs/partytown';
export default defineConfig({
// ...
integrations: [partytown()],
});
export default defineConfig({
// ...
integrations: [partytown()],
// ^^^^^^^^^^^
});
```
## Usage
Partytown should be ready to go with zero config. If you have an existing 3rd party script on your site, try adding the `type="text/partytown"` attribute:
```diff
```diff lang="html"
- <script src="fancy-analytics.js"></script>
+ <script type="text/partytown" src="fancy-analytics.js"></script>
```
@ -79,7 +80,7 @@ export default defineConfig({
integrations: [
partytown({
config: {
//options go here
// options go here
},
}),
],

10
packages/integrations/preact/README.md
View file

@ -53,14 +53,15 @@ npm install preact
Then, apply this integration to your `astro.config.*` file using the `integrations` property:
```js ins={3} "preact()"
```diff lang="js" "preact()"
// astro.config.mjs
import { defineConfig } from 'astro/config';
import preact from '@astrojs/preact';
+ import preact from '@astrojs/preact';
export default defineConfig({
// ...
integrations: [preact()],
// ^^^^^^^^
});
```
@ -93,6 +94,7 @@ import preact from '@astrojs/preact';
export default defineConfig({
integrations: [preact({ compat: true })],
// ^^^^^^^^^^^^
});
```
@ -100,8 +102,7 @@ With the `compat` option enabled, the Preact integration will render React compo
When importing React component libraries, in order to swap out the `react` and `react-dom` dependencies as `preact/compat`, you can use [`overrides`](https://docs.npmjs.com/cli/v8/configuring-npm/package-json#overrides) to do so.
```json
// package.json
```json title="package.json"
{
"overrides": {
"react": "npm:@preact/compat@latest",
@ -126,6 +127,7 @@ Use the `include` (required) and `exclude` (optional) configuration options to s
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
// astro.config.mjs
import { defineConfig } from 'astro/config';
import preact from '@astrojs/preact';
import react from '@astrojs/react';

17
packages/integrations/prefetch/README.md
View file

@ -41,15 +41,16 @@ npm install @astrojs/prefetch
Then, apply this integration to your `astro.config.*` file using the `integrations` property:
```js ins={3} "prefetch()"
// astro.config.mjs
import { defineConfig } from 'astro/config';
import prefetch from '@astrojs/prefetch';
```diff lang="js" "prefetch()"
// astro.config.mjs
import { defineConfig } from 'astro/config';
+ import prefetch from '@astrojs/prefetch';
export default defineConfig({
// ...
integrations: [prefetch()],
});
export default defineConfig({
// ...
integrations: [prefetch()],
// ^^^^^^^^^^
});
```
## Usage

18
packages/integrations/react/README.md
View file

@ -42,15 +42,16 @@ npm install react react-dom
Now, apply this integration to your `astro.config.*` file using the `integrations` property:
```js ins={3} "react()"
// astro.config.mjs
import { defineConfig } from 'astro/config';
import react from '@astrojs/react';
```diff lang="js" "react()"
// astro.config.mjs
import { defineConfig } from 'astro/config';
+ import react from '@astrojs/react';
export default defineConfig({
// ...
integrations: [react()],
});
export default defineConfig({
// ...
integrations: [react()],
// ^^^^^^^
});
```
## Getting started
@ -72,6 +73,7 @@ Use the `include` (required) and `exclude` (optional) configuration options to s
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
// astro.config.mjs
import { defineConfig } from 'astro/config';
import preact from '@astrojs/preact';
import react from '@astrojs/react';

37
packages/integrations/sitemap/README.md
View file

@ -48,15 +48,16 @@ npm install @astrojs/sitemap
Then, apply this integration to your `astro.config.*` file using the `integrations` property:
```js ins={3} "sitemap()"
// astro.config.mjs
import { defineConfig } from 'astro/config';
import sitemap from '@astrojs/sitemap';
```diff lang="js" "sitemap()"
// astro.config.mjs
import { defineConfig } from 'astro/config';
+ import sitemap from '@astrojs/sitemap';
export default defineConfig({
// ...
integrations: [sitemap()],
});
export default defineConfig({
// ...
integrations: [sitemap()],
// ^^^^^^^^^
});
```
## Usage
@ -84,19 +85,19 @@ Now, [build your site for production](https://docs.astro.build/en/reference/cli-
After verifying that the sitemaps are built, you can add them to your site's `<head>` and the `robots.txt` file for crawlers to pick up.
```html ins={3}
<!-- src/layouts/Layout.astro -->
<head>
<link rel="sitemap" href="/sitemap-index.xml" />
</head>
```diff lang="html"
<!-- src/layouts/Layout.astro -->
<head>
+ <link rel="sitemap" href="/sitemap-index.xml" />
</head>
```
<!-- prettier-ignore -->
```diff ins={4} title="public/robots.txt"
User-agent: *
Allow: /
```diff
# public/robots.txt
User-agent: *
Allow: /
Sitemap: https://<YOUR SITE>/sitemap-index.xml
+ Sitemap: https://<YOUR SITE>/sitemap-index.xml
```
### Example of generated files for a two-page website

18
packages/integrations/solid/README.md
View file

@ -42,15 +42,16 @@ npm install solid-js
Now, apply this integration to your `astro.config.*` file using the `integrations` property:
```js ins={3} "solid()"
// astro.config.mjs
import { defineConfig } from 'astro/config';
import solid from '@astrojs/solid-js';
```diff lang="js" "solid()"
// astro.config.mjs
import { defineConfig } from 'astro/config';
+ import solid from '@astrojs/solid-js';
export default defineConfig({
// ...
integrations: [solid()],
});
export default defineConfig({
// ...
integrations: [solid()],
// ^^^^^^^
});
```
## Getting started
@ -72,6 +73,7 @@ Use the `include` (required) and `exclude` (optional) configuration options to s
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
// astro.config.mjs
import { defineConfig } from 'astro/config';
import preact from '@astrojs/preact';
import react from '@astrojs/react';

17
packages/integrations/svelte/README.md
View file

@ -42,15 +42,16 @@ npm install svelte
Now, apply this integration to your `astro.config.*` file using the `integrations` property:
```js ins={3} "svelte()"
// astro.config.mjs
import { defineConfig } from 'astro/config';
import svelte from '@astrojs/svelte';
```diff lang="js" "svelte()"
// astro.config.mjs
import { defineConfig } from 'astro/config';
+ import svelte from '@astrojs/svelte';
export default defineConfig({
// ...
integrations: [svelte()],
});
export default defineConfig({
// ...
integrations: [svelte()],
// ^^^^^^^^
});
```
## Getting started

37
packages/integrations/tailwind/README.md
View file

@ -50,15 +50,16 @@ npm install @astrojs/tailwind tailwindcss
Then, apply this integration to your `astro.config.*` file using the `integrations` property:
```js ins={3} "tailwind()"
// astro.config.mjs
import { defineConfig } from 'astro/config';
import tailwind from '@astrojs/tailwind';
```diff lang="js" "tailwind()"
// astro.config.mjs
import { defineConfig } from 'astro/config';
+ import tailwind from '@astrojs/tailwind';
export default defineConfig({
// ...
integrations: [tailwind()],
});
export default defineConfig({
// ...
integrations: [tailwind()],
// ^^^^^^^^^^
});
```
Then, create a `tailwind.config.cjs` file in your project's root directory. You can use the following command to generate a basic configuration file for you:
@ -69,16 +70,16 @@ npx tailwindcss init
Finally, add this basic configuration to your `tailwind.config.cjs` file:
```js ins={4} "content: ['./src/**/*.{astro,html,js,jsx,md,mdx,svelte,ts,tsx,vue}']"
// tailwind.config.cjs
/** @type {import('tailwindcss').Config} */
module.exports = {
content: ['./src/**/*.{astro,html,js,jsx,md,mdx,svelte,ts,tsx,vue}'],
theme: {
extend: {},
},
plugins: [],
};
```diff lang="js" "content: ['./src/**/*.{astro,html,js,jsx,md,mdx,svelte,ts,tsx,vue}']"
// tailwind.config.cjs
/** @type {import('tailwindcss').Config} */
module.exports = {
+ content: ['./src/**/*.{astro,html,js,jsx,md,mdx,svelte,ts,tsx,vue}'],
theme: {
extend: {},
},
plugins: [],
};
```
## Usage

16
packages/integrations/vercel/README.md
View file

@ -45,15 +45,15 @@ If you prefer to install the adapter manually instead, complete the following tw
1. Add two new lines to your `astro.config.mjs` project configuration file.
```js ins={3, 6-7}
// astro.config.mjs
import { defineConfig } from 'astro/config';
import vercel from '@astrojs/vercel/serverless';
```diff lang="js"
// astro.config.mjs
import { defineConfig } from 'astro/config';
+ import vercel from '@astrojs/vercel/serverless';
export default defineConfig({
output: 'server',
adapter: vercel(),
});
export default defineConfig({
+ output: 'server',
+ adapter: vercel(),
});
```
### Targets

17
packages/integrations/vue/README.md
View file

@ -42,15 +42,16 @@ npm install vue
Now, apply this integration to your `astro.config.*` file using the `integrations` property:
```js ins={3} "vue()"
// astro.config.mjs
import { defineConfig } from 'astro/config';
import vue from '@astrojs/vue';
```diff lang="js" "vue()"
// astro.config.mjs
import { defineConfig } from 'astro/config';
+ import vue from '@astrojs/vue';
export default defineConfig({
// ...
integrations: [vue()],
});
export default defineConfig({
// ...
integrations: [vue()],
// ^^^^^
});
```
## Getting started