Markdown¶
Added in version 0.11.0
A widget to display a Markdown document.
- Focusable
- Container
Tip
See MarkdownViewer for a widget that adds additional features such as a Table of Contents.
Example¶
The following example displays Markdown from a string.
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()
Reactive Attributes¶
This widget has no reactive attributes.
Messages¶
Bindings¶
This widget has no bindings.
Component Classes¶
The markdown widget provides the following component classes:
These component classes target standard inline markdown styles. Changing these will potentially break the standard markdown formatting.
Class | Description |
---|---|
code_inline |
Target text that is styled as inline code. |
em |
Target text that is emphasized inline. |
s |
Target text that is styled inline with strykethrough. |
strong |
Target text that is styled inline with strong. |
See Also¶
- MarkdownViewer code reference
textual.widgets.Markdown
class
¶
Bases: Widget
Parameters
Name | Type | Description | Default |
---|---|---|---|
markdown |
str | None
|
String containing Markdown or None to leave blank for now. |
None
|
name |
str | None
|
The name of the widget. |
None
|
id |
str | None
|
The ID of the widget in the DOM. |
None
|
classes |
str | None
|
The CSS classes of the widget. |
None
|
parser_factory |
Callable[[], MarkdownIt] | None
|
A factory function to return a configured MarkdownIt instance. If |
None
|
COMPONENT_CLASSES
class-attribute
instance-attribute
¶
These component classes target standard inline markdown styles. Changing these will potentially break the standard markdown formatting.
Class | Description |
---|---|
code_inline |
Target text that is styled as inline code. |
em |
Target text that is emphasized inline. |
s |
Target text that is styled inline with strykethrough. |
strong |
Target text that is styled inline with strong. |
LinkClicked
class
¶
Bases: Message
A link in the document was clicked.
control
property
¶
The Markdown
widget containing the link clicked.
This is an alias for LinkClicked.markdown
and is used by the on
decorator.
markdown
instance-attribute
¶
The Markdown
widget containing the link clicked.
TableOfContentsSelected
class
¶
Bases: Message
An item in the TOC was selected.
control
property
¶
The Markdown
widget where the selected item is.
This is an alias for TableOfContentsSelected.markdown
and is used by the on
decorator.
markdown
instance-attribute
¶
The Markdown
widget where the selected item is.
TableOfContentsUpdated
class
¶
Bases: Message
The table of contents was updated.
control
property
¶
The Markdown
widget associated with the table of contents.
This is an alias for TableOfContentsUpdated.markdown
and is used by the on
decorator.
markdown
instance-attribute
¶
The Markdown
widget associated with the table of contents.
table_of_contents
instance-attribute
¶
Table of contents.
goto_anchor
method
¶
Try and find the given anchor in the current document.
Parameters
Name | Type | Description | Default |
---|---|---|---|
anchor |
str
|
The anchor to try and find. |
required |
Note
The anchor is found by looking at all of the headings in the document and finding the first one whose slug matches the anchor.
Note that the slugging method used is similar to that found on GitHub.
Returns
Type | Description |
---|---|
bool
|
True when the anchor was found in the current document, False otherwise. |
load
async
¶
Load a new Markdown document.
Parameters
Name | Type | Description | Default |
---|---|---|---|
path |
Path
|
Path to the document. |
required |
Raises
Type | Description |
---|---|
OSError
|
If there was some form of error loading the document. |
Note
The exceptions that can be raised by this method are all of
those that can be raised by calling Path.read_text
.
sanitize_location
staticmethod
¶
unhandled_token
method
¶
Process an unhandled token.
Parameters
Name | Type | Description | Default |
---|---|---|---|
token |
Token
|
The token to handle. |
required |
Returns
Type | Description |
---|---|
MarkdownBlock | None
|
Either a widget to be added to the output, or |
update
method
¶
Update the document with new Markdown.
Parameters
Name | Type | Description | Default |
---|---|---|---|
markdown |
str
|
A string containing Markdown. |
required |
Returns
Type | Description |
---|---|
AwaitMount
|
An optionally awaitable object. Await this to ensure that all children have been mounted. |