Working with Markdown
Note: This content is not actively maintained. If you'd like us to maintain these guides, let us know by opening an issue.
This guide gives a tour of files, Markdown conventions, and more to contribute.
The easiest way to work with Markdown is a template. We have a general Markdown Template as a guide: generated output and sample Markdown code.
Coming Soon! Templates for content (April 2021) Use quick templates to start a general page or a tutorial for Learn. We're working to make submissions easier.
We use the following tools:
- The documentation site uses Docusaurus V2, built on React, Remark, NodeJS, and various other tech.
- Search uses Algolia.
We can respond to requests for custom panels, page layouts, styles, plugins, and more. Open a feature request or ask on Discord #documentation channel.
Need a quick and easy way to write? Just copy the markdown content from this template file.
Paste it into a new file, and write!
All previews of templates are on the site.
Learn more about the doc site structure:
- All Markdown (.md) files are saved in the folder based on versioning.
- All general images files (.png) are saved in /static/img and included in markdown using this format:
If you have a screenshot or image for a specific version, add the image in that versioned_docs folder.
- Open your editor and the files for the GitHub repo. You should see your branch name in the bottom bar.
- 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.
- Add a name file to the folder with a
name.md. This will create an empty markdown file. - Add frontmatter. This sets the name of the page, the id used for navigation, and additional metadata as needed. See Frontmatter below.
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: |
Page name, 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 |
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.
For numbered lists, always start with 1.. The generator will automatically number the list correctly when building the site:
Example ordered list:
1. First ordered list item
1. Another item
- Unordered sub-list.
1. Actual numbers don't matter, just that it's a number
1. Ordered sub-list
1. And another item.
For bulleted lists, use asterisks *.
See the following example code for Markdown links. When linking to Markdown files, use absolute links to the markdown file name.
[I'm an inline-style link](https://www.google.com/)
See [Page Name](filename.md) to link to Markdown site pages.
You can include inline commands and code using single ticks:
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.
You can also embed code samples for a file in a public GitHub repo. 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. For example with a JavaScript file: ```js reference. 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`.
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
:::If you need to add images to pages, save files as the following:
- Save files in .png format with a clear name. Do not make names extremely long!
- Make sure the images look good on light and dark themes.
- Save image files to the /static/imgs directory in the repo. If you save an image in different languages, make sure to add the 2 letter code for the language in the file name. For example -es.png for Spanish.
- All images are linked from the /img folder. You do not need to include static in the link.
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 chart={`
graph LR;
A-->B;
B-->C;
B-->D[Example Label];
`}/>
import Mermaid from '@theme/Mermaid';
Doc Team will help! 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.
Versioning: These instructions will greatly change with versioning.
- 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.
- Open
sidebars.jsin the root. - 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.
- 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:
Example:
- The
typeis best to putdocfor a Markdown page. - The
idis the folder in /docs, ending with the frontmatterid. For example: in the folder advanced-topics you will find a file with the id message-encryption. This also becomes the canonical URL. - The title of the page is controlled in the Markdown file, not the sidebars file.
{
"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"
},
...
]
},
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/awesome-feature"
},
{
"type": "doc",
"id": "tutorials/write-tests"
},
},
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",
};
To add a link to a website outside of the docs, use this format:
{
"type": "link",
"label": "string",
"href": "string",
};