Add subsections for references with 2+ examples.

docs/styles/align.md

@@ -23,6 +23,8 @@ To specify alignment on a single axis, use the respective style and type:
 
 ## Examples
 
+### Basic usage
+
 This example contains a simple app with two labels centered on the screen with `align: center middle;`:
 
 === "align.py"
@@ -43,6 +45,8 @@ This example contains a simple app with two labels centered on the screen with `
 
     ```
 
+### All alignments
+
 The next example shows a 3 by 3 grid of containers with text labels.
 Each label has been aligned differently inside its container, and its text shows its `align: ...` value.
 

docs/styles/background.md

@@ -12,6 +12,8 @@ The style `background` needs a [`<color>`](../../css_types/color) followed by an
 
 ## Examples
 
+### Basic usage
+
 This example creates three widgets and applies a different background to each.
 
 === "background.py"
@@ -31,6 +33,8 @@ This example creates three widgets and applies a different background to each.
     ```{.textual path="docs/examples/styles/background.py"}
     ```
 
+### Different transparency settings
+
 The next example creates ten widgets layed out side by side to show the effect of setting different percentages for the transparency of the background color.
 
 === "background_transparency.py"

docs/styles/border.md

@@ -54,6 +54,8 @@ Alternatively, you can see the examples below.
 
 ## Examples
 
+### Basic usage
+
 This examples shows three widgets with different border styles.
 
 === "border.py"
@@ -73,6 +75,8 @@ This examples shows three widgets with different border styles.
     ```{.textual path="docs/examples/styles/border.py"}
     ```
 
+### All border types
+
 The next example shows a grid with all the available border types.
 
 === "border_all.py"
@@ -92,6 +96,30 @@ The next example shows a grid with all the available border types.
     ```{.textual path="docs/examples/styles/border_all.py"}
     ```
 
+### Borders and outlines
+
+The next example makes the difference between [`border`](./border.md) and [`outline`](./outline.md) clearer by having three labels side-by-side.
+They contain the same text, have the same width and height, and are styled exactly the same up to their `outline` and [`border`](./border.md) rules.
+
+This example also shows that a widget cannot contain both a `border` and an `outline`:
+
+=== "Output"
+
+    ```{.textual path="docs/examples/styles/outline_vs_border.py"}
+    ```
+
+=== "outline_vs_border.py"
+
+    ```python
+    --8<-- "docs/examples/styles/outline_vs_border.py"
+    ```
+
+=== "outline_vs_border.css"
+
+    ```sass
+    --8<-- "docs/examples/styles/outline_vs_border.css"
+    ```
+
 ## CSS
 
 ```sass

docs/styles/color.md

@@ -14,6 +14,8 @@ Instead of a [`<color>`](../../css_types/color), one can use the special value `
 
 ## Examples
 
+### Basic usage
+
 This example sets a different text color for each of three different widgets.
 
 === "color.py"
@@ -33,6 +35,8 @@ This example sets a different text color for each of three different widgets.
     ```{.textual path="docs/examples/styles/color.py"}
     ```
 
+### Auto
+
 The next example shows how `auto` chooses between a lighter or a darker text color to increase the contrast and improve readability.
 
 === "color_auto.py"

docs/styles/content_align.md

@@ -24,6 +24,8 @@ To specify content alignment on a single axis, use the respective style and type
 
 ## Examples
 
+### Basic usage
+
 This first example shows three labels stacked vertically, each with different content alignments.
 
 === "content_align.py"
@@ -43,6 +45,8 @@ This first example shows three labels stacked vertically, each with different co
     ```{.textual path="docs/examples/styles/content_align.py"}
     ```
 
+### All content alignments
+
 The next example shows a 3 by 3 grid of labels.
 Each label has its text aligned differently.
 

docs/styles/dock.md

@@ -12,6 +12,8 @@ The option chosen determines the edge to which the widget is docked.
 
 ## Examples
 
+### Basic usage
+
 The example below shows a `left` docked sidebar.
 Notice that even though the content is scrolled, the sidebar remains fixed.
 
@@ -32,6 +34,8 @@ Notice that even though the content is scrolled, the sidebar remains fixed.
     --8<-- "docs/examples/guide/layout/dock_layout1_sidebar.css"
     ```
 
+### Advanced usage
+
 The second example shows how one can use full-width or full-height containers to dock labels to the edges of a larger container.
 The labels will remain in that position (docked) even if the container they are in scrolls horizontally and/or vertically.
 

docs/styles/grid/grid_size.md

@@ -20,6 +20,8 @@ If present, the second one sets the number of rows – regardless of the number
 
 ## Examples
 
+### Columns and rows
+
 In the first example, we create a grid with 2 columns and 5 rows, regardless of the fact that we do not have enough labels to fill in the whole grid:
 
 === "Output"
@@ -41,6 +43,8 @@ In the first example, we create a grid with 2 columns and 5 rows, regardless of
 
     1. Create a grid with 2 columns and 4 rows.
 
+### Columns only
+
 In the second example, we create a grid with 2 columns and however many rows are needed to display all of the grid children:
 
 === "Output"

docs/styles/height.md

@@ -13,6 +13,8 @@ By default, it sets the height of the content area, but if [`box-sizing`](./box_
 
 ## Examples
 
+### Basic usage
+
 This examples creates a widget with a height of 50% of the screen.
 
 === "height.py"
@@ -32,6 +34,8 @@ This examples creates a widget with a height of 50% of the screen.
     ```{.textual path="docs/examples/styles/height.py"}
     ```
 
+### All height formats
+
 The next example creates a series of wide widgets with heights set with different units.
 Open the CSS file tab to see the comments that explain how each height is computed.
 (The output includes a vertical ruler on the right to make it easier to check the height of each widget.)

docs/styles/margin.md

@@ -34,6 +34,8 @@ Alternatively, margin can be set for each edge individually through the rules `m
 
 ## Examples
 
