Skip to content

Commit ec249f7

Browse files
ElianCodesHiDeooGenteureBryceRussellTheOtterlord
authored
update all the readme's for expressive code (#8691)
 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>
1 parent 0ab19ba commit ec249f7

16 files changed

Lines changed: 249 additions & 224 deletions

File tree

‎packages/integrations/alpinejs/README.md‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -67,7 +67,10 @@ The Alpine.js integration does not give you control over how the script is loade
6767

6868
**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:
6969

70-
```astro title="src/pages/index.astro"
70+
```astro
71+
---
72+
// src/pages/index.astro
73+
---
7174
<!-- Example: Load AlpineJS on a single page. -->
7275
<script>
7376
import Alpine from 'alpinejs';

‎packages/integrations/cloudflare/README.md‎

Lines changed: 49 additions & 47 deletions
Original file line numberDiff line numberDiff line change
@@ -25,15 +25,15 @@ npm install @astrojs/cloudflare
2525

2626
2. Add the following to your `astro.config.mjs` file:
2727

28-
```js ins={3, 6-7}
29-
// astro.config.mjs
30-
import { defineConfig } from 'astro/config';
31-
import cloudflare from '@astrojs/cloudflare';
32-
33-
export default defineConfig({
34-
output: 'server',
35-
adapter: cloudflare(),
36-
});
28+
```diff lang="ts"
29+
// astro.config.mjs
30+
import { defineConfig } from 'astro/config';
31+
+ import cloudflare from '@astrojs/cloudflare';
32+
33+
export default defineConfig({
34+
+ output: 'server',
35+
+ adapter: cloudflare(),
36+
});
3737
```
3838

3939
## Options
@@ -61,16 +61,17 @@ In `directory` mode, the adapter will compile the client-side part of your app t
6161

6262
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.
6363

64-
```diff
65-
import {defineConfig} from "astro/config";
66-
import cloudflare from '@astrojs/cloudflare';
64+
```diff lang="ts"
65+
// astro.config.mjs
66+
import {defineConfig} from "astro/config";
67+
import cloudflare from '@astrojs/cloudflare';
6768

68-
export default defineConfig({
69-
adapter: cloudflare({
70-
mode: 'directory',
71-
+ functionPerRoute: true
69+
export default defineConfig({
70+
adapter: cloudflare({
71+
mode: 'directory',
72+
+ functionPerRoute: true
7273
})
73-
})
74+
})
7475
```
7576

7677
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
147148

148149
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.
149150

150-
```diff
151-
// astro.config.mjs
152-
export default defineConfig({
151+
```diff lang="ts"
152+
// astro.config.mjs
153+
export default defineConfig({
153154
adapter: cloudflare({
154-
mode: 'directory',
155-
+ routes: {
156-
+ strategy: 'include',
157-
+ include: ['/users/*'], // handled by custom function: functions/users/[id].js
158-
+ exclude: ['/users/faq'], // handled by static page: pages/users/faq.astro
159-
+ },
155+
mode: 'directory',
156+
+ routes: {
157+
+ strategy: 'include',
158+
+ include: ['/users/*'], // handled by custom function: functions/users/[id].js
159+
+ exclude: ['/users/faq'], // handled by static page: pages/users/faq.astro
160+
+ },
160161
}),
161-
});
162+
});
162163
```
163164

164165
## Enabling Preview
@@ -287,24 +288,24 @@ Whether or not to import `.wasm` files [directly as ES modules](https://github.c
287288

288289
Add `wasmModuleImports: true` to `astro.config.mjs` to enable in both the Cloudflare build and the Astro dev server.
289290

290-
```diff
291-
// astro.config.mjs
292-
import {defineConfig} from "astro/config";
293-
import cloudflare from '@astrojs/cloudflare';
291+
```diff lang="ts"
292+
// astro.config.mjs
293+
import {defineConfig} from "astro/config";
294+
import cloudflare from '@astrojs/cloudflare';
294295

295-
export default defineConfig({
296+
export default defineConfig({
296297
adapter: cloudflare({
297-
+ wasmModuleImports: true
298+
+ wasmModuleImports: true
298299
}),
299-
output: 'server'
300-
})
300+
output: 'server'
301+
})
301302
```
302303

303304
Once enabled, you can import a web assembly module in Astro with a `.wasm?module` import.
304305

