diff --git a/docs/src/accessibility-testing-js.md b/docs/src/accessibility-testing-js.md
index d367662545..96fe1f1865 100644
--- a/docs/src/accessibility-testing-js.md
+++ b/docs/src/accessibility-testing-js.md
@@ -14,7 +14,7 @@ A few examples of problems this can catch include:
 
 The following examples rely on the [`@axe-core/playwright`](https://npmjs.org/@axe-core/playwright) package which adds support for running the [axe accessibility testing engine](https://www.deque.com/axe/) as part of your Playwright tests.
 
-:::note Disclaimer
+:::note[Disclaimer]
 Automated accessibility tests can detect some common accessibility problems such as missing or invalid properties. But many accessibility problems can only be discovered through manual testing. We recommend using a combination of automated testing, manual accessibility assessments, and inclusive user testing.
 
 For manual assessments, we recommend [Accessibility Insights for Web](https://accessibilityinsights.io/docs/web/overview/?referrer=playwright-accessibility-testing-js), a free and open source dev tool that walks you through assessing a website for [WCAG 2.1 AA](https://www.w3.org/WAI/WCAG21/quickref/?currentsidebar=%23col_customize&levels=aaa) coverage.
diff --git a/docs/src/api/class-elementhandle.md b/docs/src/api/class-elementhandle.md
index 6d727f675a..3f27509a0d 100644
--- a/docs/src/api/class-elementhandle.md
+++ b/docs/src/api/class-elementhandle.md
@@ -4,7 +4,7 @@
 
 ElementHandle represents an in-page DOM element. ElementHandles can be created with the [`method: Page.querySelector`] method.
 
-:::caution Discouraged
+:::warning[Discouraged]
 The use of ElementHandle is discouraged, use [Locator] objects and web-first assertions instead.
 :::
 
diff --git a/docs/src/api/class-locator.md b/docs/src/api/class-locator.md
index 50ef738c9a..9ccfa6c2b1 100644
--- a/docs/src/api/class-locator.md
+++ b/docs/src/api/class-locator.md
@@ -53,7 +53,7 @@ foreach (var li in await page.GetByRole("listitem").AllAsync())
 
 Returns an array of `node.innerText` values for all matching nodes.
 
-:::caution Asserting text
+:::warning[Asserting text]
 If you need to assert text on the page, prefer [`method: LocatorAssertions.toHaveText`] with [`option: useInnerText`] option to avoid flakiness. See [assertions guide](../test-assertions.md) for more details.
 :::
 
@@ -85,7 +85,7 @@ var texts = await page.GetByRole(AriaRole.Link).AllInnerTextsAsync();
 
 Returns an array of `node.textContent` values for all matching nodes.
 
-:::caution Asserting text
+:::warning[Asserting text]
 If you need to assert text on the page, prefer [`method: LocatorAssertions.toHaveText`] to avoid flakiness. See [assertions guide](../test-assertions.md) for more details.
 :::
 
@@ -443,7 +443,7 @@ await page.Locator("canvas").ClickAsync(new() {
 
 Returns the number of elements matching the locator.
 
-:::caution Asserting count
+:::warning[Asserting count]
 If you need to assert the number of elements on the page, prefer [`method: LocatorAssertions.toHaveCount`] to avoid flakiness. See [assertions guide](../test-assertions.md) for more details.
 :::
 
@@ -1121,7 +1121,7 @@ await locator.ClickAsync();
 
 Returns the matching element's attribute value.
 
-:::caution Asserting attributes
+:::warning[Asserting attributes]
 If you need to assert an element's attribute, prefer [`method: LocatorAssertions.toHaveAttribute`] to avoid flakiness. See [assertions guide](../test-assertions.md) for more details.
 :::
 
@@ -1293,7 +1293,7 @@ Returns the [`element.innerHTML`](https://developer.mozilla.org/en-US/docs/Web/A
 
 Returns the [`element.innerText`](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/innerText).
 
-:::caution Asserting text
+:::warning[Asserting text]
 If you need to assert text on the page, prefer [`method: LocatorAssertions.toHaveText`] with [`option: useInnerText`] option to avoid flakiness. See [assertions guide](../test-assertions.md) for more details.
 :::
 
@@ -1309,7 +1309,7 @@ If you need to assert text on the page, prefer [`method: LocatorAssertions.toHav
 
 Returns the value for the matching `<input>` or `<textarea>` or `<select>` element.
 
-:::caution Asserting value
+:::warning[Asserting value]
 If you need to assert input value, prefer [`method: LocatorAssertions.toHaveValue`] to avoid flakiness. See [assertions guide](../test-assertions.md) for more details.
 :::
 
@@ -1351,7 +1351,7 @@ Throws elements that are not an input, textarea or a select. However, if the ele
 
 Returns whether the element is checked. Throws if the element is not a checkbox or radio input.
 
-:::caution Asserting checked state
+:::warning[Asserting checked state]
 If you need to assert that checkbox is checked, prefer [`method: LocatorAssertions.toBeChecked`] to avoid flakiness. See [assertions guide](../test-assertions.md) for more details.
 :::
 
@@ -1389,7 +1389,7 @@ var isChecked = await page.GetByRole(AriaRole.Checkbox).IsCheckedAsync();
 
 Returns whether the element is disabled, the opposite of [enabled](../actionability.md#enabled).
 
-:::caution Asserting disabled state
+:::warning[Asserting disabled state]
 If you need to assert that an element is disabled, prefer [`method: LocatorAssertions.toBeDisabled`] to avoid flakiness. See [assertions guide](../test-assertions.md) for more details.
 :::
 
@@ -1427,7 +1427,7 @@ Boolean disabled = await page.GetByRole(AriaRole.Button).IsDisabledAsync();
 
 Returns whether the element is [editable](../actionability.md#editable).
 
-:::caution Asserting editable state
+:::warning[Asserting editable state]
 If you need to assert that an element is editable, prefer [`method: LocatorAssertions.toBeEditable`] to avoid flakiness. See [assertions guide](../test-assertions.md) for more details.
 :::
 
@@ -1465,7 +1465,7 @@ Boolean editable = await page.GetByRole(AriaRole.Textbox).IsEditableAsync();
 
 Returns whether the element is [enabled](../actionability.md#enabled).
 
-:::caution Asserting enabled state
+:::warning[Asserting enabled state]
 If you need to assert that an element is enabled, prefer [`method: LocatorAssertions.toBeEnabled`] to avoid flakiness. See [assertions guide](../test-assertions.md) for more details.
 :::
 
@@ -1503,7 +1503,7 @@ Boolean enabled = await page.GetByRole(AriaRole.Button).IsEnabledAsync();
 
 Returns whether the element is hidden, the opposite of [visible](../actionability.md#visible).
 
-:::caution Asserting visibility
+:::warning[Asserting visibility]
 If you need to assert that element is hidden, prefer [`method: LocatorAssertions.toBeHidden`] to avoid flakiness. See [assertions guide](../test-assertions.md) for more details.
 :::
 
@@ -1540,7 +1540,7 @@ Boolean hidden = await page.GetByRole(AriaRole.Button).IsHiddenAsync();
 
 Returns whether the element is [visible](../actionability.md#visible).
 
-:::caution Asserting visibility
+:::warning[Asserting visibility]
 If you need to assert that element is visible, prefer [`method: LocatorAssertions.toBeVisible`] to avoid flakiness. See [assertions guide](../test-assertions.md) for more details.
 :::
 
@@ -2324,7 +2324,7 @@ When all steps combined have not finished during the specified [`option: timeout
 
 Returns the [`node.textContent`](https://developer.mozilla.org/en-US/docs/Web/API/Node/textContent).
 
-:::caution Asserting text
+:::warning[Asserting text]
 If you need to assert text on the page, prefer [`method: LocatorAssertions.toHaveText`] to avoid flakiness. See [assertions guide](../test-assertions.md) for more details.
 :::
 
diff --git a/docs/src/api/class-page.md b/docs/src/api/class-page.md
index caea5998b6..fdc3fa165a 100644
--- a/docs/src/api/class-page.md
+++ b/docs/src/api/class-page.md
@@ -3146,7 +3146,7 @@ return value resolves to `[]`.
 ## async method: Page.addLocatorHandler
 * since: v1.42
 
-:::warning Experimental
+:::warning[Experimental]
 This method is experimental and its behavior may change in the upcoming releases.
 :::
 
diff --git a/docs/src/api/params.md b/docs/src/api/params.md
index e33cd7d664..e3b2894c3c 100644
--- a/docs/src/api/params.md
+++ b/docs/src/api/params.md
@@ -999,11 +999,10 @@ disable timeout.
 If specified, traces are saved into this directory.
 
 ## browser-option-devtools
+* deprecated: Use [debugging tools](../debug.md) instead.
 - `devtools` <[boolean]>
 
-**Deprecated, Chromium-only.** Use [debugging tools](../debug.md) instead.
-
-Whether to auto-open a Developer Tools panel for each tab. If this option is `true`, the
+**Chromium-only** Whether to auto-open a Developer Tools panel for each tab. If this option is `true`, the
 [`option: headless`] option will be set `false`.
 
 ## browser-option-slowmo
diff --git a/docs/src/handles.md b/docs/src/handles.md
index 0707891936..1a1f368267 100644
--- a/docs/src/handles.md
+++ b/docs/src/handles.md
@@ -52,7 +52,7 @@ var jsHandle = await page.EvaluateHandleAsync("window");
 
 ## Element Handles
 
-:::caution Discouraged
+:::warning[Discouraged]
 The use of [ElementHandle] is discouraged, use [Locator] objects and web-first assertions instead.
 :::
 
diff --git a/docs/src/locators.md b/docs/src/locators.md
index 720e5618ca..6d5926b579 100644
--- a/docs/src/locators.md
+++ b/docs/src/locators.md
@@ -264,7 +264,7 @@ Role locators include [buttons, checkboxes, headings, links, lists, tables, and
 
 Note that role locators **do not replace** accessibility audits and conformance tests, but rather give early feedback about the ARIA guidelines.
 
-:::note When to use role locators
+:::note[When to use role locators]
 We recommend prioritizing role locators to locate elements, as it is the closest way to how users and assistive technology perceive the page.
 :::
 
@@ -301,7 +301,7 @@ page.get_by_label("Password").fill("secret")
 await page.GetByLabel("Password").FillAsync("secret");
 ```
 
-:::note When to use label locators
+:::note[When to use label locators]
 Use this locator when locating form fields.
 :::
 ### Locate by placeholder
@@ -340,7 +340,7 @@ await page
     .FillAsync("playwright@microsoft.com");
 ```
 
-:::note When to use placeholder locators
+:::note[When to use placeholder locators]
 Use this locator when locating form elements that do not have labels but do have placeholder texts.
 :::
 
@@ -433,7 +433,7 @@ await Expect(Page
 Matching by text always normalizes whitespace, even with exact match. For example, it turns multiple spaces into one, turns line breaks into spaces and ignores leading and trailing whitespace.
 :::
 
-:::note When to use text locators
+:::note[When to use text locators]
 We recommend using text locators to find non interactive elements like `div`, `span`, `p`, etc. For interactive elements like `button`, `a`, `input`, etc. use [role locators](#locate-by-role).
 :::
 
@@ -471,7 +471,7 @@ page.get_by_alt_text("playwright logo").click()
 await page.GetByAltText("playwright logo").ClickAsync();
 ```
 
-:::note When to use alt locators
+:::note[When to use alt locators]
 Use this locator when your element supports alt text such as `img` and `area` elements.
 :::
 
@@ -507,7 +507,7 @@ expect(page.get_by_title("Issues count")).to_have_text("25 issues")
 await Expect(Page.GetByTitle("Issues count")).toHaveText("25 issues");
 ```
 
-:::note When to use title locators
+:::note[When to use title locators]
 Use this locator when your element has the `title` attribute.
 :::
 
@@ -543,7 +543,7 @@ page.get_by_test_id("directions").click()
 await page.GetByTestId("directions").ClickAsync();
 ```
 
-:::note When to use testid locators
+:::note[When to use testid locators]
 You can also use test ids when you choose to use the test id methodology or when you can't locate by [role](#locate-by-role) or [text](#locate-by-text).
 :::
 
@@ -693,7 +693,7 @@ await page.Locator("#tsf > div:nth-child(2) > div.A8SBwf > div.RNNXgb > div > di
 await page.Locator("//*[@id='tsf']/div[2]/div[1]/div[1]/div/div[2]/input").ClickAsync();
 ```
 
-:::note When to use this
+:::note[When to use this]
 CSS and XPath are not recommended as the DOM can often change leading to non resilient tests. Instead, try to come up with a locator that is close to how the user perceives the page such as [role locators](#locate-by-role) or [define an explicit testing contract](#locate-by-test-id) using test ids.
 :::
 
diff --git a/packages/playwright-core/types/types.d.ts b/packages/playwright-core/types/types.d.ts
index 3bc56b0a83..b0071ffd02 100644
--- a/packages/playwright-core/types/types.d.ts
+++ b/packages/playwright-core/types/types.d.ts
@@ -13173,10 +13173,9 @@ export interface BrowserType<Unused = {}> {
     deviceScaleFactor?: number;
 
     /**
-     * **Deprecated, Chromium-only.** Use [debugging tools](https://playwright.dev/docs/debug) instead.
-     *
-     * Whether to auto-open a Developer Tools panel for each tab. If this option is `true`, the `headless` option will be
-     * set `false`.
+     * **Chromium-only** Whether to auto-open a Developer Tools panel for each tab. If this option is `true`, the
+     * `headless` option will be set `false`.
+     * @deprecated Use [debugging tools](https://playwright.dev/docs/debug) instead.
      */
     devtools?: boolean;
 
@@ -13579,10 +13578,9 @@ export interface BrowserType<Unused = {}> {
     chromiumSandbox?: boolean;
 
     /**
-     * **Deprecated, Chromium-only.** Use [debugging tools](https://playwright.dev/docs/debug) instead.
-     *
-     * Whether to auto-open a Developer Tools panel for each tab. If this option is `true`, the `headless` option will be
-     * set `false`.
+     * **Chromium-only** Whether to auto-open a Developer Tools panel for each tab. If this option is `true`, the
+     * `headless` option will be set `false`.
+     * @deprecated Use [debugging tools](https://playwright.dev/docs/debug) instead.
      */
     devtools?: boolean;
 
@@ -20278,10 +20276,9 @@ export interface LaunchOptions {
   chromiumSandbox?: boolean;
 
   /**
-   * **Deprecated, Chromium-only.** Use [debugging tools](https://playwright.dev/docs/debug) instead.
-   *
-   * Whether to auto-open a Developer Tools panel for each tab. If this option is `true`, the `headless` option will be
-   * set `false`.
+   * **Chromium-only** Whether to auto-open a Developer Tools panel for each tab. If this option is `true`, the
+   * `headless` option will be set `false`.
+   * @deprecated Use [debugging tools](https://playwright.dev/docs/debug) instead.
    */
   devtools?: boolean;