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 Syntax#

To 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 Template#

If 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 Frontmatter#

All 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:

---
id: installation
title: Installation
---

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.

Headers#

Use 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#

Emphasis#

Emphasis, 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.~~

Lists#

For numbered lists, always start with 1.. The generator will automatically number the list correctly when building the site:

Markdown Ordered List

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.

First ordered list item
Another item
- Unordered sub-list.
Actual numbers don't matter, just that it's a number
1. 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 *.

Links#

See the following example code for Markdown links.

Markdown Link Examples

See [Page Name](filename.md) to link to Markdown site pages.

See [Page Name](filename.md#header-name) to link to a section in the Markdown site pages.

[I'm an inline-style link](https://www.google.com/)

[I'm an inline-style link with title](https://www.google.com/ "Google's Homepage")

[I'm a reference-style link][arbitrary case-insensitive reference text]

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:

Markdown Reference Links

[You can use numbers for reference-style link definitions][1]

Or leave it empty and use the [link text itself].

[1]: http://slashdot.org/
[link text itself]: http://www.reddit.com/

Images#

To include images, save PNG (.png) files to the /static/img folder. Add an image to a markdown file using the following format:

Markdown for displaying images

![alt text](/img/filename.png)

Markdown for website image

[alt text](https://github.com/adam-p/markdown-here/raw/master/src/common/images/icon48.png 'Logo Title Text 1')

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 Mode#

You 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:

import ImageSwitcher from '@site/src/ImageSwitcher.js';

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:

<ImageSwitcher 
lightImageSrc="/img/ping-animation-light.gif?text=LightMode"
darkImageSrc="/img/ping-animation-dark.gif?text=DarkMode"/>

For example:

Tabs#

Use 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:

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

For each set of tabs, use the following code:

<Tabs
  className="unique-tabs"
  defaultValue="tab1"
  values={[
    {label: 'Tab 1', value: 'tab1'},
    {label: 'Tab 2', value: 'tab2'},
  ]}>

<TabItem value="tab1">

Add content here for first tab.

</TabItem>
<TabItem value="tab2">

Add content here for second tab.

</TabItem>
</Tabs>

See the following tabbed code examples:

UNet Example
MLAPI Example

   public class MyUnetClass : NetworkBehaviour
   {
      [SyncVar]
      public float MySyncFloat;
      public void Start()
      {
         if (isClient)
         {
               CmdExample(10f);
         }
         else if (isServer)
         {
               RpcExample(10f);
         }
      }
      [Command]
      public void CmdExample(float x)
      {
         Debug.Log(“Runs on server”);
      }
      [ClientRpc]
      public void RpcExample(float x)
      {
         Debug.Log(“Runs on clients”);
      }
   }

Code#

important

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:

Markdown Inline Example

Use the `npm update` command to check and update packages for Docusaurus.

To add code sample blocks, use three ticks and the programming language. Optionally, you can add a title="name" to describe the example.

Javascript Example

var s = 'JavaScript syntax highlighting';
alert(s);

s = "Python syntax highlighting"
print(s)

To highlight a line of code, add {#} with the line number in the brackets.

Example with line {2} highlighted

function highlightMe() {
  console.log('This line can be highlighted!');
}

Embedding Code from a Repository#

To 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:

src/theme/ReferenceCodeBlock/index.tsx

See full example on GitHub

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.

Tables#

Tables can have one header at the top, with a line indiciting the header and alignment, and rows surrounded by pipes (|).

Markdown Table

| Tables        |      Are      |   Cool |
| ------------- | :-----------: | -----: |
| col 3 is      | right-aligned |  $1600 |
| col 2 is      |   centered    |    $12 |
| zebra stripes |   are neat    |     $1 |

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">

supports up to 5 columns with differing shades.

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

Blockquotes#

Markdown Code

> Blockquotes are very handy in email to emulate reply text. This line is part of the same quote.

Blockquotes 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 Files#

We 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:

import Iframe from 'react-iframe'

Embedding Youtube#

To embed a YouTube, use the following code with a YouTube link:

YouTube Embed

<Iframe url="YOUTUBE LINK HERE"
        width="854px"
        height="480px"
        id="myId"
        className="video-container"
        display="initial"
        position="relative"
        allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" 
        allowfullscreen
        />

Admonitions#

Add an admonition using three colons, the type, and closing content with colons:

Markdown Code

:::note
This is a note.
:::

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 Charts#

Mermaid 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.

Mermaid Example Code

<Mermaid chart={`
    graph LR;
        A-->B;
        B-->C;
        B-->D[Example Label];
`}/>
import Mermaid from '@theme/Mermaid';

graph LR; A-->B; B-->C; B-->D[Example Label];

MDX#

You 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 Files#

Using 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.

## Heading

import Alias from '../shared/_file-name.md';

<Alias/>