From 56e5e39740200494f3dd4784012753364f8e20d4 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Rodrigo=20Gir=C3=A3o=20Serr=C3=A3o?=
 <5621605+rodrigogiraoserrao@users.noreply.github.com>
Date: Wed, 4 Jan 2023 11:26:01 +0000
Subject: [PATCH] Refactor overflow reference.

[skip ci]
---
 docs/styles/overflow.md | 55 ++++++++++++++++++++++++-----------------
 1 file changed, 32 insertions(+), 23 deletions(-)

diff --git a/docs/styles/overflow.md b/docs/styles/overflow.md
index 7b49ec4f1..84a903fd1 100644
--- a/docs/styles/overflow.md
+++ b/docs/styles/overflow.md
@@ -1,35 +1,48 @@
 # Overflow
 
-The `overflow` rule specifies if and when scrollbars should be displayed on the `x` and `y` axis.
-The rule takes two overflow values; one for the horizontal bar (x-axis), followed by the vertical bar (y-axis).
-
-The default value for overflow is `"auto auto"` which will show scrollbars automatically for both scrollbars if content doesn't fit within container.
-
-Overflow may also be set independently by setting the `overflow-x` rule for the horizontal bar, and `overflow-y` for the vertical bar.
+The `overflow` rule specifies if and when scrollbars should be displayed.
 
 ## Syntax
 
-```
-overflow: [auto|hidden|scroll];
-overflow-x: [auto|hidden|scroll];
-overflow-y: [auto|hidden|scroll];
-```
+--8<-- "docs/snippets/syntax_block_start.md"
+overflow: <a href="../../css_types/overflow">&lt;overflow&gt;</a> <a href="../../css_types/overflow">&lt;overflow&gt;</a>;
+
+overflow-x: <a href="../../css_types/overflow">&lt;overflow&gt;</a>;
+overflow-y: <a href="../../css_types/overflow">&lt;overflow&gt;</a>;
+--8<-- "docs/snippets/syntax_block_end.md"
+
+The style `overflow` accepts two values that determine when to display scrollbars in a container widget.
+The two values set the overflow for the horizontal and vertical axes, respectively.
+
+Overflow may also be set individually for each axis:
+
+ - `overflow-x` sets the overflow for the horizontal axis; and
+ - `overflow-y` sets the overflow for the vertical axis.
 
 ### Values
 
-| Value            | Description                                             |
-|------------------|---------------------------------------------------------|
-| `auto` (default) | Automatically show the scrollbar if content doesn't fit |
-| `hidden`         | Never show the scrollbar                                |
-| `scroll`         | Always show the scrollbar                               |
+--8<-- "docs/snippets/type_syntax/overflow.md"
+
+### Defaults
+
+The default setting for containers is `overflow: auto auto`.
+
+!!! warning
+
+    Some built-in containers like `Horizontal` and `Vertical` override these defaults.
 
 ## Example
 
-Here we split the screen in to left and right sections, each with three vertically scrolling widgets that do not fit in to the height of the terminal.
+Here we split the screen into left and right sections, each with three vertically scrolling widgets that do not fit into the height of the terminal.
 
 The left side has `overflow-y: auto` (the default) and will automatically show a scrollbar.
 The right side has `overflow-y: hidden` which will prevent a scrollbar from being shown.
 
+=== "Output"
+
+    ```{.textual path="docs/examples/styles/overflow.py"}
+    ```
+
 === "overflow.py"
 
     ```python
@@ -42,11 +55,6 @@ The right side has `overflow-y: hidden` which will prevent a scrollbar from bein
     --8<-- "docs/examples/styles/overflow.css"
     ```
 
-=== "Output"
-
-    ```{.textual path="docs/examples/styles/overflow.py"}
-    ```
-
 ## CSS
 
 ```sass
@@ -62,11 +70,12 @@ overflow-x: scroll;
 
 ## Python
 
+Overflow cannot be programmatically set for both axes at the same time.
+
 ```python
 # Hide the vertical scrollbar
 widget.styles.overflow_y = "hidden"
 
 # Always show the horizontal scrollbar
 widget.styles.overflow_x = "scroll"
-
 ```