Media Content File

The media (images) used by conceptual content in a help file project are defined in a separate media content file. Each is assigned a unique ID that is used to refer to the image in conceptual topic links. When a help file is built, all images referenced by an image link are copied to the help file's .\Media folder. Any unused images are omitted.

  Note

The Sandcastle Help File Builder does not use a media content file directly. Instead, images are managed as project file items and the media content file is created for you automatically at build time based on the property values on those items.

Media Content File Format

Below is an example of a media content file.

Example Media Content File
<?xml version="1.0" encoding="utf-8"?>
<!-- This is an example media content file -->
<stockSharedContentDefinitions>
  <item id="4cfacbe8-d100-471c-9d69-1dbcce50e316">
    <image file="..\ProjectImages\SmallInformation.png">
      <altText>Information</altText>
    </image>
  </item>
  <item id="6be7079d-a9d8-4189-9021-0f72d1642beb">
    <image file="..\ProjectImages\SandcastleLogoLarge.JPG">
      <altText>Sandcastle</altText>
    </image>
  </item>
  <item id="98a8a8b7-c374-40c7-902a-91c947bf107c">
    <image file="..\ProjectImages\SandcastleLogoSmall.jpg" />
  </item>
  <item id="b5d069f7-5daf-45ae-882c-4596ab2b724a">
    <image file="..\ProjectImages\SecuritySuccess.png" />
  </item>
</stockSharedContentDefinitions>

The file consists of a root stockSharedContentDefinitions node that contains one or more item nodes that represent the images.

The item element has an id attribute that gives each one a unique identifier. This is used as the target of the media link elements in the topics. Within the item element is a required image element used to define the image. The file attribute should point to the location of the image file. A relative or absolute path can be used as long as it can be located at build time. If you would like to display alternate text when the mouse hovers over the image, nest an altText element within the image element as shown in the first item in the example above. The inner text for it defines the alternate text to display.

  Note

The unique ID is not case-sensitive. The example above uses GUID values for the ID but you are free to use any unique value that you like.

  Caution

Unlike topics, image files will retain their name when copied to the media folder. As such, if you add two images from different locations that have the same name, one will overwrite the other when the help file is built.

See Also