Markdown Guide and Code
This guide details how to use Markdown and custom features available for this site. You can review Markdown code in this GitHub file or in local cloned files in the /reference/template.md file. You can write content using GitHub-flavored Markdown syntax. See the Contributions Guide for details on creating and updating documentation.
#
Markdown SyntaxTo serve as an example page when styling markdown based Docusaurus sites.
About File Names
The doc site requires all file names in lowercase, no spaces, with dashes used as needed. This includes Markdown, images, videos, and downloadable files.
#
Simple TemplateIf you need a simple template to start a new page, see the /reference/templates/markdown.md file in your local cloned files. This file gives you simple Markdown to get started. For more Markdown formats, see this page's code.
#
Markdown FrontmatterAll Markdown files require some information at the top of every file indicating the title, id, and other attributes as needed.
Copy, paste, and fill out the following in the first lines of your Markdown file:
See the following options for frontmatter fields:
Frontmatter Fields | Description |
---|---|
id: | Used for the navigation. Recommend only using lowercase and dashes. |
title: | Displays as the page name and as the H1. |
description: | Metadata description for the page for search engines. By default, search engines will pull the first X amount of words from the page as a description. |
sidebar_label: | Shorter name for the side nav for the page, if the title is very long this can help for viewing and formatting. |
#
HeadersUse hashtags #
to indicate the heading level. You should not use H1, this is automatically used for the page title when building the site. Link anchors automatically also generate.
#
H2 - Create the best documentation#
H3 - Create the best documentation#
H4 - Create the best documentation#
H5 - Create the best documentation#
H6 - Create the best documentation#
EmphasisEmphasis, aka italics, with asterisks or underscores.
Strong emphasis, aka bold, with asterisks or underscores.
Combined emphasis with asterisks and underscores.
Strikethrough uses two tildes. Scratch this.
#
ListsFor numbered lists, always start with 1.
. The generator will automatically number the list correctly when building the site:
- First ordered list item
- Another item
- Unordered sub-list.
- Actual numbers don't matter, just that it's a number
- Ordered sub-list
- And another item.
- Use asterisks
*
for unordered lists.
You can configure your editor to always use this format for lists. For Visual Studio Code, configure the following settings:
- Ordered List: Marker set to one.
- Unordered List: Marker set to *.
#
LinksSee the following example code for Markdown links.
URLs and URLs in angle brackets will automatically get turned into links. http://www.example.com/ or http://www.example.com/ and sometimes example.com (but not on GitHub, for example).
Some text to show that the reference links can be added at the bottom:
#
ImagesTo include images, save PNG (.png) files to the /static/img
folder. Add an image to a markdown file using the following format:
See the following examples:
Inline-style: alt text
Reference-style: alt text
Images from any folder can be used by providing path to file. Path should be relative to markdown file.
#
Images for Dark and Light ModeYou can save diagrams, animations, and images for dark and light mode to provide the best look for all users.
At the bottom of your markdown file, add this code:
note
Depending on the location of your Markdown file, you may need more or less ../
.
Save your light image with a background color of white (#ffffff
) or charcoal (#18191a
). Save your images to the /static/img folder and add the image using the following code:
For example:

#
TabsUse the following code to create tabbed content. You can use Markdown in these tabs, including text, code content, images, and more.
At the bottom of the Markdown file, add the following code:
For each set of tabs, use the following code:
See the following tabbed code examples:
- UNet Example
- MLAPI Example
#
Codeimportant
All code samples should meet coding standard guidelines and requirements for Unity. They should be tested, functioning, and provide live examples that developers can reuse easily.
To add code inline, use single ticks:
To add code sample blocks, use three ticks and the programming language. Optionally, you can add a title="name"
to describe the example.
To highlight a line of code, add {#}
with the line number in the brackets.
#
Embedding Code from a RepositoryTo embed a code sample from a file in a GitHub repositiory, use reference
in the code block with a link to the file. The code sample is embedded using the language with a link to the original file.
This code references a JavaScript file: ```js reference
, for example:
You can use a link to a file embedding the entire file, or embed a range of code lines using #L
and a line range at the end of the link, such as #L105-108
.
#
TablesTables can have one header at the top, with a line indiciting the header and alignment, and rows surrounded by pipes (|).
Tables | Are | Cool |
---|---|---|
col 3 is | right-aligned | $1600 |
col 2 is | centered | $12 |
zebra stripes | are neat | $1 |
There must be at least 3 dashes separating each header cell. You can also use inline Markdown.
Markdown | Less | Pretty |
---|---|---|
Still | renders | nicely |
1 | 2 | 3 |
Custom styles are available for tables, added using <div>
tags around the markdown table.
<div class="table-rows">
Tables | Are | Cool | Check | It | Out |
---|---|---|---|---|---|
col 3 is | right-aligned | $1600 | $1 | .003 | finals |
col 2 is | centered | $12 | |||
zebra stripes | are neat | $1 |
<div class="table-columns">
supports up to 5 columns with differing shades and highlights a column on hover.
Tables | Are | Cool | Check | It | Out |
---|---|---|---|---|---|
col 3 is | right-aligned | $1600 | $1 | .003 | finals |
col 2 is | centered | $12 | |||
zebra stripes | are neat | $1 |
#
BlockquotesBlockquotes are very handy in email to emulate reply text. This line is part of the same quote.
Quote break.
This is a very long line that will still be quoted properly when it wraps. Oh boy let's keep writing to make sure this is long enough to actually wrap for everyone. Oh, you can put Markdown into a blockquote.
#
Embed FilesWe support embedding using the react-iframe plugin. You can use this feature for YouTube videos, Google Slides and Docs, and much more.
Add the following code once in the Markdown file:
#
Embedding YoutubeTo embed a YouTube, use the following code with a YouTube link:
#
AdmonitionsAdd an admonition using three colons, the type, and closing content with colons:
note
This is a note.
tip
This is a tip.
important
This is important.
caution
This is a caution.
warning
This is a warning.
Community Contribution
Thank you to Unity for this tutorial! This contribution is a great help to the community.
Fun Fact
Use for helpful facts and info.
Best Practice
Highlight best practices and recommendations.
unity
Information specific to Unity, for example license information.
#
Mermaid ChartsMermaid provides sequence diagrams, charts, and more. Use these charts to detail processes, workflows, inheritance, and more. See the Mermaid guide for specifics and examples, and use the live editor to generate code.
See the following example code for adding Mermaid charts. You need to include the import line once per page.
#
MDXYou can write JSX and use React components within your Markdown thanks to MDX.
Docusaurus green and Facebook blue are my favorite colors.I can write Markdown alongside my JSX!
#
Import Markdown FilesUsing MDX, you can create markdown files with a section of content that can be imported to multiple files. For example, you may have the same notation or install instructions across multiple files.
Save your files with a file name starting with an underscore (_) in a shared folder (available in each version folder). These files will be included in generated versions.
Currently, any headings will not build in the on-page navigation (on the right). You can add a heading to the page then import the file.
Use the following code with an absolute path to the shared folder file.