streamlit-nightly 1.33.1.dev20240430__py2.py3-none-any.whl → 1.33.1.dev20240501__py2.py3-none-any.whl

streamlit/commands/page_config.py

@@ -136,22 +136,50 @@ def set_page_config(
     page_title: str or None
         The page title, shown in the browser tab. If None, defaults to the
         filename of the script ("app.py" would show "app • Streamlit").
-    page_icon : Anything supported by st.image or str or None
-        The page favicon.
-        Besides the types supported by `st.image` (like URLs or numpy arrays),
-        you can pass in an emoji as a string ("🦈") or a shortcode (":shark:").
-        If you're feeling lucky, try "random" for a random emoji!
-        Emoji icons are courtesy of Twemoji and loaded from MaxCDN.
+
+    page_icon : Anything supported by st.image, str, or None
+        The page favicon. If ``page_icon`` is ``None`` (default), the favicon
+        will be a monochrome Streamlit logo.
+
+        In addition to the types supported by ``st.image`` (like URLs or numpy
+        arrays), the following strings are valid:
+
+        * A single-character emoji. For example, you can set ``page_icon="🦈"``.
+
+        * An emoji short code. For example, you can set ``page_icon=":shark:"``.
+          For a list of all supported codes, see
+          https://share.streamlit.io/streamlit/emoji-shortcodes.
+
+        * The string literal, ``"random"``. You can set ``page_icon="random"``
+          to set a random emoji from the supported list above. Emoji icons are
+          courtesy of Twemoji and loaded from MaxCDN.
+
+        * An icon from the Material Symbols library (outlined style) in the
+          format ``":material/icon_name:"`` where "icon_name" is the name
+          of the icon in snake case.
+
+          For example, ``icon=":material/thumb_up:"`` will display the
+          Thumb Up icon. Find additional icons in the `Material Symbols \
+          <https://fonts.google.com/icons?icon.set=Material+Symbols&icon.style=Outlined>`_
+          font library.
+
+        .. note::
+            Colors are not supported for Material icons. When you use a
+            Material icon for favicon, it will be black, regardless of browser
+            theme.
+
     layout: "centered" or "wide"
         How the page content should be laid out. Defaults to "centered",
         which constrains the elements into a centered column of fixed width;
         "wide" uses the entire screen.
+
     initial_sidebar_state: "auto", "expanded", or "collapsed"
         How the sidebar should start out. Defaults to "auto",
         which hides the sidebar on small devices and shows it otherwise.
         "expanded" shows the sidebar initially; "collapsed" hides it.
         In most cases, you should just use "auto", otherwise the app will
         look bad when embedded and viewed on mobile.
+
     menu_items: dict
         Configure the menu that appears on the top-right side of this app.
         The keys in this dict denote the menu item you'd like to configure:

streamlit/elements/alert.py

@@ -39,11 +39,22 @@ class AlertMixin:
         ----------
         body : str
             The error text to display.
-        icon : str or None
-            An optional argument that specifies an emoji to use as
-            the icon for the alert. Shortcodes are not allowed, please use a
-            single character instead. E.g. "🚨", "🔥", "🤖", etc.
-            Defaults to None, which means no icon is displayed.
+        icon : str, None
+            An optional emoji or icon to display next to the alert. If ``icon``
+            is ``None`` (default), no icon is displayed. If ``icon`` is a
+            string, the following options are valid:
+
+            * A single-character emoji. For example, you can set ``icon="🚨"``
+              or ``icon="🔥"``. Emoji short codes are not supported.
+
+            * An icon from the Material Symbols library (outlined style) in the
+              format ``":material/icon_name:"`` where "icon_name" is the name
+              of the icon in snake case.
+
+              For example, ``icon=":material/thumb_up:"`` will display the
+              Thumb Up icon. Find additional icons in the `Material Symbols \
+              <https://fonts.google.com/icons?icon.set=Material+Symbols&icon.style=Outlined>`_
+              font library.
 
         Example
         -------
@@ -72,11 +83,22 @@ class AlertMixin:
         ----------
         body : str
             The warning text to display.
-        icon : str or None
-            An optional argument that specifies an emoji to use as
-            the icon for the alert. Shortcodes are not allowed, please use a
-            single character instead. E.g. "🚨", "🔥", "🤖", etc.
-            Defaults to None, which means no icon is displayed.
+        icon : str, None
+            An optional emoji or icon to display next to the alert. If ``icon``
+            is ``None`` (default), no icon is displayed. If ``icon`` is a
+            string, the following options are valid:
+
+            * A single-character emoji. For example, you can set ``icon="🚨"``
+              or ``icon="🔥"``. Emoji short codes are not supported.
+
+            * An icon from the Material Symbols library (outlined style) in the
+              format ``":material/icon_name:"`` where "icon_name" is the name
+              of the icon in snake case.
+
+              For example, ``icon=":material/thumb_up:"`` will display the
+              Thumb Up icon. Find additional icons in the `Material Symbols \
+              <https://fonts.google.com/icons?icon.set=Material+Symbols&icon.style=Outlined>`_
+              font library.
 
         Example
         -------
@@ -104,11 +126,22 @@ class AlertMixin:
         ----------
         body : str
             The info text to display.
-        icon : str or None
-            An optional argument that specifies an emoji to use as
-            the icon for the alert. Shortcodes are not allowed, please use a
-            single character instead. E.g. "🚨", "🔥", "🤖", etc.
-            Defaults to None, which means no icon is displayed.
+        icon : str, None
+            An optional emoji or icon to display next to the alert. If ``icon``
+            is ``None`` (default), no icon is displayed. If ``icon`` is a
+            string, the following options are valid:
+
+            * A single-character emoji. For example, you can set ``icon="🚨"``
+              or ``icon="🔥"``. Emoji short codes are not supported.
+
+            * An icon from the Material Symbols library (outlined style) in the
+              format ``":material/icon_name:"`` where "icon_name" is the name
+              of the icon in snake case.
+
+              For example, ``icon=":material/thumb_up:"`` will display the
+              Thumb Up icon. Find additional icons in the `Material Symbols \
+              <https://fonts.google.com/icons?icon.set=Material+Symbols&icon.style=Outlined>`_
+              font library.
 
         Example
         -------
@@ -137,11 +170,22 @@ class AlertMixin:
         ----------
         body : str
             The success text to display.
-        icon : str or None
-            An optional argument that specifies an emoji to use as
-            the icon for the alert. Shortcodes are not allowed, please use a
-            single character instead. E.g. "🚨", "🔥", "🤖", etc.
-            Defaults to None, which means no icon is displayed.
+        icon : str, None
+            An optional emoji or icon to display next to the alert. If ``icon``
+            is ``None`` (default), no icon is displayed. If ``icon`` is a
+            string, the following options are valid:
+
+            * A single-character emoji. For example, you can set ``icon="🚨"``
+              or ``icon="🔥"``. Emoji short codes are not supported.
+
+            * An icon from the Material Symbols library (outlined style) in the
+              format ``":material/icon_name:"`` where "icon_name" is the name
+              of the icon in snake case.
+
+              For example, ``icon=":material/thumb_up:"`` will display the
+              Thumb Up icon. Find additional icons in the `Material Symbols \
+              <https://fonts.google.com/icons?icon.set=Material+Symbols&icon.style=Outlined>`_
+              font library.
 
         Example
         -------

streamlit/elements/dialog_decorator.py

@@ -94,56 +94,81 @@ def dialog_decorator(title: F | None, *, width: DialogWidth = "small") -> F:
 def dialog_decorator(
     title: F | None | str = "", *, width: DialogWidth = "small"
 ) -> F | Callable[[F], F]:
-    r"""Decorate a function to mark it as a Streamlit dialog. When the decorated function is called, a dialog element is inserted with the function's body as the content.
+    """Function decorator to create a modal dialog.
 
-    The decorated function can hold multiple elements which are rendered inside of a modal when the decorated function is called.
-    The decorated function is using `st.experimental_fragment`, which means that interacting with elements inside of the dialog will
-    only re-run the dialog function.
+    A function decorated with ``@st.experimental_dialog`` becomes a dialog
+    function. When you call a dialog function, Streamlit inserts a modal dialog
+    into your app. Streamlit element commands called within the dialog function
+    render inside the modal dialog.
 
-    The decorated function can accept arguments that can be passed when it is called.
+    The dialog function can accept arguments that can be passed when it is
+    called. Any values from the dialog that need to be accessed from the wider
+    app should generally be stored in Session State.
 
-    Dismissing a dialog does not cause an app re-run.
-    You can close the dialog programmatically by executing `st.rerun()` explicitly inside of the decorated function.
+    A user can dismiss a modal dialog by clicking outside of it, clicking the
+    "**X**" in its upper-right corner, or pressing``ESC`` on their keyboard.
+    Dismissing a modal dialog does not trigger an app rerun. To close the modal
+    dialog programmatically, call ``st.rerun()`` explicitly inside of the
+    dialog function.
 
-    In order to pass state from dialog widgets to the app, you can leverage `st.session_state`.
+    ``st.experimental_dialog`` inherits behavior from |st.experimental_fragment|_.
+    When a user interacts with an input widget created inside a dialog function,
+    Streamlit only reruns the dialog function instead of the full script.
+
+    Calling ``st.sidebar`` in a dialog function is not supported.
+
+    Dialog code can interact with Session State, imported modules, and other
+    Streamlit elements created outside the dialog. Note that these interactions
+    are additive across multiple dialog reruns. You are responsible for
+    handling any side effects of that behavior.
 
     .. warning::
-        Currently, a dialog may not open another dialog.
-        Also, only one dialog-decorated function may be called in a script run, which means that only one dialog can be open at any given time.
+        A dialog may not open another dialog. Only one dialog function may be
+        called in a script run, which means that only one dialog can be open at
+        any given time.
+
+    .. |st.experimental_fragment| replace:: ``st.experimental_fragment``
+    .. _st.experimental_fragment: https://docs.streamlit.io/develop/api-reference/execution-flow/st.fragment
 
     Parameters
     ----------
     title : str
-        A string that will be used as the dialog's title. It cannot be empty.
+        The title to display at the top of the modal dialog. It cannot be empty.
     width : "small", "large"
-        The width of the dialog. Defaults to "small".
-
-    Returns
-    -------
-    A decorated function that, when called, inserts a dialog element context container. The container itself contains the decorated function's elements.
+        The width of the modal dialog. If ``width`` is ``"small`` (default), the
+        modal dialog will be 500 pixels wide. If ``width`` is ``"large"``, the
+        modal dialog will be about 750 pixels wide.
 
     Examples
     --------
-    You can annotate a function to mark it as a Streamlit dialog function and pass arguments to it. You can either dismiss the dialog via the ESC-key or the X-button or close it programmatically and trigger a re-run by using `st.rerun()`.
-    Leverage `st.session_state` if you want to pass dialog widget states to the overall app:
+    The following example demonstrates the basic usage of ``@st.experimental_dialog``.
+    In this app, clicking "**A**" or "**B**" will open a modal dialog and prompt you
+    to enter a reason for your vote. In the modal dialog, click "**Submit**" to record
+    your vote into Session State and rerun the app. This will close the modal dialog
+    since the dialog function is not called during the full-script rerun.
 
     >>> import streamlit as st
     >>>
-    >>> @st.experimental_dialog("Streamlit Example Dialog")
-    >>> def example_dialog(some_arg: str, some_other_arg: int):
-    >>>     st.write(f"You passed following args: {some_arg} | {some_other_arg}")
-    >>>     # interacting with the text_input only re-runs `example_dialog`
-    >>>     some_text_input = st.text_input("Type something:", key="example_dialog_some_text_input")
-    >>>     # following write is updated when chaning the text_input inside the dialog
-    >>>     st.write(f"You wrote '{some_text_input}' in the dialog")
-    >>>     if st.button("Close the dialog"):
+    >>> @st.experimental_dialog("Cast your vote")
+    >>> def vote(item):
+    >>>     st.write(f"Why is {item} your favorite?")
+    >>>     reason = st.text_input("Because...")
+    >>>     if st.button("Submit"):
+    >>>         st.session_state.vote = {"item": item, "reason": reason}
     >>>         st.rerun()
     >>>
-    >>> if st.button("Open dialog"):
-    >>>     example_dialog("Some string arg", 42)
-    >>>
-    >>> # following write is updated with the dialog's text input when the dialog was opened, the text input was interacted with and a re-run was triggered, e.g. by clicking the Close-button defined in `example_dialog`
-    >>> st.write(f"You wrote '{st.session_state.get('example_dialog_some_text_input', '')}' in the dialog")
+    >>> if "vote" not in st.session_state:
+    >>>     st.write("Vote for your favorite")
+    >>>     if st.button("A"):
+    >>>         vote("A")
+    >>>     if st.button("B"):
+    >>>         vote("B")
+    >>> else:
+    >>>     f"You voted for {st.session_state.vote['item']} because {st.session_state.vote['reason']}"
+
+    .. output::
+        https://doc-dialog.streamlit.app/
+        height: 350px
 
     """
 

streamlit/elements/empty.py

@@ -33,12 +33,12 @@ class EmptyMixin:
         several elements at once (using a child multi-element container).
 
         To insert/replace/clear an element on the returned container, you can
-        use "with" notation or just call methods directly on the returned object.
+        use ``with`` notation or just call methods directly on the returned object.
         See examples below.
 
         Examples
         --------
-        Overwriting elements in-place using "with" notation:
+        Overwriting elements in-place using ``with`` notation:
 
         >>> import streamlit as st
         >>> import time
@@ -82,7 +82,7 @@ class EmptyMixin:
         several elements at once (using a child multi-element container).
 
         To insert/replace/clear an element on the returned container, you can
-        use "with" notation or just call methods directly on the returned object.
+        use ``with`` notation or just call methods directly on the returned object.
         See some of the examples below.
 
         This is an internal method and should not be used directly.

streamlit/elements/form.py

@@ -123,7 +123,7 @@ class FormMixin:
         Submit button is pressed, all widget values inside the form will be
         sent to Streamlit in a batch.
 
-        To add elements to a form object, you can use "with" notation
+        To add elements to a form object, you can use ``with`` notation
         (preferred) or just call methods directly on the form. See
         examples below.
 
@@ -157,7 +157,7 @@ class FormMixin:
 
         Examples
         --------
-        Inserting elements using "with" notation:
+        Inserting elements using ``with`` notation:
 
         >>> import streamlit as st
         >>>

streamlit/elements/heading.py

@@ -69,8 +69,10 @@ class HeadingMixin:
 
             * Colored text and background colors for text, using the syntax
               ``:color[text to be colored]`` and ``:color-background[text to be colored]``,
-              respectively — where ``color`` needs to be replaced with any of the following
+              respectively. ``color`` must be replaced with any of the following
               supported colors: blue, green, orange, red, violet, gray/grey, rainbow.
+              For example, you can use ``:orange[your text here]`` or
+              ``:blue-background[your text here]``.
 
         anchor : str or False
             The anchor name of the header that can be accessed with #anchor
@@ -140,8 +142,10 @@ class HeadingMixin:
 
             * Colored text and background colors for text, using the syntax
               ``:color[text to be colored]`` and ``:color-background[text to be colored]``,
-              respectively — where ``color`` needs to be replaced with any of the following
+              respectively. ``color`` must be replaced with any of the following
               supported colors: blue, green, orange, red, violet, gray/grey, rainbow.
+              For example, you can use ``:orange[your text here]`` or
+              ``:blue-background[your text here]``.
 
         anchor : str or False
             The anchor name of the header that can be accessed with #anchor
@@ -213,8 +217,10 @@ class HeadingMixin:
 
             * Colored text and background colors for text, using the syntax
               ``:color[text to be colored]`` and ``:color-background[text to be colored]``,
-              respectively — where ``color`` needs to be replaced with any of the following
+              respectively. ``color`` must be replaced with any of the following
               supported colors: blue, green, orange, red, violet, gray/grey, rainbow.
+              For example, you can use ``:orange[your text here]`` or
+              ``:blue-background[your text here]``.
 
         anchor : str or False
             The anchor name of the header that can be accessed with #anchor

streamlit/elements/layouts.py

@@ -41,7 +41,7 @@ class LayoutsMixin:
         multiple elements. This allows you to, for example, insert multiple
         elements into your app out of order.
 
-        To add elements to the returned container, you can use the "with" notation
+        To add elements to the returned container, you can use the ``with`` notation
         (preferred) or just call methods directly on the returned object. See
         examples below.
 
@@ -67,7 +67,7 @@ class LayoutsMixin:
 
         Examples
         --------
-        Inserting elements using "with" notation:
+        Inserting elements using ``with`` notation:
 
         >>> import streamlit as st
         >>>
@@ -151,7 +151,7 @@ class LayoutsMixin:
         Inserts a number of multi-element containers laid out side-by-side and
         returns a list of container objects.
 
-        To add elements to the returned containers, you can use the "with" notation
+        To add elements to the returned containers, you can use the ``with`` notation
         (preferred) or just call methods directly on the returned object. See
         examples below.
 
@@ -183,7 +183,7 @@ class LayoutsMixin:
 
         Examples
         --------
-        You can use the `with` notation to insert any element into a column:
+        You can use the ``with`` notation to insert any element into a column:
 
         >>> import streamlit as st
         >>>
@@ -277,7 +277,7 @@ class LayoutsMixin:
         Tabs are a navigational element that allows users to easily
         move between groups of related content.
 
-        To add elements to the returned containers, you can use the "with" notation
+        To add elements to the returned containers, you can use the ``with`` notation
         (preferred) or just call methods directly on the returned object. See
         examples below.
 
@@ -305,8 +305,10 @@ class LayoutsMixin:
 
             * Colored text and background colors for text, using the syntax
               ``:color[text to be colored]`` and ``:color-background[text to be colored]``,
-              respectively — where ``color`` needs to be replaced with any of the following
+              respectively. ``color`` must be replaced with any of the following
               supported colors: blue, green, orange, red, violet, gray/grey, rainbow.
+              For example, you can use ``:orange[your text here]`` or
+              ``:blue-background[your text here]``.
 
             Unsupported elements are unwrapped so only their children (text contents) render.
             Display unsupported elements as literal characters by
@@ -319,7 +321,7 @@ class LayoutsMixin:
 
         Examples
         --------
-        You can use the `with` notation to insert any element into a tab:
+        You can use the ``with`` notation to insert any element into a tab:
 
         >>> import streamlit as st
         >>>
@@ -390,7 +392,7 @@ class LayoutsMixin:
         and can be expanded or collapsed by the user. When collapsed, all that is
         visible is the provided label.
 
-        To add elements to the returned container, you can use the "with" notation
+        To add elements to the returned container, you can use the ``with`` notation
         (preferred) or just call methods directly on the returned object. See
         examples below.
 
@@ -416,8 +418,10 @@ class LayoutsMixin:
 
             * Colored text and background colors for text, using the syntax
               ``:color[text to be colored]`` and ``:color-background[text to be colored]``,
-              respectively — where ``color`` needs to be replaced with any of the following
+              respectively. ``color`` must be replaced with any of the following
               supported colors: blue, green, orange, red, violet, gray/grey, rainbow.
+              For example, you can use ``:orange[your text here]`` or
+              ``:blue-background[your text here]``.
 
             Unsupported elements are unwrapped so only their children (text contents) render.
             Display unsupported elements as literal characters by
@@ -428,18 +432,18 @@ class LayoutsMixin:
 
         Examples
         --------
-        You can use the `with` notation to insert any element into an expander
+        You can use the ``with`` notation to insert any element into an expander
 
         >>> import streamlit as st
         >>>
         >>> st.bar_chart({"data": [1, 5, 2, 6, 2, 1]})
         >>>
         >>> with st.expander("See explanation"):
-        ...     st.write(\"\"\"
+        ...     st.write('''
         ...         The chart above shows some numbers I picked for you.
         ...         I rolled actual dice for these, so they're *guaranteed* to
         ...         be random.
-        ...     \"\"\")
+        ...     ''')
         ...     st.image("https://static.streamlit.io/examples/dice.jpg")
 
         .. output ::
@@ -453,11 +457,11 @@ class LayoutsMixin:
         >>> st.bar_chart({"data": [1, 5, 2, 6, 2, 1]})
         >>>
         >>> expander = st.expander("See explanation")
-        >>> expander.write(\"\"\"
+        >>> expander.write('''
         ...     The chart above shows some numbers I picked for you.
         ...     I rolled actual dice for these, so they're *guaranteed* to
         ...     be random.
-        ... \"\"\")
+        ... ''')
         >>> expander.image("https://static.streamlit.io/examples/dice.jpg")
 
         .. output ::
@@ -523,8 +527,10 @@ class LayoutsMixin:
 
             * Colored text and background colors for text, using the syntax
               ``:color[text to be colored]`` and ``:color-background[text to be colored]``,
-              respectively — where ``color`` needs to be replaced with any of the following
+              respectively. ``color`` must be replaced with any of the following
               supported colors: blue, green, orange, red, violet, gray/grey, rainbow.
+              For example, you can use ``:orange[your text here]`` or
+              ``:blue-background[your text here]``.
 
             Unsupported elements are unwrapped so only their children (text contents) render.
             Display unsupported elements as literal characters by
@@ -545,7 +551,7 @@ class LayoutsMixin:
 
         Examples
         --------
-        You can use the `with` notation to insert any element into a popover:
+        You can use the ``with`` notation to insert any element into a popover:
 
         >>> import streamlit as st
         >>>
@@ -609,11 +615,11 @@ class LayoutsMixin:
 
         The label, state, and expanded state can all be updated by calling ``.update()``
         on the returned object. To add elements to the returned container, you can
-        use "with" notation (preferred) or just call methods directly on the returned
+        use ``with`` notation (preferred) or just call methods directly on the returned
         object.
 
         By default, ``st.status()`` initializes in the "running" state. When called using
-        "with" notation, it automatically updates to the "complete" state at the end
+        ``with`` notation, it automatically updates to the "complete" state at the end
         of the "with" block. See examples below for more details.
 
         Parameters
@@ -636,8 +642,10 @@ class LayoutsMixin:
 
             * Colored text and background colors for text, using the syntax
               ``:color[text to be colored]`` and ``:color-background[text to be colored]``,
-              respectively — where ``color`` needs to be replaced with any of the following
+              respectively. ``color`` must be replaced with any of the following
               supported colors: blue, green, orange, red, violet, gray/grey, rainbow.
+              For example, you can use ``:orange[your text here]`` or
+              ``:blue-background[your text here]``.
 
             Unsupported elements are unwrapped so only their children (text contents)
             render. Display unsupported elements as literal characters by
@@ -667,7 +675,7 @@ class LayoutsMixin:
         Examples
         --------
 
-        You can use the `with` notation to insert any element into an status container:
+        You can use the ``with`` notation to insert any element into an status container:
 
         >>> import time
         >>> import streamlit as st
@@ -680,13 +688,13 @@ class LayoutsMixin:
         ...     st.write("Downloading data...")
         ...     time.sleep(1)
         >>>
-        >>> st.button('Rerun')
+        >>> st.button("Rerun")
 
         .. output ::
             https://doc-status.streamlit.app/
             height: 300px
 
-        You can also use `.update()` on the container to change the label, state,
+        You can also use ``.update()`` on the container to change the label, state,
         or expanded state:
 
         >>> import time
@@ -701,7 +709,7 @@ class LayoutsMixin:
         ...     time.sleep(1)
         ...     status.update(label="Download complete!", state="complete", expanded=False)
         >>>
-        >>> st.button('Rerun')
+        >>> st.button("Rerun")
 
         .. output ::
             https://doc-status-update.streamlit.app/

streamlit/elements/lib/column_types.py

@@ -533,7 +533,9 @@ def LinkColumn(
 
         * A regular expression (JS flavor, detected by usage of parentheses)
           to extract a part of the URL via a capture group, e.g. ``"https://(.*?)\\.example\\.com"``
-          to extract the display text "foo" from the URL "https://foo.example.com".
+          to extract the display text "foo" from the URL "\\https://foo.example.com".
+
+        .. Comment: The backslash in front of foo.example.com prevents a hyperlink.
 
         For more complex cases, you may use `Pandas Styler's format \
         <https://pandas.pydata.org/docs/reference/api/pandas.io.formats.style.Styler.format.html>`_

streamlit/elements/markdown.py

@@ -58,8 +58,10 @@ class MarkdownMixin:
 
             * Colored text and background colors for text, using the syntax
               ``:color[text to be colored]`` and ``:color-background[text to be colored]``,
-              respectively — where ``color`` needs to be replaced with any of the following
+              respectively. ``color`` must be replaced with any of the following
               supported colors: blue, green, orange, red, violet, gray/grey, rainbow.
+              For example, you can use ``:orange[your text here]`` or
+              ``:blue-background[your text here]``.
 
         unsafe_allow_html : bool
             By default, any HTML tags found in the body will be escaped and
@@ -82,7 +84,7 @@ class MarkdownMixin:
         >>> st.markdown("*Streamlit* is **really** ***cool***.")
         >>> st.markdown('''
         ...     :red[Streamlit] :orange[can] :green[write] :blue[text] :violet[in]
-        ...     :gray[pretty] :rainbow[colors].''')
+        ...     :gray[pretty] :rainbow[colors] and :blue-background[highlight] text.''')
         >>> st.markdown("Here's a bouquet —\
         ...             :tulip::cherry_blossom::rose::hibiscus::sunflower::blossom:")
         >>>
@@ -95,7 +97,7 @@ class MarkdownMixin:
 
         .. output::
            https://doc-markdown.streamlit.app/
-           height: 260px
+           height: 350px
 
         """
         markdown_proto = MarkdownProto()
@@ -177,8 +179,10 @@ class MarkdownMixin:
 
             * Colored text and background colors for text, using the syntax
               ``:color[text to be colored]`` and ``:color-background[text to be colored]``,
-              respectively — where ``color`` needs to be replaced with any of the following
+              respectively. ``color`` must be replaced with any of the following
               supported colors: blue, green, orange, red, violet, gray/grey, rainbow.
+              For example, you can use ``:orange[your text here]`` or
+              ``:blue-background[your text here]``.
 
         unsafe_allow_html : bool
             By default, any HTML tags found in strings will be escaped and