Document suppress in supportedAstroFeatures

src/content/docs/en/reference/adapter-reference.mdx

@@ -26,12 +26,12 @@ An adapter __must__ call the `setAdapter` API in the `astro:config:done` hook li
 ```js title="my-adapter.mjs"
 export default function createIntegration() {
   return {
-    name: '@matthewp/my-adapter',
+    name: '@example/my-adapter',
     hooks: {
       'astro:config:done': ({ setAdapter }) => {
         setAdapter({
-          name: '@matthewp/my-adapter',
-          serverEntrypoint: '@matthewp/my-adapter/server.js',
+          name: '@example/my-adapter',
+          serverEntrypoint: '@example/my-adapter/server.js',
           supportedAstroFeatures: {
               staticOutput: 'stable'
           }
@@ -71,6 +71,7 @@ export type AdapterSupportsKind = 'unsupported' | 'stable' | 'experimental' | 'd
 export type AdapterSupportWithMessage = {
 	support: Exclude<AdapterSupportsKind, 'stable'>;
 	message: string;
+	suppress?: 'default' | 'all';
 };
 
 export type AdapterSupport = AdapterSupportsKind | AdapterSupportWithMessage;
@@ -147,12 +148,12 @@ And then in your integration, where you call `setAdapter`, provide this name in
 ```js title="my-adapter.mjs" ins={9}
 export default function createIntegration() {
   return {
-    name: '@matthewp/my-adapter',
+    name: '@example/my-adapter',
     hooks: {
       'astro:config:done': ({ setAdapter }) => {
         setAdapter({
-          name: '@matthewp/my-adapter',
-          serverEntrypoint: '@matthewp/my-adapter/server.js',
+          name: '@example/my-adapter',
+          serverEntrypoint: '@example/my-adapter/server.js',
           exports: ['handler'],
         });
       },
@@ -371,21 +372,21 @@ Astro features are a way for an adapter to tell Astro whether they are able to s
 
 When using these properties, Astro will:
 - run specific validation; 
-- emit contextual to the logs;
+- emit contextual information to the logs;
 
-These operations are run based on the features supported or not supported, their level of support, and the configuration that the user uses.
+These operations are run based on the features supported or not supported, their level of support, the [desired amount of logging](#suppress), and the user's own configuration.
 
 The following configuration tells Astro that this adapter has experimental support for the Sharp-powered built-in image service:
 
 ```js title="my-adapter.mjs" ins={9-11}
 export default function createIntegration() {
   return {
-    name: '@matthewp/my-adapter',
+    name: '@example/my-adapter',
     hooks: {
       'astro:config:done': ({ setAdapter }) => {
         setAdapter({
-          name: '@matthewp/my-adapter',
-          serverEntrypoint: '@matthewp/my-adapter/server.js',
+          name: '@example/my-adapter',
+          serverEntrypoint: '@example/my-adapter/server.js',
           supportedAstroFeatures: {
             sharpImageService: 'experimental'
           } 
@@ -399,26 +400,86 @@ export default function createIntegration() {
 If the Sharp image service is used, Astro will log a warning and error to the terminal based on your adapter's support:
 
 ```
-[@matthewp/my-adapter] The feature is experimental and subject to issues or changes.
+[@example/my-adapter] The feature is experimental and subject to issues or changes.
 
-[@matthewp/my-adapter] The currently selected adapter `@matthewp/my-adapter` is not compatible with the service "Sharp". Your project will NOT be able to build.
+[@example/my-adapter] The currently selected adapter `@example/my-adapter` is not compatible with the service "Sharp". Your project will NOT be able to build.
 ```
 
 A message can additionally be provided to give more context to the user:
 
 ```js title="my-adapter.mjs" ins={9-14}
 export default function createIntegration() {
   return {
-    name: '@matthewp/my-adapter',
+    name: '@example/my-adapter',
     hooks: {
       'astro:config:done': ({ setAdapter }) => {
         setAdapter({
-          name: '@matthewp/my-adapter',
-          serverEntrypoint: '@matthewp/my-adapter/server.js',
+          name: '@example/my-adapter',
+          serverEntrypoint: '@example/my-adapter/server.js',
           supportedAstroFeatures: {
             sharpImageService: {
               support: 'limited',
-              message: 'This adapter has limited support for Sharp, certain features may not work as expected.'
+              message: 'This adapter has limited support for Sharp. Certain features may not work as expected.'
+            }
+          } 
+        });
+      },
+    },
+  };
+}
+```
+
+### `suppress`
+
+<p>
+
+  **Type:** `default | all`<br />
+  <Since v="5.9.0" />
+</p>
+
+An option to prevent showing some or all logged messages.
+
+If Astro's default log message is redundant, or confusing to the user in combination with your custom `message`, you can use `suppress: "default"` to suppress the default message and only log your message:
+
+```js title="my-adapter.mjs" ins={13}
+export default function createIntegration() {
+  return {
+    name: '@example/my-adapter',
+    hooks: {
+      'astro:config:done': ({ setAdapter }) => {
+        setAdapter({
+          name: '@example/my-adapter',
+          serverEntrypoint: '@example/my-adapter/server.js',
+          supportedAstroFeatures: {
+            sharpImageService: {
+              support: 'limited',
+              message: 'The adapter has limited support for Sharp. It will be used for images during build time, but will not work at runtime.',
+              suppress: 'default' // custom message is more detailed than the default
+            }
+          } 
+        });
+      },
+    },
+  };
+}
+```
+
+You can also use `suppress: "all"` to suppress all messages for a specific feature. This is useful when these messages are unhelpful to users in a specific context. For example, you can choose to prevent logging any messages about Sharp:
+
+```js title="my-adapter.mjs" ins={13}
+export default function createIntegration() {
+  return {
+    name: '@example/my-adapter',
+    hooks: {
+      'astro:config:done': ({ setAdapter }) => {
+        setAdapter({
+          name: '@example/my-adapter',
+          serverEntrypoint: '@example/my-adapter/server.js',
+          supportedAstroFeatures: {
+            sharpImageService: {
+              support: 'limited',
+              message: 'This adapter has limited support for Sharp. Certain features may not work as expected.',
+              suppress: 'all'
             }
           } 
         });
@@ -446,12 +507,12 @@ When enabled, this prevents middleware code from being bundled and imported by a
 ```js title="my-adapter.mjs" ins={9-11}
 export default function createIntegration() {
   return {
-    name: '@matthewp/my-adapter',
+    name: '@example/my-adapter',
     hooks: {
       'astro:config:done': ({ setAdapter }) => {
         setAdapter({
-          name: '@matthewp/my-adapter',
-          serverEntrypoint: '@matthewp/my-adapter/server.js',
+          name: '@example/my-adapter',
+          serverEntrypoint: '@example/my-adapter/server.js',
           adapterFeatures: {
               edgeMiddleware: true
           } 
@@ -467,12 +528,12 @@ Then, consume the hook [`astro:build:ssr`](/en/reference/integrations-reference/
 ```js title="my-adapter.mjs" ins={15-20}
 export default function createIntegration() {
   return {
-    name: '@matthewp/my-adapter',
+    name: '@example/my-adapter',
     hooks: {
       'astro:config:done': ({ setAdapter }) => {
         setAdapter({
-          name: '@matthewp/my-adapter',
-          serverEntrypoint: '@matthewp/my-adapter/server.js',
+          name: '@example/my-adapter',
+          serverEntrypoint: '@example/my-adapter/server.js',
           adapterFeatures: {
               edgeMiddleware: true
           } 
@@ -508,12 +569,12 @@ Enable the feature by passing any valid `AdapterSupportsKind` value to the adapt
 ```js title="my-adapter.mjs" ins={9-11}
 export default function createIntegration() {
   return {
-    name: '@matthewp/my-adapter',
+    name: '@example/my-adapter',
     hooks: {
       'astro:config:done': ({ setAdapter }) => {
         setAdapter({
-          name: '@matthewp/my-adapter',
-          serverEntrypoint: '@matthewp/my-adapter/server.js',
+          name: '@example/my-adapter',
+          serverEntrypoint: '@example/my-adapter/server.js',
           adapterFeatures: {
               envGetSecret: 'stable'
           } 
@@ -583,12 +644,12 @@ This property allows you to force a specific output shape for the build. This ca
 ```js title="my-adapter.mjs" ins={9-11}
 export default function createIntegration() {
   return {
-    name: '@matthewp/my-adapter',
+    name: '@example/my-adapter',
     hooks: {
       'astro:config:done': ({ setAdapter }) => {
         setAdapter({
-          name: '@matthewp/my-adapter',
-          serverEntrypoint: '@matthewp/my-adapter/server.js',
+          name: '@example/my-adapter',
+          serverEntrypoint: '@example/my-adapter/server.js',
           adapterFeatures: {
             buildOutput: 'static'
           }