Merge branch 'main' into promote-disabled

docs/api/markdown.md

@@ -0,0 +1 @@
+::: textual.widgets.Markdown

docs/api/markdown_viewer.md

@@ -0,0 +1 @@
+::: textual.widgets.MarkdownViewer

docs/examples/widgets/markdown.py

@@ -0,0 +1,28 @@
+from textual.app import App, ComposeResult
+from textual.widgets import Markdown
+
+EXAMPLE_MARKDOWN = """\
+# Markdown Document
+
+This is an example of Textual's `Markdown` widget.
+
+## Features
+
+Markdown syntax and extensions are supported.
+
+- Typography *emphasis*, **strong**, `inline code` etc.
+- Headers
+- Lists (bullet and ordered)
+- Syntax highlighted code blocks
+- Tables!
+"""
+
+
+class MarkdownExampleApp(App):
+    def compose(self) -> ComposeResult:
+        yield Markdown(EXAMPLE_MARKDOWN)
+
+
+if __name__ == "__main__":
+    app = MarkdownExampleApp()
+    app.run()

docs/examples/widgets/markdown_viewer.py

@@ -0,0 +1,60 @@
+from textual.app import App, ComposeResult
+from textual.widgets import MarkdownViewer
+
+EXAMPLE_MARKDOWN = """\
+# Markdown Viewer
+
+This is an example of Textual's `MarkdownViewer` widget.
+
+
+## Features
+
+Markdown syntax and extensions are supported.
+
+- Typography *emphasis*, **strong**, `inline code` etc.
+- Headers
+- Lists (bullet and ordered)
+- Syntax highlighted code blocks
+- Tables!
+
+## Tables
+
+Tables are displayed in a DataTable widget.
+
+| Name            | Type   | Default | Description                        |
+| --------------- | ------ | ------- | ---------------------------------- |
+| `show_header`   | `bool` | `True`  | Show the table header              |
+| `fixed_rows`    | `int`  | `0`     | Number of fixed rows               |
+| `fixed_columns` | `int`  | `0`     | Number of fixed columns            |
+| `zebra_stripes` | `bool` | `False` | Display alternating colors on rows |
+| `header_height` | `int`  | `1`     | Height of header row               |
+| `show_cursor`   | `bool` | `True`  | Show a cell cursor                 |
+
+
+## Code Blocks
+
+Code blocks are syntax highlighted, with guidelines.
+
+```python
+class ListViewExample(App):
+    def compose(self) -> ComposeResult:
+        yield ListView(
+            ListItem(Label("One")),
+            ListItem(Label("Two")),
+            ListItem(Label("Three")),
+        )
+        yield Footer()
+```
+
+
+"""
+
+
+class MarkdownExampleApp(App):
+    def compose(self) -> ComposeResult:
+        yield MarkdownViewer(EXAMPLE_MARKDOWN, show_table_of_contents=True)
+
+
+if __name__ == "__main__":
+    app = MarkdownExampleApp()
+    app.run()

docs/widgets/markdown.md

@@ -0,0 +1,40 @@
+# Markdown
+
+A widget to display a Markdown document.
+
+- [x] Focusable
+- [ ] Container
+
+
+!!! tip
+
+    See [MarkdownViewer](./markdown_viewer.md) for a widget that adds additional features such as a Table of Contents.
+
+## Example
+
+The following example displays Markdown from a string.
+
+=== "Output"
+
+    ```{.textual path="docs/examples/widgets/markdown.py"}
+    ```
+
+=== "markdown.py"
+
+    ~~~python
+    --8<-- "docs/examples/widgets/markdown.py"
+    ~~~
+
+## Messages
+
+### ::: textual.widgets.Markdown.TableOfContentsUpdated
+
+### ::: textual.widgets.Markdown.TableOfContentsSelected
+
+### ::: textual.widgets.Markdown.LinkClicked
+
+
+## See Also
+
+* [Markdown][textual.widgets.Markdown] code reference
+* [MarkdownViewer][textual.widgets.MarkdownViewer] code reference

docs/widgets/markdown_viewer.md

@@ -0,0 +1,37 @@
+# Markdown Viewer
+
+A Widget to display Markdown content with an optional Table of Contents.
+
+- [x] Focusable
+- [ ] Container
+
+!!! note
+
+    This Widget adds browser-like functionality on top of the [Markdown](./markdown.md) widget.
+
+
+## Example
+
+The following example displays Markdown from a string and a Table of Contents.
+
+=== "Output"
+
+    ```{.textual path="docs/examples/widgets/markdown_viewer.py" columns="100" lines="42"}
+    ```
+
+=== "markdown.py"
+
+    ~~~python
+    --8<-- "docs/examples/widgets/markdown_viewer.py"
+    ~~~
+
+## Reactive Attributes
+
+| Name                     | Type | Default | Description                                                       |
+| ------------------------ | ---- | ------- | ----------------------------------------------------------------- |
+| `show_table_of_contents` | bool | True    | Wether a Table of Contents should be displayed with the Markdown. |
+
+## See Also
+
+* [MarkdownViewer][textual.widgets.MarkdownViewer] code reference
+* [Markdown][textual.widgets.Markdown] code reference