Fix docs rendering of mixed HTML / markdown content (#3585)

packages/core/src/components/button/button.md

@@ -21,13 +21,17 @@ Buttons trigger actions when clicked.
 ```
 
 <div class="@ns-callout @ns-intent-danger @ns-icon-error">
-    <h4 class="@ns-heading">Disabled `Button` prevents all interaction</h4>
-    Use `AnchorButton` if you need mouse interaction events (such as hovering) on a disabled button.
+    <h4 class="@ns-heading">
 
-    `Button` uses the native `disabled` attribute on the `<button>` tag so the browser disables all interactions.
-    `AnchorButton` uses the class `.@ns-disabled` because `<a>` tags do not support the `disabled`
-    attribute. As a result, the `AnchorButton` component will prevent *only* the `onClick` handler
-    when disabled but permit other events.
+Disabled `Button` prevents all interaction
+</h4>
+
+Use `AnchorButton` if you need mouse interaction events (such as hovering) on a disabled button.
+
+`Button` uses the native `disabled` attribute on the `<button>` tag so the browser disables all interactions.
+`AnchorButton` uses the class `.@ns-disabled` because `<a>` tags do not support the `disabled`
+attribute. As a result, the `AnchorButton` component will prevent *only* the `onClick` handler
+when disabled but permit other events.
 
 </div>
 

packages/core/src/components/collapsible-list/collapsible-list.md

@@ -7,18 +7,26 @@ customizing the appearance of visible items, using the props from the `MenuItem`
 children.
 
 <div class="@ns-callout @ns-intent-danger @ns-icon-error">
-    <h4 class="@ns-heading">Deprecated: use [Overflow list](#core/components/overflow-list)</h4>
-    This component is **deprecated since 3.0.0** with the introduction of
-    [`OverflowList`](#core/components/overflow-list) which provides a similar
-    experience with two distinct advantages:
-    <ol>
-        <li>Items collapse automatically based on available space in the container.</li>
-        <li>
-            `OverflowList` accepts a generic array of items (instead of explicit
-            `<MenuItem>` children) with custom renderers for both visible and overflowed
-            items, allowing for _any_ UI, not just a dropdown menu.
-        </li>
-    </ol>
+    <h4 class="@ns-heading">
+
+Deprecated: use [Overflow list](#core/components/overflow-list)
+</h4>
+
+This component is **deprecated since 3.0.0** with the introduction of
+[`OverflowList`](#core/components/overflow-list) which provides a similar
+experience with two distinct advantages:
+
+<ol>
+    <li>Items collapse automatically based on available space in the container.</li>
+    <li>
+
+`OverflowList` accepts a generic array of items (instead of explicit
+`<MenuItem>` children) with custom renderers for both visible and overflowed
+items, allowing for _any_ UI, not just a dropdown menu.
+
+</li>
+</ol>
+
 </div>
 
 @reactExample CollapsibleListExample

packages/core/src/components/dialog/dialog.md

@@ -4,11 +4,13 @@ Dialogs present content overlaid over other parts of the UI.
 
 <div class="@ns-callout @ns-intent-primary @ns-icon-info-sign">
     <h4 class="@ns-heading">Terminology note</h4>
-    The term "modal" is sometimes used to mean "dialog," but this is a misnomer.
-    _Modal_ is an adjective that describes parts of a UI.
-    An element is considered modal if it
-    [blocks interaction with the rest of the application](https://en.wikipedia.org/wiki/Modal_window).
-    We use the term "dialog" to avoid confusion with the adjective.
+
+The term "modal" is sometimes used to mean "dialog," but this is a misnomer.
+_Modal_ is an adjective that describes parts of a UI.
+An element is considered modal if it
+[blocks interaction with the rest of the application](https://en.wikipedia.org/wiki/Modal_window).
+We use the term "dialog" to avoid confusion with the adjective.
+
 </div>
 
 @reactExample DialogExample

packages/core/src/components/editable-text/editable-text.md

@@ -15,9 +15,11 @@ You should not use `EditableText` when a static always-editable `<input>` or
 
 <div class="@ns-callout @ns-intent-danger @ns-icon-error">
     <h4 class="@ns-heading">Centering the component</h4>
-    **Do not center this component** using `text-align: center`, as it will cause an infinite loop
-    in the browser ([more details](https://github.com/JedWatson/react-select/issues/540)). Instead,
-    you should center the component via flexbox or with `position` and `transform: translateX(-50%)`.
+
+**Do not center this component** using `text-align: center`, as it will cause an infinite loop
+in the browser ([more details](https://github.com/JedWatson/react-select/issues/540)). Instead,
+you should center the component via flexbox or with `position` and `transform: translateX(-50%)`.
+
 </div>
 
 

packages/core/src/components/forms/control-group.md

@@ -6,13 +6,17 @@ groups, and HTML selects as direct children.
 
 <div class="@ns-callout @ns-intent-success @ns-icon-comparison">
     <h4 class="@ns-heading">Control group vs. input group</h4>
-    <p>Both components group multiple elements into a single unit, but their usage patterns are
-    quite different.</p>
-    <p>Think of `ControlGroup` as a parent with multiple children, with each one a separate
-    control.</p>
-    <p>Conversely, an `InputGroup` is a single control, and should function like so. A
-    button inside of an input group should only affect that input; if its reach is further, then it
-    should be promoted to live in a control group.</p>
+
+Both components group multiple elements into a single unit, but their usage patterns are
+quite different.
+
+Think of `ControlGroup` as a parent with multiple children, with each one a separate
+control.
+
+Conversely, an `InputGroup` is a single control, and should function like so. A
+button inside of an input group should only affect that input; if its reach is further, then it
+should be promoted to live in a control group.
+
 </div>
 
 @reactExample ControlGroupExample

packages/core/src/components/forms/file-input.md

@@ -12,8 +12,10 @@ Use `inputProps` to apply props to the `<input>` element.
 
 <div class="@ns-callout @ns-intent-warning @ns-icon-warning-sign">
     <h4 class="@ns-heading">Static file name</h4>
-    File name does not update on file selection. To get this behavior,
-    you must implement it separately in JS.
+
+File name does not update on file selection. To get this behavior,
+you must implement it separately in JS.
+
 </div>
 
 ```tsx

packages/core/src/components/forms/label.md

@@ -8,10 +8,12 @@ below, clicking a label focuses its `<input>`.
 
 <div class="@ns-callout @ns-intent-warning @ns-icon-warning-sign">
     <h4 class="@ns-heading">Prefer form groups over labels</h4>
-    The [React `FormGroup` component](#core/components/form-group) provides
-    additional functionality such as helper text and modifier props as well as
-    full label support. `FormGroup` supports both simple and complex use cases,
-    therefore we recommend using it exclusively when constructing forms.
+
+The [React `FormGroup` component](#core/components/form-group) provides
+additional functionality such as helper text and modifier props as well as
+full label support. `FormGroup` supports both simple and complex use cases,
+therefore we recommend using it exclusively when constructing forms.
+
 </div>
 
 @## Props

packages/core/src/components/forms/numeric-input.md

@@ -43,9 +43,11 @@ custom `onKeyDown` callback) and when the field loses focus (via a custom
 trigged, the field will be cleared.
 
 <div class="@ns-callout @ns-intent-primary @ns-icon-info-sign">
-    This example contains non-core functionality that is meant to demonstrate
-    the extensibility of the `NumericInput` component. The correctness of the
-    custom evaluation code has not been tested robustly.
+
+This example contains non-core functionality that is meant to demonstrate
+the extensibility of the `NumericInput` component. The correctness of the
+custom evaluation code has not been tested robustly.
+
 </div>
 
 @reactExample NumericInputExtendedExample

packages/core/src/components/forms/text-inputs.md

@@ -39,12 +39,13 @@ the parent input.
 
 <div class="@ns-callout @ns-intent-warning @ns-icon-warning-sign">
     <h4 class="@ns-heading">Icons only</h4>
-    <p>You cannot use buttons with text in the CSS API for input groups. The padding for text inputs
-    in CSS cannot accommodate buttons whose width varies due to text content. You should use icons on
-    buttons instead.</p>
 
-    Conversely, the [`InputGroup`](#core/components/text-inputs.input-group) React
-    component _does_ support arbitrary content in its right element.
+You cannot use buttons with text in the CSS API for input groups. The padding for text inputs
+in CSS cannot accommodate buttons whose width varies due to text content. You should use icons on
+buttons instead.
+
+Conversely, the [`InputGroup`](#core/components/text-inputs.input-group) React
+component _does_ support arbitrary content in its right element.
 
 </div>
 

packages/core/src/components/html-select/html-select.md

@@ -5,9 +5,11 @@ dropdown caret, so we provide an `HTMLSelect` component to streamline this
 process.
 
 <div class="@ns-callout @ns-intent-success @ns-icon-info-sign">
-    The [`Select`](#select/multi-select) component in the [**@blueprintjs/select**](#select)
-    package provides a React alternative to the native HTML `<select>` tag. Notably, it
-    supports custom filtering logic and item rendering.
+
+The [`Select`](#select/multi-select) component in the [**@blueprintjs/select**](#select)
+package provides a React alternative to the native HTML `<select>` tag. Notably, it
+supports custom filtering logic and item rendering.
+
 </div>
 
 @## Props

packages/core/src/components/html-table/html-table.md

@@ -4,9 +4,11 @@ This component provides Blueprint styling to native HTML tables.
 
 <div class="@ns-callout @ns-intent-primary @ns-icon-info-sign">
     <h4 class="@ns-heading">This is not @blueprintjs/table</h4>
-    This table component is a simple CSS-only skin for HTML `<table>` elements.
-    It is ideal for basic static tables. If you're looking for more complex
-    spreadsheet-like features, check out [**@blueprintjs/table**](#table).
+
+This table component is a simple CSS-only skin for HTML `<table>` elements.
+It is ideal for basic static tables. If you're looking for more complex
+spreadsheet-like features, check out [**@blueprintjs/table**](#table).
+
 </div>
 
 @## Props

packages/core/src/components/icon/icon.md

@@ -1,15 +1,19 @@
 @# Icon
 
 <div class="@ns-callout @ns-intent-primary @ns-icon-info-sign">
-    See the [**Icons package**](#icons) for a searchable list of all available UI icons.
+
+See the [**Icons package**](#icons) for a searchable list of all available UI icons.
+
 </div>
 
 <div class="@ns-callout @ns-intent-primary @ns-icon-info-sign">
     <h4 class="@ns-heading">SVG icons in 2.0</h4>
-    Blueprint 2.0 introduced SVG icon support and moved icon resources to a separate __@blueprintjs/icons__ package.
-    The `Icon` component renders SVG paths and the icon classes are no longer used by any Blueprint React component.
-    Icon font support has been preserved but should be considered a legacy feature that will be removed in a
-    future major version.
+
+Blueprint 2.0 introduced SVG icon support and moved icon resources to a separate __@blueprintjs/icons__ package.
+The `Icon` component renders SVG paths and the icon classes are no longer used by any Blueprint React component.
+Icon font support has been preserved but should be considered a legacy feature that will be removed in a
+future major version.
+
 </div>
 
 This section describes two ways of using the UI icon font: via React `Icon`
@@ -66,9 +70,11 @@ import { IconNames } from "@blueprintjs/icons";
 
 <div class="@ns-callout @ns-intent-warning @ns-icon-warning-sign">
     <h4 class="@ns-heading">Icon fonts are legacy in 2.0</h4>
-    Blueprint's icon fonts should be considered a legacy feature and will be removed in a future major version.
-    The SVGs rendered by the React component do not suffer from the blurriness of icon fonts, and browser
-    support is equivalent.
+
+Blueprint's icon fonts should be considered a legacy feature and will be removed in a future major version.
+The SVGs rendered by the React component do not suffer from the blurriness of icon fonts, and browser
+support is equivalent.
+
 </div>
 
 The CSS-only icons API uses the __icon fonts__ from the __@blueprintjs/icons__ package.
@@ -88,7 +94,9 @@ Icon classes also support the four `.@ns-intent-*` modifiers to color the image.
 
 <div class="@ns-callout @ns-intent-primary @ns-icon-info-sign">
     <h4 class="@ns-heading">Non-standard sizes</h4>
-    Generally, font icons should only be used at either 16px or 20px. However, if a non-standard size is
-    necessary, set a `font-size` that is whole multiple of 16 or 20 with the relevant size class.
-    You can instead use the class `@ns-icon` to make the icon inherit its size from surrounding text.
+
+Generally, font icons should only be used at either 16px or 20px. However, if a non-standard size is
+necessary, set a `font-size` that is whole multiple of 16 or 20 with the relevant size class.
+You can instead use the class `@ns-icon` to make the icon inherit its size from surrounding text.
+
 </div>

packages/core/src/components/menu/menu.md

@@ -43,8 +43,10 @@ there is not enough room to the right.
 
 <div class="@ns-callout @ns-intent-warning @ns-icon-warning-sign">
     <h4 class="@ns-heading">JavaScript only</h4>
-    Submenus are only supported in the React components. They cannot be created with CSS alone because
-    they rely on the [`Popover`](#core/components/popover) component for positioning and transitions.
+
+Submenus are only supported in the React components. They cannot be created with CSS alone because
+they rely on the [`Popover`](#core/components/popover) component for positioning and transitions.
+
 </div>
 
 @## Props
@@ -126,8 +128,10 @@ as they abstract away the tedious parts of implementing a menu.
 defined as part of `.@ns-menu-item`.</small>
 
 <div class="@ns-callout @ns-intent-primary @ns-icon-info-sign">
-    Note that the following examples are `display: inline-block`; you may need to adjust
-    menu width in your own usage.
+
+Note that the following examples are `display: inline-block`; you may need to adjust
+menu width in your own usage.
+
 </div>
 
 @css menu

packages/core/src/components/navbar/navbar.md

@@ -14,8 +14,10 @@ This modifier is not illustrated here because it breaks the document flow.
 
 <div class="@ns-callout @ns-intent-danger @ns-icon-error">
     <h4 class="@ns-heading">Body padding required</h4>
-    The fixed navbar will lie on top of your other content unless you add padding to the top of the
-    `<body>` element equal to the height of the navbar. Use the `$pt-navbar-height` Sass variable.
+
+The fixed navbar will lie on top of your other content unless you add padding to the top of the
+`<body>` element equal to the height of the navbar. Use the `$pt-navbar-height` Sass variable.
+
 </div>
 
 @### Fixed width

packages/core/src/components/overlay/overlay.md

@@ -44,8 +44,9 @@ actually closes the overlay.
 
 <div class="@ns-callout @ns-intent-primary @ns-icon-info-sign">
     <h4 class="@ns-heading">A note about overlay content positioning</h4>
-    When rendered inline, content will automatically be set to `position: absolute` to respect
-    document flow. Otherwise, content will be set to `position: fixed` to cover the entire viewport.
+
+When rendered inline, content will automatically be set to `position: absolute` to respect
+document flow. Otherwise, content will be set to `position: fixed` to cover the entire viewport.
 </div>
 
 ```tsx