External Links
The Doc Tools package supports uid-based markdown cross-reference syntaxes to make links to the Unity Manual, Script Reference, and dependent packages:
<xref:uid>
[displayed text](xref:uid)
Where uid
is a unique ID that is defined as follows:
- For the Unity manual, use the page name (without the .html) — the link text is the page title by default.
- For package manual files, the uid must be assigned at the top of the markdown page you are linking to.
- For both Unity Script Reference and for package classes, use the full qualified class name — the link text is the unqualified type name.
Note that you can use these same cross-reference syntaxes within the current package and to dependent packages. These types of cross references are not supported for links to arbitrary packages.
Links directly to class constructors are not currently supported for links to the Unity Script Reference, but you can use them for package classes.
When to use UIDs for links
Besides saving typing and clutter in your markdown text, links created this way link to a specific version of Unity or a dependent package without having to specify a version in the link text. That means when your package is updated to use a newer version of Unity or a dependent package, you don’t have to manually change the links before publishing the new docs AND the docs for the old version still link to the correct, older versions of Unity and dependent packages even though the versionless URLs for those things has moved on.
If you want a link to the latest version of the Unity docs, no matter what version of Unity that has become, continue to use a normal href-based link, such as Unity Manual
Assigning a UID to a markdown page
To assign a UID to a markdown file, place the following YAML snippet as the first few lines of the file:
---
uid: your-uid-name
---
Replacing your-uid-name
with the uid you want to use. UIDs must be unique in a project. As a convention, use dashes to separate words.
Links to non-dependant packages
You can add xrefs to other packages by including the package name or URLs to their xrefmap files in the projectMetadata.json file. You can use:
- A full, absolute URL, such as "https://docs.unity3d.com/Packages/com.unity.addressables@1.19/xrefmap.yml". Note that the
@latest
version of the package URL does not work here (because that isn't really a URL, its a JavaScript hack!). You must specify a version. - A package name, with version, such as "com.unity.xr.compositionlayers@0.1".
- A package name without version, such as "com.unity.timeline". In this case, we try to find the latest public version.
Here's an example link to the latest Addressables topic, Using Addressables at runtime created with [Using Addressables at runtime](xref:addressable-runtime)
, where addressable-runtime
is a uid in the Addressables package docs. This package adds the addressables doc links using the full, absolute version of the URL.
Links to the Core Unity documentation
See the following pages for a list of the UIDs to use for linking to the core Unity documentation:
- Links to Unity Manual
- Links to Core Script Reference -- UnityEditor namespace
- Links to Core Script Reference -- UnityEngine namespace
Important
These pages are complete and accurate for the version of Unity used to generate the page you are now reading (see Links to Unity Manual) at the time the xrefmaps were last updated -- which is a manual process. You can find the xrefmap files used to make links to the Unity core docs in the Package Manager Doc Tools package source (inside the .docgen/docfx_packages
folder). These xrefmap files are generated using the Python scripts in the UnityDocTools repo.
Also note that these files have been purged of NDA-restricted strings, even where those strings don't refer to the NDA item. Thus if you are looking for an item using one of those strings, you might not find it (e.g. the name of the thing commonly used to turn lights on or off is one such string).
Testing links
Sometimes, if you are working on a set of packages that have not been released or their docs haven't been published yet, the Doc Tools will report bad links from one package to another simply because it requires the target package docs to already exist at an accessible web site. When package docs are published, they must be published in the correct order for the links to work. That is, if package A depends on package B, the docs for B must be published and pushed live before the docs for A are generated. When generating docs for local testing before release, this isn't possible, of course. To solve this conundrum, you can build the docs for any unpublished packages you need to link to and host them on a localhost web server. If the Doc Tools can't find the requested version at the usual place on the web, it checks for the xrefmap on localhost. You can use this for any packages in the manifests of the package you are generating the docs for and also for any packages that you added to the projectMetaData.json file as additional xrefs. In this latter case, you must use the package.id@x.y form of the xref.
Python offers an easy way to run a localhost web server. Assuming you can run Python from a command prompt, you can use the following (on Windows, Mac and Linux should be similar):
pushd "d:\docs"
start chrome localhost
python -m http.server 80
popd
Change "d:\docs" to the directory at which you generate the docs (there's an "Output path" field for the Doc Tools in the Package Manager window -- use the same value).
Examples:
Links to Unity manual:
* [A Unity Manual](xref:UnityManual)
* [](xref:UnityManual)
* <xref:UnityManual>
* <xref:ScriptCompilationAssemblyDefinitionFiles>
* @UnityManual
* @ScriptCompilationAssemblyDefinitionFiles
* @"UnityManual?text=Da Manual"
* @class-MeshRenderer#Lighting
* @"class-MeshRenderer?text=Lighting#Lighting"
- A Unity Manual
- Unity User Manual 2021.3 (LTS)
- Unity User Manual 2021.3 (LTS)
- Assembly definitions
- Unity User Manual 2021.3 (LTS)
- Assembly definitions
- Da Manual
- Mesh Renderer component -- Note the link text is the Page title, not the heading title. You must use
?text=title
here: - Lighting
Links to the Unity Script Reference
* <xref:UnityEngine.MonoBehaviour>
* <xref:Unity.Jobs.JobHandle>
* @"Unity.Jobs.JobHandle?text=JobFoo"
Caveats and limitations
A caveat to the newly supported link syntaxes is that xref:uid’s are a DocFX-specific concept. They could be difficult to migrate to Flare. So use them where they solve version-related cross-reference dilemmas, but not everywhere (at least not yet).
The link form that uses the @
symbol may be convenient, but if you mistype the uid (or it is later removed), DocFX does not report the broken link (because the @ sign has multiple uses).
And finally, the package docs must be generated in the version of the Editor that matches the version of Unity you want to link to (currently 19.3, 20.1, and 20.2 are supported; everything else links to the current versionless Unity doc URL).