Home

Awesome

Markdown UIElement

This package is neither endorsed nor supported by Unity, this is a personal project

This package add rendering of markdown file in Unity by using UIElement.

In Unity 2021.x and 2022.1, this will use reflection to handle links, so it could break in some patch releases if those classes are changed. 2022.2 and above use experimental link tag event and no reflection

It will override the default inspector on .md file and offer a simple API to get a VisualElement root with the markdown as children to add to you own windows and tools.

It also include a special Attribute to display Markdown doc file for a given Monobehaviour and the Markdown implementation handle some special keyword link to simplify link in a Unity Project.

Installation

You can install this package either with :

Note on git method : this will require git to be installed on your machine (e.g. you can run git in your terminal) If you installed git when the Unity editor or Hub was running, the PATH it used won't be updated so close them all completly before. <br/>ON WINDOWS this mean also right click -> quit on the hub icon in the tray icon that may be hidden next to the time/date*

Note and Special Syntax

The Markdown support implementation may miss some bits, so this list some quirks it may have. This also highlight some special keyword/command it has, especially in link, specific to unity.

Relative path

Local path are handled relatively to where the Markdown file is.

so ![Tutorial image](./doc/image.png) will load the image.png that is in the doc folder next to the MD file. The handler look for .. and . at the start of a path to make it relative.

Note that explicit file protocol, file://./doc/image.png will not work as the system won't be able to modify the path to the current folder of the MD file

Absolute path

The system can handle absolute path in the of form of

Assets/Folder/SubFolder/file.png

It can also handle package path (refers to the documentation on accessing packages assets for how those path works). As an example to access this file you would use the path

Packages/com.rtl.markdownrenderer/Readme.md

Search path

A special handler for this Unity implementation is the ![My Image](search:special_doc) link type.

This will search for a file called special_doc in the Assets folder, and will use its path.

Note however that it doesn't support multiple file with the same name and will always return the first found.

Package search path

The package search path works as the Search path but will only search in packages.

package:my_image.png

There is no way to search in a specific packages, this will search in all packages, but will ignore the Assets folder. This is useful to avoid having your package users files found by your search path.

Commands

You can trigger a command through a link. By using the syntax [link text](cmd:cmdName) where cmdName is the name of a command.

This package got a couple of builtin command but you can also write your own.

NOTE : SPACE ARE NOT PERMITTED IN COMMAND, THEY BREAK THE LINK. so [click](cmd:log(this is log) won't work. [click](cmd:save(material,scene)) would work but [click](cmd:save(material, scene)) would NOT work because of the space between , and scene

Built-in Commands

Custom Commands

Register a handler through UIMarkdownRenderer.RegisterCommandHandler which take a delegate with a single parameter of type Command.

A Command contains the CommandName a string that is the command name specified in our link (in our example toolOpen) and an array of string CommandParameters which is parameters you can send to the command

Custom Classes and USS Files

The renderer have the Markdig Extensions for YAML front matter and Generic attributes enabled. This means you can set custom class to elements in your Markdown and give a custom uss file used to render it (in addition to the default ones)

Custom classes

Custom classes are defined using Generic Attribute (see Markdig Generic Attributes documentation for more info).

{.test-class}
This paragraph will have .test-class class assigned to it

{.whole-block}
> ## This is a quote block
> that whole block have the .whole-block class assigned to it
> {.line-class} This line will have .line-class class on it
> 
> Not this line though

As a note for image, you need to place the custom class AFTER THE IMAGE LINE as if you add it before, it will apply it the block before the image

![Image](./path/to/image) {.classToApplyToImage}

Custom USS files

In addition to custom classes on elements in Markdown, you can specify a USS file to be used to render that file.

This use Markdig YAML front matter extension. To speicify the uss add this front matter at the top of your Markdown file

---
uss: ./path/to/file.uss
---

This file will use the file specified in addition to the default USS

Refer to Markdig YAML Front Matter documentation for the format possible but this was tested only with two --- delimiter.

Path can be relative to the Markdown file (using ./ as the start of the path like in the example) or they can be absolute by using a path starting with Assets/ like Assets/Docs/Styles/myStyle.uss

Note: there is no actual YAML parsing, the system only supports uss as a key for now

MarkdownDoc Attribute

The package contains an attribute MarkdownDoc(DocFileName) that can be applied to a Monobehaviour.

If the Markdown Doc Viewer is open (Windows > Markdown Doc View or double clicking on a markdown file) and a Gameobject with a Monobehaviour that have a MarkdownDoc attribute is selected, the doc specified in the attribute will be loaded in the window.

The file is searched by name, so you do not have to put a full path, just the name without extension (e.g. for a doc file that is in Assets/Tools/Docs/MyBehaviourDoc.md the attribute MarkdownDoc("MyBehaviourDoc") will work)

Render Markdown in your own tools

The markdown renderer is using UIElement, so you can embed it in your own tools.

Just call

GenerateVisualElement(string markdownText,  Action<string> LinkHandler, bool includeScrollview = true, string filePath = "")