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

Co-authored-by: HiDeoo <[email protected]> Co-authored-by: Genteure <[email protected]> Co-authored-by: Bryce Russell <[email protected]> Co-authored-by: Reuben Tier <[email protected]> Co-authored-by: Hippo <[email protected]> Co-authored-by: Sarah Rainsberger <[email protected]> Co-authored-by: Kevin Zuniga Cuellar <[email protected]>
knpwrs · Sep 28, 2023 · ec249f7 · ec249f7
1 parent 0ab19ba
commit ec249f7
Show file tree

Hide file tree

Showing 16 changed files with 249 additions and 224 deletions.
diff --git a/packages/integrations/alpinejs/README.md b/packages/integrations/alpinejs/README.md
@@ -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';

diff --git a/packages/integrations/cloudflare/README.md b/packages/integrations/cloudflare/README.md
@@ -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';
-
-export default defineConfig({
-  output: 'server',
-  adapter: cloudflare(),
-});
+```diff lang="ts"
+  // astro.config.mjs
+  import { defineConfig } from 'astro/config';
++ import cloudflare from '@astrojs/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

diff --git a/packages/integrations/lit/README.md b/packages/integrations/lit/README.md
@@ -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';
-
-export default defineConfig({
-  // ...
-  integrations: [lit()],
-});
+```diff lang="js" "lit()"
+  // astro.config.mjs
+  import { defineConfig } from 'astro/config';
++ import lit from '@astrojs/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*
 ```
 

diff --git a/packages/integrations/markdoc/README.md b/packages/integrations/markdoc/README.md
@@ -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**

diff --git a/packages/integrations/mdx/README.md b/packages/integrations/mdx/README.md
@@ -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';
-
-export default defineConfig({
-  // ...
-  integrations: [mdx()],
-});
+```diff lang="js" "mdx()"
+  // astro.config.mjs
+  import { defineConfig } from 'astro/config';
++ import mdx from '@astrojs/mdx';
+
+  export default defineConfig({
+    // ...
+    integrations: [mdx()],
+    //             ^^^^^
+  });
 ```
 
 ### Editor Integration

diff --git a/packages/integrations/node/README.md b/packages/integrations/node/README.md
@@ -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';
-
-import node from '@astrojs/node';
+```diff lang="js"
+  // astro.config.mjs
+  import { defineConfig } from 'astro/config';
+  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!