Token File

A token is used as a replaceable tag within a topic and is represented using a token element. The inner text of the element is a token name. The tokens are defined in a separate token file. They are an easy way to represent common items that you use regularly such as a common phrase or external link.

Below is an example of a token file.

<?xml version="1.0" encoding="utf-8"?>
<!-- This is an example tokens file -->
<content xml:space="preserve"
  xmlns:ddue="http://ddue.schemas.microsoft.com/authoring/2003/5"
  xmlns:xlink="http://www.w3.org/1999/xlink">

  <item id="BuildDate">{@BuildDate:MMMM d, yyyy}</item>

  <item id="SHFB"><ddue:externalLink xmlns:ddue="http://ddue.schemas.microsoft.com/authoring/2003/5">
  <ddue:linkText>Sandcastle Help File Builder</ddue:linkText>
  <ddue:linkUri>https://GitHub.com/EWSoftware/SHFB</ddue:linkUri>
  <ddue:linkTarget>_blank</ddue:linkTarget>
</ddue:externalLink>
  </item>

  <item id="SandcastleVersion">v2022.2.6.0</item>

  <item id="VisualStudioMinVersion">Visual Studio 2017</item>

</content>

The file consists of a root content node that contains one or more item nodes. Be sure to add the xml:space attribute to preserve whitespace and the two namespace attributes on the content element.

The item element has an id attribute that gives each one a unique identifier. This is used as the inner text of the token element in a topic to represent the token. The inner XML of the item will be used to replace the token at build-time.

The content of a token item can be anything you like and may include other MAML elements. In the examples above, they are used to define a commonly used link and some common text elements. When used with the Sandcastle Help File Builder, substitution tags such as BuildDate can also be used in the token content.

Other Resources