Working with Markdown

This guide gives a tour of files, Markdown conventions, and more to contribute.

Tools

We use the following tools:

• The documentation site uses Docusaurus V2, built on React, Remark, NodeJS, and various other tech. See package.json for full plugin details.
• Search will use Algolia.
• Admonitions (notes, warnings, etc) are formatted using Remark-Admonitions.

The Unity documentation team can respond to requests for custom panels, page layouts, styles, plugins, and more. Open a feature request with details.

About Doc Files

Learn more about the doc site structure:

• All Markdown (.md) files are saved in /docs. Content files may be saved to specific folders per group, feature, etc.
• All images files (.png) are saved in /static/img and included in markdown using this format: ![alt text](/img/filename.png)

Creating Markdown Files

1. Open your editor and the files for the GitHub repo. You should see your branch name in the bottom bar.
2. Locate the docs folder. You can add your file in the main docs folder or select an existing folder that best represents content. For example, we may have content moved into a folder structure per feature/product.
3. Add a name file to the folder with a name.md. This will create an empty markdown file.

Template

See template.md for example Markdown, conventions, and more! You can view how this page looks when building locally at localhost:3000/docs/template/

Formatting Markdown

Use H2 through H5 for headings. H1 is used for the page title. Use * for bullets. Use 1. for all numbered lists. Generation will automatically generate the numbered list.

Frontmatter

Every Markdown file must have frontmatter, at the beginning of every file. The following content is required:

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

Field	Description
id:	Quick name for topics, used for linking into side navigation (sidebars.js file)
title:	Name of the page, displays as the H1 on the generated page.

You can also use the following fields as needed:

Field	Description
keywords:	Adds keyword metatags for search engines
description:	Metadata description for the page for search engines. By default, search engines will pull the first X amount of words if a description is not included.
sidebar_label:	Shorter name for the side nav for the page, if the title is very long this can help for viewing and formatting
hide_table_of_contents:	Great option to use for a page without headings, like a table of features or landing for other content

Admonitions

These are panels including note, tip, important, caution, warning, and contribution. You can add general content, bold, italics, bullets, and code in these panels.

Use the following code to use these options:

:::note

This is a note

:::

Sidebar Navigation

This can be a bit complicated. The Unity tech writing team can help! We can add new content to the navigation through your PRs, asking you for information and recommendations as needed.

1. Determine where in the list of files you want to have the page display. Also decide if this is a single link outside of a section, or start of a new section, etc.
2. Open sidebars.js in the root.
3. To add a page into an existing section, locate in the navigation where you want to add the page. Pages include a folder and id.
4. For this example, you may want to add an introduction to Advanced Topics. You would add it to the top of that section. Add a new line, add the directory name (advanced-topics) and topic id (introduction), matching this formatting. See the following example:

{
      "collapsed": true,
      "type": "category",
      "label": "Advanced Topics",
      "items": [
        {
          "type": "doc",
          "id": "advanced-topics/introduction"
        },
        {
          "type": "doc",
          "id": "advanced-topics/message-encryption"
        },
        {
          "type": "doc",
          "id": "advanced-topics/message-encryption"
        },
        ...
      ]
    },

Add New Section in Side Nav

To add a new section with two topics, locate where in the list you want the pages to display. Sections include a category name (not linked to any page), open brackets like an array, and a list of folder/ids. This format defaults to type doc for a markdown file.

For this example, we add a Tutorials section with two new tutorials after Advanced Topics. The folder name is tutorials. You want to include a category name with an array of page IDs. The category cannot have a linked topic. See the following example:

{
      "collapsed": true,
      "type": "category",
      "label": "Tutorials",
      "items": [
        {
          "type": "doc",
          "id": "tutorials/multipie"
        },
        {
          "type": "doc",
          "id": "tutorials/write-tests"
        },
},

Add Single Markdown Page to Side Nav

To add a link to a single markdown page without a category, use the following format. For example, adding a glossary:

{
        "type": "doc",
        "id": "reference/glossary",
};

Adding Links to Side Nav

To add a link to a website outside of the docs, use this format:

{
        "type": "link",
        "label": "string",
        "href": "string",
};