From 9a28195fd8b2020f919d67fa9d882b131195f5a6 Mon Sep 17 00:00:00 2001
From: Ben Cos <52817096+BenCos17@users.noreply.github.com>
Date: Sun, 1 Sep 2024 23:49:26 +0100
Subject: [PATCH] Add `header`, `hyperlink` and `subtext` utilities (#6102)
 (#19)

Co-authored-by: Kreusada <67752638+Kreusada@users.noreply.github.com>
Co-authored-by: Kowlin <10947836+Kowlin@users.noreply.github.com>
---
 redbot/core/utils/chat_formatting.py | 68 +++++++++++++++++++++++++++-
 1 file changed, 67 insertions(+), 1 deletion(-)

diff --git a/redbot/core/utils/chat_formatting.py b/redbot/core/utils/chat_formatting.py
index b13d869dc02..a65417b298c 100644
--- a/redbot/core/utils/chat_formatting.py
+++ b/redbot/core/utils/chat_formatting.py
@@ -5,7 +5,7 @@
 import math
 import textwrap
 from io import BytesIO
-from typing import Iterator, List, Optional, Sequence, SupportsInt, Union
+from typing import Iterator, List, Literal, Optional, Sequence, SupportsInt, Union
 
 import discord
 from babel.lists import format_list as babel_list
@@ -21,11 +21,14 @@
     "question",
     "bold",
     "box",
+    "header",
+    "hyperlink",
     "inline",
     "italics",
     "spoiler",
     "pagify",
     "strikethrough",
+    "subtext",
     "underline",
     "quote",
     "escape",
@@ -39,6 +42,69 @@
 _ = Translator("UtilsChatFormatting", __file__)
 
 
+def hyperlink(text: str, url: str) -> str:
+    """Create hyperlink markdown with text and a URL.
+
+    Parameters
+    ----------
+    text : str
+        The text which will contain the link.
+    url : str
+        The URL used for the hyperlink.
+
+    Returns
+    -------
+    str
+        The new message.
+
+    """
+    return f"[{text}]({url})"
+
+
+def header(text: str, size: Literal["small", "medium", "large"]) -> str:
+    """Formats a header.
+
+    Parameters
+    ----------
+    text : str
+        The text for the header.
+    url : Literal['small', 'medium', 'large']
+        The size of the header ('small', 'medium' or 'large')
+
+    Returns
+    -------
+    str
+        The new message.
+
+    """
+    if size == "small":
+        multiplier = 3
+    elif size == "medium":
+        multiplier = 2
+    elif size == "large":
+        multiplier = 1
+    else:
+        raise ValueError(f"Invalid size '{size}'")
+    return "#" * multiplier + " " + text
+
+
+def subtext(text: str) -> str:
+    """Formats subtext from the given text.
+
+    Parameters
+    ----------
+    text : str
+        The text to format as subtext.
+
+    Returns
+    -------
+    str
+        The new message.
+
+    """
+    return "-# " + text
+
+
 def error(text: str) -> str:
     """Get text prefixed with an error emoji.