Links and citations

Follow these guidelines when you add links and citations to your documentation.

tip

For instructions on how to implement this guidance with Markdown, refer to Confluence: Formatting documentation.

Write link text in sentence case, with the first letter capitalized. Use the title of the target page as the link text or a descriptive phrase that makes it clear what information the user can find at the link.

Introduce links with a short phrase to help orient the user to where the link takes them. Don't write "See here," "Click this link to see..." or similarly non-descriptive language. You can use a phrase of the form "For more information about ..., refer to ..."

Learn platform: For current guidance on formatting hyperlinks, refer to Learn platform formatting: Hyperlinks.

Provide each link only once per page, ideally the first time you mention the concept that it's related to.

Links to Unity sources within the Unity documentation

When you link to other areas of the Unity documentation, include the page title as the hyperlink. You can include the link either as part of the sentence, or directly afterward. If the page title doesn't convey the specific topic that you want to link to, then state the topic using the following format: "For more information about <topic>, refer to <[Page title](URL)>

When you link to pages in the Unity Scripting API reference, include the name of the API itself as the link text, in monospaced font.

Link as main part of the sentence	Link after main sentence
Before you can debug shaders on Xbox One, you need to disable shader optimization on the Unity shader files and generate PDBs symbols for them.	Before you can debug shaders, you need to disable shader optimization on the Unity shader files and generate PDBs symbols for them. For more information, refer to Debugging on Xbox One.
Use Animations.AnimatorController to control animation through layers with state machines.	The Animator Controller controls animation through layers with state machines. Refer to Animations.AnimatorController.
You can create and manage placeholder sprites in your project during development using the Sprite Creator.	To test your project during development, you can use temporary placeholder sprites that you later replace with the final graphics. For more information about working with placeholder sprites, refer to Sprite Creator.

Links to sources on the same page

You can use anchor tags to link to a specific part of the same page.

Make sure that you link to a specific section of the page, with a section heading. Use the section heading as the link text or use a descriptive phrase that makes it clear what information the user can find at the link. Don't link to other parts of the page without headings, such as paragraphs or images, because such links can be disorienting for readers.

Links to Unity sources outside the documentation

When you link to Unity sources that are outside the documentation, include the source in the text to make it clear that the link takes the user to a page outside the documentation. Don't include the source name as part of the hyperlink.

Link as main part of the sentence	Link after main sentence
To learn how to use initialization functions, use the Unity Learn tutorial Start MonoBehaviour Methods.	For a tutorial on how to use initialization functions, refer to Start MonoBehaviour Methods (Unity Learn).

Links to external pages

To reduce the burden of ongoing maintenance, link to external documentation only when absolutely necessary. For example, you can link to third-party software or hardware manuals if the user needs to use them to complete a procedure. Make sure that your sources are authoritative and reputable. Don't link to Wikipedia, personal blogs, forum posts, or other sites that aren't official or vetted.

note

You can use Wikipedia as a starting point to find authoritative sources by checking the references section on any given page.

When you link to pages outside the documentation, include the source in the text to make it clear that the link takes the user to an external page.

Link as main part of the sentence	Link after main sentence
This process uses the Microsoft documentation on installing HoloLens.	For more information, refer to HoloLens installation (Microsoft).

Links to downloadable files

Indicate that a file is downloadable in the text, and provide the file name and file extension in the link.

Example download link
This file is available as a downloadable project: MyProject.zip.

URLs

If you need to insert a URL without a link (for example, if you want to display the structure of a URL), enter it in monospaced font on a new line, and make sure it doesn't create a hyperlink.

Example URL formatting
Component reference URLs use the following format: https://docs-redirects.unity.com/<component ID>?version=<Unity version>&section=<section ID>

Citations

Use Chicago-style author-date citations to refer to papers and journals.