MarkdownLabel

A custom Godot node that extends RichTextLabel to use Markdown instead of BBCode.

Compatible with Godot 4.2+. Contains uid files for Godot 4.4+.

Contents

• Disclaimer
• Installation
• Usage
  • Basic syntax
  • Code
  • Headers
  • Links
  • Horizontal rules
  • Images
  • Lists
    • Task list items (checkboxes)
  • Tables
  • Escaping characters
  • Internationalization
  • Advanced usage
• Limitations
  • Unsupported syntax elements
  • Performance
• Acknowledgements

Disclaimer

I created this for my own use and figured out someone else might as well have some use for it. Obviously using BBCode will be better performance-wise since it's natively integrated in Godot. But using Markdown is much easier to write and read, so it can save development time in many cases.

I coded this quickly and without previous knowledge of how to parse Markdown properly, so there might be some inefficiencies and bugs. Please report any unexpected behavior.

I might convert this to C++ code at some point, to improve performance.

Intended use case

This node is very useful for static text that you want to display in your application. It's not recommended to use this for text which is dynamically modified at run time.

My initial use case that lead me to do this was to directly include text from files in my game, such as credits and patch notes, in a format that is easier to mantain for me. This has the added benefit of being able to use the same Markdown files that are displayed in a github repository, instead of having to make two versions of the same text in two different formats.

Installation

From Github:

1. Download the addons folder of this repository
2. Place it in your project's root folder (merge it if you already have an 'addons' folder)
3. Go to Project > Project Settings... > Plugins and enable the MarkdownLabel plugin

From Godot:

1. Go to the AssetLib tab and search for MarkdownLabel
2. Click "Download" and then "Install"
3. Go to Project > Project Settings... > Plugins and enable the MarkdownLabel plugin

You might need to reload the project.

Usage

Simply add a MarkdownLabel to the scene and write its markdown_text field in Markdown format. Alternatively, you can use the display_file method to automatically import the contents of a Markdown file.

In the RichTextLabel properties:

• Do not touch the bbcode_enabled property, since it's automatically set to true by MarkdownLabel to properly format its text. It's hidden from the editor to prevent misusage.
• Editing the text property has the same effect as editing markdown_text. It's hidden from the editor to prevent misusage.
• You can use the rest of its properties as normal.

You can still use BBCode tags that don't have a Markdown equivalent, such as [color=green]underlined text[/color], allowing you to have the full functionality of RichTextLabel with the simplicity and readibility of Markdown.

You can access the in-editor documentation in Godot by going to "Help" > "Search Help" and search for MarkdownLabel.

An example of the node being used to display this Markdown file.

Basic syntax

The basic Markdown syntax works in the standard way:

Markdown text ................ -> BBCode equivalent
-------------------------------||------------------
**Bold** or __bold__ ......... -> [b]Bold[/b] or [b]bold[/b]
*Italics* or _italics_ ....... -> [i]Italics[/i] or [i]italics[/i]
***Nested*** *__emphasis__* .. -> [b][i]Nested[/i][b] [i][b]emphasis[/b][/i]
~~Strike-through~~ ........... -> [s]Strike-through[/s]

Code

You can display code in-line by surrounding text with any number of backticks (`), and you can display code in multiple lines (also called a fenced code block) by placing a line containing just three or more backticks (```) or tildes (~~~) above and below your code block.

Examples:

Markdown text ................. -> BBCode equivalent
--------------------------------||------------------
The following is `in-line code` -> The following is [code]in-line code[/code]
This is also ``in-line code``   -> The is also [code]in-line code[/code]

~~~                  .......... -> [code]
This is a            .......... -> This is a
multiline codeblock  .......... -> multiline codeblock
~~~                  .......... -> [/code]

Important: note that in-line code and code blocks won't do anything with Godot's default font, since it doesn't have a monospace variant. As described in Godot's BBCode reference: "The monospaced ([code]) tag only works if a custom font is set up in the RichTextLabel node's theme overrides. Otherwise, monospaced text will use the regular font".

Headers

MarkdownLabel supports headers, although RichTextLabel doesn't. By default, a line defined as a header will have its font size scaled by a pre-defined amount.

To define a line as a header, begin it with any number of consecutive hash symbols (#) and follow it with the title of your header. The number of hash symbols defines the level of the header. The maximum supported level is six.

Example:

Markdown text:
## This is a second-level header

BBCode equivalent:
[font_size=27]This is a second-level header[/font_size]

where the 27 in [font_size=27] comes from multiplying the set h2.font_size (1.714 by default) by the current normal_font_size (16 by default).

You can optionally set custom sizes and formatting (bold, italics, underline, and color) for each header level individually. To do so:

• In the inspector, open the "Header formats" category, click on the resource associated with the desired header level, and customize the properties there.
• In script, access those properties through the h1, h2, etc. properties. Example: $YourMarkdownLabel.h3.is_italic = true will set all level-3 headers within $YourMarkdownLabel to be displayed as italics.

Note: to change a header level's font color, it's not enough with changing the font_color property: you also have to set its override_font_color property to true.

Of course, you can also use basic formatting within the headers (e.g. ### Header with **bold** and *italic* words).

Links

Links follow the standard Markdown syntax of [text to display](https://example.com). Additionally, you can add tooltips to your links with [text to display](https://example.com "Some tooltip").

"Autolinks" are also supported with their standard syntax: <https://example.com>, and <mail@example.com> for mail autolinks.

Links created this way will be automatically handled by MarkdownLabel, implementing their expected behaviour:

• Valid header anchors (such as the ones in Contents) will make MarkdownLabel scroll to their header's position.
• Valid URLs and emails will be opened according to the user's settings (usually, using their default browser).
• Links that do not match any of the above conditions will be interpreted as a URL by prefixing them with "https://". E.g. [link](example.com) will link to "https://example.com". This can be disabled using the assume_https_links property (enabled by default), in which case the unhandled_link_clicked signal will be emitted.

This behavior can be disabled using the automatic_links property (enabled by default), in which case all links will be left unhandled and the unhandled_link_clicked signal will be emitted for all of them.

The unhandled_link_clicked signal can be used to implement custom behavior when clicking a link. It passes the clicked link metadata (which usually would be the URL) as an argument.

Markdown text ...................................... -> BBCode equivalent
-----------------------------------------------------||------------------
[this is a link](https://example.com) .............. -> [url=https://example.com]this is a link[/url]
[this is a link](https://example.com "Example page") -> [hint=Example url][url=https://example.com]this is a link[/url][/hint]
<https://example.com> .............................. -> [url]https://example.com[/url]
<mail@example.com> ................................. -> [url=mailto:mail@example.com]mail@example.com[/url]

Horizontal rules

Note: this feature is exclusive for Godot 4.5+.

Write a line with just three (or more) matching -, _, or * to form a horizontal rule (also called a thematic break).

You can customize the height, width, alignment, and color of all horizontal rules in the label by modifying its hr_height, hr_width, hr_alignment, and hr_color properties (by default they are 2 px high, 90% wide, center-aligned, and white). If you need to customize these properties individually for each rule, then you can just use the [hr] BBCode tag.

Markdown text  -> BBCode equivalent
---------------||------------------
---            -> [hr height=2 width=90% align=center color=ffffffff]
 ____          -> [hr height=2 width=90% align=center color=ffffffff]
***            -> [hr height=2 width=90% align=center color=ffffffff]

Images

Images use the same syntax as links but preceded by an exclamation mark (!):

Markdown text .............................................. -> BBCode equivalent
-------------------------------------