305306
The following is an example of importing a Wasm module that then responds to requests by adding the request's number parameters together.
306307

307-
```javascript
308+
```js
308309
// pages/add/[a]/[b].js
309310
import mod from '../util/add.wasm?module';
310311

@@ -366,19 +367,20 @@ You can also check our [Astro Integration Documentation][astro-integration] for
366367

367368
### Meaningful error messages
368369

369-
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`
370+
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`.
370371

371-
```js
372-
export default defineConfig({
373-
adapter: cloudflare(),
374-
output: 'server',
372+
```diff lang="js"
373+
// astro.config.mjs
374+
export default defineConfig({
375+
adapter: cloudflare(),
376+
output: 'server',
375377

376-
vite: {
377-
build: {
378-
minify: false,
379-
},
380-
},
381-
});
378+
+ vite: {
379+
+ build: {
380+
+ minify: false,
381+
+ },
382+
+ },
383+
});
382384
```
383385

384386
## Contributing

‎packages/integrations/lit/README.md‎

Lines changed: 21 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -42,15 +42,16 @@ npm install lit @webcomponents/template-shadowroot
4242

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

45-
```js ins={3} "lit()"
46-
// astro.config.mjs
47-
import { defineConfig } from 'astro/config';
48-
import lit from '@astrojs/lit';
49-
50-
export default defineConfig({
51-
// ...
52-
integrations: [lit()],
53-
});
45+
```diff lang="js" "lit()"
46+
// astro.config.mjs
47+
import { defineConfig } from 'astro/config';
48+
+ import lit from '@astrojs/lit';
49+
50+
export default defineConfig({
51+
// ...
52+
integrations: [lit()],
53+
// ^^^^^
54+
});
5455
```
5556

5657
## Getting started
@@ -121,15 +122,16 @@ These globals _can_ interfere with other libraries that might use the existence
121122

122123
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:
123124

124-
```diff
125-
import { defineConfig } from 'astro/config';
126-
import vue from '@astrojs/vue';
127-
import lit from '@astrojs/lit';
125+
```diff lang="js"
126+
// astro.config.mjs
127+
import { defineConfig } from 'astro/config';
128+
import vue from '@astrojs/vue';
129+
import lit from '@astrojs/lit';
128130

129-
export default defineConfig({
130-
- integrations: [vue(), lit()]
131-
+ integrations: [lit(), vue()]
132-
});
131+
export default defineConfig({
132+
- integrations: [vue(), lit()]
133+
+ integrations: [lit(), vue()]
134+
});
133135
```
134136

135137
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
138140

139141
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:
140142

141-
```ini title=".npmrc"
143+
```ini
144+
# .npmrc
142145
public-hoist-pattern[]=*lit*
143146
```
144147

‎packages/integrations/markdoc/README.md‎

Lines changed: 18 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -42,15 +42,15 @@ npm install @astrojs/markdoc
4242

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

45-
```js ins={3} "markdoc()"
46-
// astro.config.mjs
47-
import { defineConfig } from 'astro/config';
48-
import markdoc from '@astrojs/markdoc';
49-
50-
export default defineConfig({
51-
// ...
52-
integrations: [markdoc()],
53-
});
45+
```diff lang="js" "markdoc()"
46+
// astro.config.mjs
47+
import { defineConfig } from 'astro/config';
48+
+ import markdoc from '@astrojs/markdoc';
49+
export default defineConfig({
50+
// ...
51+
integrations: [markdoc()],
52+
// ^^^^^^^^^
53+
});
5454
```
5555

5656
### Editor Integration
@@ -443,15 +443,16 @@ By default, Markdoc will not recognize HTML markup as semantic content.
443443
444444
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.
445445
446-
```js {7} "allowHTML: true"
447-
// astro.config.mjs
448-
import { defineConfig } from 'astro/config';
449-
import markdoc from '@astrojs/markdoc';
446+
```diff lang="js" "allowHTML: true"
447+
// astro.config.mjs
448+
import { defineConfig } from 'astro/config';
449+
import markdoc from '@astrojs/markdoc';
450450

451-
export default defineConfig({
452-
// ...
453-
integrations: [markdoc({ allowHTML: true })],
454-
});
451+
export default defineConfig({
452+
// ...
453+
+ integrations: [markdoc({ allowHTML: true })],
454+
// ^^^^^^^^^^^^^^^
455+
});
455456
```
456457
457458
> **Warning**

