fix(demo): use bracketed admonition title syntax for Docusaurus 3.10

sserrata · sserrata · commit 90b0919c10f1 · 2026-05-01T15:27:32.000-04:00
Docusaurus 3.10's strict admonition parser silently drops the box when the title uses the legacy space-separated form (`:::info TIP`). Switch to the bracketed form (`:::info[TIP]`) in versioning.mdx, sidebars.mdx, and the cos OpenAPI spec. Generated .api.mdx files already pick up the matching plugin-side fix from PR #1423 on regeneration.
diff --git a/demo/docs/sidebars.mdx b/demo/docs/sidebars.mdx
@@ -21,15 +21,15 @@ Guidelines:
 
 ## Built-in Docusaurus Sidebars
 
-:::info TIP
+:::info[TIP]
 Visit docusaurus.io for the [official documentation](https://docusaurus.io/docs/sidebar) on sidebars.
 :::
 
 Docusaurus comes equipped with some helpful utilities, patterns and methods for managing sidebars. The following is a high-level summary of options that may be of use for constructing them for your OpenAPI docs.
 
 ### Autogenerated
 
-:::info TIP
+:::info[TIP]
 Visit https://docusaurus.io/docs/sidebar/autogenerated for the official documentation on `autogenerated` sidebars.
 :::
 
diff --git a/demo/docs/versioning.mdx b/demo/docs/versioning.mdx
@@ -18,7 +18,7 @@ Finally, the OpenAPI Docs versioning implementation allows API docs to be versio
 
 The OpenAPI Docs plugin versioning system is driven by the CLI and is not unlike the experience of generating and cleaning non-versioned API docs.
 
-:::info TIP
+:::info[TIP]
 For details around how to configure versioning see the [Plugin Configuration Options](./intro.mdx#plugin-configuration-options) and [Versioning](./intro.mdx#versioning-openapi-docs) guides.
 :::
 
@@ -52,7 +52,7 @@ The `versions.json` file contains metadata that could be useful for building UI
   - **Step 3**: Remove the version from the OpenAPI plugin config.
   - **Step 4**: Run the `gen-api-docs:version` command to update the `versions.json` file.
 
-:::info TIP
+:::info[TIP]
 The OpenAPI Docs plugin will **not** delete a versioned `outputDir` after executing the `clean-api-docs:version` command. This is by design, as the plugin tries to avoid removing non-API docs/files.
 :::
 
diff --git a/demo/examples/openapi-cos.json b/demo/examples/openapi-cos.json
@@ -79,7 +79,7 @@
       "put": {
         "tags": ["Bucket operations"],
         "summary": "Create a bucket",
-        "description": "A `PUT` request sent to the endpoint root followed by a string will create a bucket.\nFor more information about endpoints, see [Endpoints and storage locations](https://cloud.ibm.com/docs/cloud-object-storage?topic=cloud-object-storage-endpoints#endpoints).\nBucket names must be globally unique and DNS-compliant; names between 3 and 63 characters long must be made of lowercase letters, numbers, and dashes.\nBucket names must begin and end with a lowercase letter or number.\nBucket names resembling IP addresses are not allowed.\nThis operation doesn't make use of operation specific query parameters.\n\n:::info important\nBucket names must be unique because all buckets in the public cloud share a global namespace.\nThis allows for access to a bucket without needing to provide any service instance or account information.\nIt is also not possible to create a bucket with a name beginning with `cosv1-` or `account-` as these prefixes are reserved by the system.\n:::\n\n:::note\nPersonally Identifiable Information (PII): When creating buckets or adding objects, please ensure to not use any information that can identify any user (natural person) by name, location or any other means in the name of the bucket or object.\n:::\n\n## Create a bucket with a different storage class\n\nTo create a bucket with a different storage class, send an XML block specifying a bucket configuration with a `LocationConstraint` of `{provisioning code}` in the body of a `PUT` request to a bucket endpoint.\nFor more information about endpoints, see [Endpoints and storage locations](https://cloud.ibm.com/docs/cloud-object-storage?topic=cloud-object-storage-endpoints#endpoints).\nNote that standard bucket [naming rules](https://cloud.ibm.com/docs/cloud-object-storage?topic=cloud-object-storage-compatibility-api-bucket-operations#compatibility-api-new-bucket) apply.\nThis operation does not make use of operation specific query parameters.\n\nThe body of the request must contain an XML block with the following schema:\n\n```xml\n<CreateBucketConfiguration>\n  <LocationConstraint>us-vault</LocationConstraint>\n</CreateBucketConfiguration>\n```\n\nA list of valid provisioning codes for `LocationConstraint` can be referenced in [the Storage Classes guide](https://cloud.ibm.com/docs/cloud-object-storage?topic=cloud-object-storage-classes#classes-locationconstraint).\n\n## Create a new bucket with Key Protect or Hyper Protect Crypto Services managed encryption keys (SSE-KP)\n\nTo create a bucket where the encryption keys are managed by Key Protect or Hyper Protect Crypto Services, it is necessary to have access to an active Key Protect or Hyper Protect Crypto Services service instance located in the same location as the new bucket.\nThis operation does not make use of operation specific query parameters.\n\nFor more information on using Key Protect to manage your encryption keys, [see the documentation for Key Protect](https://cloud.ibm.com/docs/key-protect?topic=key-protect-getting-started-tutorial).\n\nFor more information on Hyper Protect Crypto Services, [see the documentation](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-get-started).\n\n:::note\nNote that managed encryption is **not** available in a Cross Region configuration and any SSE-KP buckets must be Regional.\n:::",
+        "description": "A `PUT` request sent to the endpoint root followed by a string will create a bucket.\nFor more information about endpoints, see [Endpoints and storage locations](https://cloud.ibm.com/docs/cloud-object-storage?topic=cloud-object-storage-endpoints#endpoints).\nBucket names must be globally unique and DNS-compliant; names between 3 and 63 characters long must be made of lowercase letters, numbers, and dashes.\nBucket names must begin and end with a lowercase letter or number.\nBucket names resembling IP addresses are not allowed.\nThis operation doesn't make use of operation specific query parameters.\n\n:::info[important]\nBucket names must be unique because all buckets in the public cloud share a global namespace.\nThis allows for access to a bucket without needing to provide any service instance or account information.\nIt is also not possible to create a bucket with a name beginning with `cosv1-` or `account-` as these prefixes are reserved by the system.\n:::\n\n:::note\nPersonally Identifiable Information (PII): When creating buckets or adding objects, please ensure to not use any information that can identify any user (natural person) by name, location or any other means in the name of the bucket or object.\n:::\n\n## Create a bucket with a different storage class\n\nTo create a bucket with a different storage class, send an XML block specifying a bucket configuration with a `LocationConstraint` of `{provisioning code}` in the body of a `PUT` request to a bucket endpoint.\nFor more information about endpoints, see [Endpoints and storage locations](https://cloud.ibm.com/docs/cloud-object-storage?topic=cloud-object-storage-endpoints#endpoints).\nNote that standard bucket [naming rules](https://cloud.ibm.com/docs/cloud-object-storage?topic=cloud-object-storage-compatibility-api-bucket-operations#compatibility-api-new-bucket) apply.\nThis operation does not make use of operation specific query parameters.\n\nThe body of the request must contain an XML block with the following schema:\n\n```xml\n<CreateBucketConfiguration>\n  <LocationConstraint>us-vault</LocationConstraint>\n</CreateBucketConfiguration>\n```\n\nA list of valid provisioning codes for `LocationConstraint` can be referenced in [the Storage Classes guide](https://cloud.ibm.com/docs/cloud-object-storage?topic=cloud-object-storage-classes#classes-locationconstraint).\n\n## Create a new bucket with Key Protect or Hyper Protect Crypto Services managed encryption keys (SSE-KP)\n\nTo create a bucket where the encryption keys are managed by Key Protect or Hyper Protect Crypto Services, it is necessary to have access to an active Key Protect or Hyper Protect Crypto Services service instance located in the same location as the new bucket.\nThis operation does not make use of operation specific query parameters.\n\nFor more information on using Key Protect to manage your encryption keys, [see the documentation for Key Protect](https://cloud.ibm.com/docs/key-protect?topic=key-protect-getting-started-tutorial).\n\nFor more information on Hyper Protect Crypto Services, [see the documentation](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-get-started).\n\n:::note\nNote that managed encryption is **not** available in a Cross Region configuration and any SSE-KP buckets must be Regional.\n:::",
         "parameters": [
           {
             "name": "bucketName",

Original file line number	Diff line number	Diff line change
`@@ -79,7 +79,7 @@`
`79`	`79`	`"put": {`
`80`	`80`	`"tags": ["Bucket operations"],`
`81`	`81`	`"summary": "Create a bucket",`
`82`		- "description": "A `PUT` request sent to the endpoint root followed by a string will create a bucket.\nFor more information about endpoints, see [Endpoints and storage locations](https://cloud.ibm.com/docs/cloud-object-storage?topic=cloud-object-storage-endpoints#endpoints).\nBucket names must be globally unique and DNS-compliant; names between 3 and 63 characters long must be made of lowercase letters, numbers, and dashes.\nBucket names must begin and end with a lowercase letter or number.\nBucket names resembling IP addresses are not allowed.\nThis operation doesn't make use of operation specific query parameters.\n\n:::info important\nBucket names must be unique because all buckets in the public cloud share a global namespace.\nThis allows for access to a bucket without needing to provide any service instance or account information.\nIt is also not possible to create a bucket with a name beginning with `cosv1-` or `account-` as these prefixes are reserved by the system.\n:::\n\n:::note\nPersonally Identifiable Information (PII): When creating buckets or adding objects, please ensure to not use any information that can identify any user (natural person) by name, location or any other means in the name of the bucket or object.\n:::\n\n## Create a bucket with a different storage class\n\nTo create a bucket with a different storage class, send an XML block specifying a bucket configuration with a `LocationConstraint` of `{provisioning code}` in the body of a `PUT` request to a bucket endpoint.\nFor more information about endpoints, see [Endpoints and storage locations](https://cloud.ibm.com/docs/cloud-object-storage?topic=cloud-object-storage-endpoints#endpoints).\nNote that standard bucket [naming rules](https://cloud.ibm.com/docs/cloud-object-storage?topic=cloud-object-storage-compatibility-api-bucket-operations#compatibility-api-new-bucket) apply.\nThis operation does not make use of operation specific query parameters.\n\nThe body of the request must contain an XML block with the following schema:\n\n```xml\n<CreateBucketConfiguration>\n <LocationConstraint>us-vault</LocationConstraint>\n</CreateBucketConfiguration>\n```\n\nA list of valid provisioning codes for `LocationConstraint` can be referenced in [the Storage Classes guide](https://cloud.ibm.com/docs/cloud-object-storage?topic=cloud-object-storage-classes#classes-locationconstraint).\n\n## Create a new bucket with Key Protect or Hyper Protect Crypto Services managed encryption keys (SSE-KP)\n\nTo create a bucket where the encryption keys are managed by Key Protect or Hyper Protect Crypto Services, it is necessary to have access to an active Key Protect or Hyper Protect Crypto Services service instance located in the same location as the new bucket.\nThis operation does not make use of operation specific query parameters.\n\nFor more information on using Key Protect to manage your encryption keys, [see the documentation for Key Protect](https://cloud.ibm.com/docs/key-protect?topic=key-protect-getting-started-tutorial).\n\nFor more information on Hyper Protect Crypto Services, [see the documentation](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-get-started).\n\n:::note\nNote that managed encryption is not available in a Cross Region configuration and any SSE-KP buckets must be Regional.\n:::",
	`82`	+ "description": "A `PUT` request sent to the endpoint root followed by a string will create a bucket.\nFor more information about endpoints, see [Endpoints and storage locations](https://cloud.ibm.com/docs/cloud-object-storage?topic=cloud-object-storage-endpoints#endpoints).\nBucket names must be globally unique and DNS-compliant; names between 3 and 63 characters long must be made of lowercase letters, numbers, and dashes.\nBucket names must begin and end with a lowercase letter or number.\nBucket names resembling IP addresses are not allowed.\nThis operation doesn't make use of operation specific query parameters.\n\n:::info[important]\nBucket names must be unique because all buckets in the public cloud share a global namespace.\nThis allows for access to a bucket without needing to provide any service instance or account information.\nIt is also not possible to create a bucket with a name beginning with `cosv1-` or `account-` as these prefixes are reserved by the system.\n:::\n\n:::note\nPersonally Identifiable Information (PII): When creating buckets or adding objects, please ensure to not use any information that can identify any user (natural person) by name, location or any other means in the name of the bucket or object.\n:::\n\n## Create a bucket with a different storage class\n\nTo create a bucket with a different storage class, send an XML block specifying a bucket configuration with a `LocationConstraint` of `{provisioning code}` in the body of a `PUT` request to a bucket endpoint.\nFor more information about endpoints, see [Endpoints and storage locations](https://cloud.ibm.com/docs/cloud-object-storage?topic=cloud-object-storage-endpoints#endpoints).\nNote that standard bucket [naming rules](https://cloud.ibm.com/docs/cloud-object-storage?topic=cloud-object-storage-compatibility-api-bucket-operations#compatibility-api-new-bucket) apply.\nThis operation does not make use of operation specific query parameters.\n\nThe body of the request must contain an XML block with the following schema:\n\n```xml\n<CreateBucketConfiguration>\n <LocationConstraint>us-vault</LocationConstraint>\n</CreateBucketConfiguration>\n```\n\nA list of valid provisioning codes for `LocationConstraint` can be referenced in [the Storage Classes guide](https://cloud.ibm.com/docs/cloud-object-storage?topic=cloud-object-storage-classes#classes-locationconstraint).\n\n## Create a new bucket with Key Protect or Hyper Protect Crypto Services managed encryption keys (SSE-KP)\n\nTo create a bucket where the encryption keys are managed by Key Protect or Hyper Protect Crypto Services, it is necessary to have access to an active Key Protect or Hyper Protect Crypto Services service instance located in the same location as the new bucket.\nThis operation does not make use of operation specific query parameters.\n\nFor more information on using Key Protect to manage your encryption keys, [see the documentation for Key Protect](https://cloud.ibm.com/docs/key-protect?topic=key-protect-getting-started-tutorial).\n\nFor more information on Hyper Protect Crypto Services, [see the documentation](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-get-started).\n\n:::note\nNote that managed encryption is not available in a Cross Region configuration and any SSE-KP buckets must be Regional.\n:::",
`83`	`83`	`"parameters": [`
`84`	`84`	`{`
`85`	`85`	`"name": "bucketName",`