Skip to content

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.

MarkdownExampleApp ▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁ Markdown Document ▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔ This is an example of Textual's Markdown widget. ▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁                               Features                               ▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔ Markdown syntax and extensions are supported. ● Typography emphasisstronginline code etc. ● Headers ● Lists (bullet and ordered) ● Syntax highlighted code blocks ● Tables!

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


textual.widgets.Markdown class

def __init__(
    self,
    markdown=None,
    *,
    name=None,
    id=None,
    classes=None,
    parser_factory=None
):

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, a "gfm-like" parser is used.

None

COMPONENT_CLASSES class-attribute instance-attribute

COMPONENT_CLASSES = {'em', 'strong', 's', 'code_inline'}

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

def __init__(self, markdown, href):

Bases: Message

A link in the document was clicked.

control property

control: Markdown

The Markdown widget containing the link clicked.

This is an alias for LinkClicked.markdown and is used by the on decorator.

href instance-attribute

href: str = href

The link that was selected.

markdown instance-attribute

markdown: Markdown = markdown

The Markdown widget containing the link clicked.

TableOfContentsSelected class

def __init__(self, markdown, block_id):

Bases: Message

An item in the TOC was selected.

block_id instance-attribute

block_id: str = block_id

ID of the block that was selected.

control property

control: Markdown

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

markdown: Markdown = markdown

The Markdown widget where the selected item is.

TableOfContentsUpdated class

def __init__(self, markdown, table_of_contents):

Bases: Message

The table of contents was updated.

control property

control: Markdown

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

markdown: Markdown = markdown

The Markdown widget associated with the table of contents.

table_of_contents instance-attribute

table_of_contents: TableOfContentsType = table_of_contents

Table of contents.

goto_anchor method

def goto_anchor(self, anchor):

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

def load(self, path):

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

def sanitize_location(location):

Given a location, break out the path and any anchor.

Parameters
Name Type Description Default
location str

The location to sanitize.

required
Returns
Type Description
Path

A tuple of the path to the location cleaned of any anchor, plus

str

the anchor (or an empty string if none was found).

unhandled_token method

def unhandled_token(self, token):

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 None.

update method

def update(self, markdown):

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.