+### Basic usage
+
 In the example below we add a large margin to a label, which makes it move away from the top-left corner of the screen.
 
 === "Output"
@@ -53,6 +55,8 @@ In the example below we add a large margin to a label, which makes it move away
     --8<-- "docs/examples/styles/margin.css"
     ```
 
+### All margin settings
+
 The next example shows a grid.
 In each cell, we have a placeholder that has its margins set in different ways.
 

docs/styles/outline.md

@@ -24,6 +24,8 @@ This rule can be useful for temporary emphasis of the content of a widget, if yo
 
 ## Examples
 
+### Basic usage
+
 This example shows a widget with an outline. Note how the outline occludes the text area.
 
 === "Output"
@@ -43,9 +45,33 @@ This example shows a widget with an outline. Note how the outline occludes the t
     --8<-- "docs/examples/styles/outline.css"
     ```
 
-The next example makes the difference clearer, by having three labels side-by-side.
+### All outline types
+
+The next example shows a grid with all the available outline types.
+
+=== "outline_all.py"
+
+    ```py
+    --8<-- "docs/examples/styles/outline_all.py"
+    ```
+
+=== "outline_all.css"
+
+    ```sass
+    --8<-- "docs/examples/styles/outline_all.css"
+    ```
+
+=== "Output"
+
+    ```{.textual path="docs/examples/styles/outline_all.py"}
+    ```
+
+### Borders and outlines
+
+The next example makes the difference between [`border`](./border.md) and [`outline`](./outline.md) clearer by having three labels side-by-side.
 They contain the same text, have the same width and height, and are styled exactly the same up to their `outline` and [`border`](./border.md) rules.
-This example also shows that a widget can contain both a `border` and an `outline`:
+
+This example also shows that a widget cannot contain both a `border` and an `outline`:
 
 === "Output"
 

docs/styles/scrollbar_size.md

@@ -19,6 +19,8 @@ The scrollbar widths may also be set individually with `scrollbar-size-horizonta
 
 ## Examples
 
+### Basic usage
+
 In this example we modify the size of the widget's scrollbar to be _much_ larger than usual.
 
 === "Output"
@@ -38,6 +40,8 @@ In this example we modify the size of the widget's scrollbar to be _much_ larger
     --8<-- "docs/examples/styles/scrollbar_size.css"
     ```
 
+### Scrollbar sizes comparison
+
 In the next example we show three containers with differently sized scrollbars.
 
 === "Output"

docs/styles/text_style.md

@@ -12,6 +12,8 @@ text-style: <a href="../../css_types/text_style">&lt;text-style&gt;</a>;
 
 ## Examples
 
+### Basic usage
+
 Each of the three text panels has a different text style, respectively `bold`, `italic`, and `reverse`, from left to right.
 
 === "Output"
@@ -31,6 +33,8 @@ Each of the three text panels has a different text style, respectively `bold`, `
     --8<-- "docs/examples/styles/text_style.css"
     ```
 
+### All text styles
+
 The next example shows all different styles on their own, as well as some combinations of styles in a single widget.
 
 === "Output"

docs/styles/visibility.md

@@ -30,6 +30,8 @@ This is shown in the second example below.
 
 ## Examples
 
+### Basic usage
+
 Note that the second widget is hidden, while leaving a space where it would have been rendered.
 
 === "Output"
@@ -49,6 +51,8 @@ Note that the second widget is hidden, while leaving a space where it would have
     --8<-- "docs/examples/styles/visibility.css"
     ```
 
+### Overriding container visibility
+
 The next example shows the interaction of the `visibility` rule with invisible containers that have visible children.
 The app below has three rows with a `Horizontal` container per row and three placeholders per row.
 The containers all have a white background, and then:

docs/styles/width.md

@@ -13,6 +13,8 @@ By default, it sets the width of the content area, but if [`box-sizing`](./box_s
 
 ## Examples
 
+### Basic usage
+
 This example adds a widget with 50% width of the screen.
 
 === "width.py"
@@ -32,8 +34,7 @@ This example adds a widget with 50% width of the screen.
     ```{.textual path="docs/examples/styles/width.py"}
     ```
 
----
-
+### All width formats
 
 === "Output"