‎packages/integrations/mdx/README.md‎

Lines changed: 10 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -42,15 +42,16 @@ npm install @astrojs/mdx
4242

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

45-
```js ins={3} "mdx()"
46-
// astro.config.mjs
47-
import { defineConfig } from 'astro/config';
48-
import mdx from '@astrojs/mdx';
49-
50-
export default defineConfig({
51-
// ...
52-
integrations: [mdx()],
53-
});
45+
```diff lang="js" "mdx()"
46+
// astro.config.mjs
47+
import { defineConfig } from 'astro/config';
48+
+ import mdx from '@astrojs/mdx';
49+
50+
export default defineConfig({
51+
// ...
52+
integrations: [mdx()],
53+
// ^^^^^
54+
});
5455
```
5556

5657
### Editor Integration

‎packages/integrations/node/README.md‎

Lines changed: 28 additions & 25 deletions
Original file line numberDiff line numberDiff line change
@@ -43,17 +43,17 @@ If you prefer to install the adapter manually instead, complete the following tw
4343

4444
1. Add two new lines to your `astro.config.mjs` project configuration file.
4545

46-
```js ins={3, 6-9}
47-
// astro.config.mjs
48-
import { defineConfig } from 'astro/config';
49-
import node from '@astrojs/node';
50-
51-
export default defineConfig({
52-
output: 'server',
53-
adapter: node({
54-
mode: 'standalone',
55-
}),
56-
});
46+
```diff lang="js"
47+
// astro.config.mjs
48+
import { defineConfig } from 'astro/config';
49+
+ import node from '@astrojs/node';
50+
51+
export default defineConfig({
52+
+ output: 'server',
53+
+ adapter: node({
54+
+ mode: 'standalone',
55+
+ }),
56+
});
5757
```
5858

5959
## Configuration
@@ -67,6 +67,7 @@ Controls whether the adapter builds to `middleware` or `standalone` mode.
6767
- `middleware` mode allows the built output to be used as middleware for another Node.js server, like Express.js or Fastify.
6868

6969
```js
70+
// astro.config.mjs
7071
import { defineConfig } from 'astro/config';
7172
import node from '@astrojs/node';
7273

@@ -91,6 +92,7 @@ The server entrypoint is built to `./dist/server/entry.mjs` by default. This mod
9192
For example, with Express:
9293

9394
```js
95+
// run-server.mjs
9496
import express from 'express';
9597
import { handler as ssrHandler } from './dist/server/entry.mjs';
9698

@@ -107,6 +109,7 @@ app.listen(8080);
107109
Or, with Fastify (>4):
108110

109111
```js
112+
// run-server.mjs
110113
import Fastify from 'fastify';
111114
import fastifyMiddie from '@fastify/middie';
112115
import fastifyStatic from '@fastify/static';
@@ -128,6 +131,7 @@ app.listen({ port: 8080 });
128131
Additionally, you can also pass in an object to be accessed with `Astro.locals` or in Astro middleware:
129132
130133
```js
134+
// run-server.mjs
131135
import express from 'express';
132136
import { handler as ssrHandler } from './dist/server/entry.mjs';
133137

@@ -192,21 +196,20 @@ export $(cat .env.runtime) && astro build
192196
193197
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:
194198
195-
```js ins={9-13}
196-
// astro.config.mjs
197-
import { defineConfig } from 'astro/config';
198-
199-
import node from '@astrojs/node';
199+
```diff lang="js"
200+
// astro.config.mjs
201+
import { defineConfig } from 'astro/config';
202+
import node from '@astrojs/node';
200203

201-
export default defineConfig({
202-
output: 'server',
203-
adapter: node(),
204-
vite: {
205-
ssr: {
206-
noExternal: ['path-to-regexp'],
207-
},
208-
},
209-
});
204+
export default defineConfig({
205+
output: 'server',
206+
adapter: node(),
207+
+ vite: {
208+
+ ssr: {
209+
+ noExternal: ['path-to-regexp'],
210+
+ },
211+
+ },
212+
});
210213
```
211214
212215
For more help, check out the `#support` channel on [Discord](https://astro.build/chat). Our friendly Support Squad members are here to help!

0 commit comments

Comments
 (0)