added escaping to docs

Author: willmcgugan

docs/api/markup.md

@@ -0,0 +1,5 @@
+---
+title: "textual.markup"
+---
+
+::: textual.markup

docs/guide/content.md

@@ -312,6 +312,28 @@ Here's what that looks like:
 ```{.textual path="docs/examples/guide/content/playground.py" lines=16 type="Play the [on $success 30% @click=app.bell]bell[/]"]}
 ```
 
+### Escaping
+
+If you precede an open bracket with a backslash (`\`), then Textual will not consider it to be a tag and the square bracket will be displayed without modification. 
+
+For example, the backslash in the following content prevents the following text from becoming bold, and the text `[bold]` will be in the output.
+
+```{.textual path="docs/examples/guide/content/playground.py" lines=16 type="\[bold]This is not bold"]}
+```
+
+!!! tip "Escaping markup"
+
+    You can also use the [escape][textual.markup.escape] function to escape tags
+
+Some methods, such as [`notify()`][textual.widget.Widget.notify], have a `markup` switch that you can use to disable markup.
+You may want to use this if you want to output a Python repr strings, so that Textual doesn't interpret a list as a tag.
+
+Here's an example:
+
+```python
+# debug code: what is my_list at this point?
+self.notify(repr(my_list), markup=False)
+```
 
 ## Content class
 

mkdocs-nav.yml

@@ -194,6 +194,7 @@ nav:
       - "api/command.md"
       - "api/constants.md"
       - "api/containers.md"
+      - "api/content.md"
       - "api/coordinate.md"
       - "api/dom_node.md"
       - "api/events.md"
@@ -206,6 +207,7 @@ nav:
       - "api/logger.md"
       - "api/logging.md"
       - "api/map_geometry.md"
+      - "api/markup.md"
       - "api/message_pump.md"
       - "api/message.md"
       - "api/on.md"

src/textual/markup.py

@@ -1,3 +1,8 @@
+"""
+Utilities related to content markup.
+
+"""
+
 from __future__ import annotations
 
 from textual.css.parse import substitute_references
@@ -171,7 +176,7 @@ def escape_backslashes(match: Match[str]) -> str:
 
 
 def parse_style(style: str, variables: dict[str, str] | None = None) -> Style:
-    """Parse an encoded style.
+    """Parse a style with substituted variables.
 
     Args:
         style: Style encoded in a string.