This project has moved and is read-only. For the latest updates, please go here.

SHFB: How to Add Images to Conceptual topics and in Code (XML) Commenting

Topics: Developer Forum, Project Management Forum, User Forum
Jan 22, 2015 at 4:35 PM
Problem 1: You cannot figure out how to get image to show up in conceptual topics...
Step 1) Make sure to use the proper XML markup similar to this:
          <image xlink:href="MyMainImage"/>
Step 2) Notice that the Href doesn't have the file type associated, this is because Sandcastle wants the ID of the resource.
Step 3) Add the image to the project, you can create a folder named Images and put it there.
Step 4) Go to properties page of the image and set Build action to Image. Copy To Media is not relevant if you have the markup shown above. Here's the catch, take note of the Image ID in the properties page, this is what you will use in the HREF above.
Step 5) Recompile the project and open up the CHM file and you will see the image.

Problem 2: I cannot get the Image to show using Code commenting XML markup
Step 1) In the summary section of the code comment, the markup can look like this:
        /// <summary>   
        /// <remarks><img src="\Images\MyImage.PNG"/></remarks>
        /// </summary>
Step 2) Note that the src attribute does contain the file type. Create an Images folder and drop the image there.
Step 3) Open the properties page of that image and set the Build action to CONTENT. The Copy to Output Director is not relevant.

Happy coding and documenting!
Thanks to Eric for this fine tool and all the work to improve it over the years!

SHFB Cannot Add Image
Sandcastle Help File Builder Conceptual Topic Images
Code Commenting Images
CHM File Images
Jan 22, 2015 at 6:04 PM
Some additional info:

If used in both conceptual topics and XML comments, the BuildAction will need to be set to Image. In that case, it will end up in the .\Media folder in the compiled help file so use that path in the XML comments reference. If you get in the habit of using .\Media as the project folder used to contain the images regardless of where they're used, it saves having to remember that requirement.

The Copy To Media option is used to ensure the image is copied to the .\Media folder regardless of whether or not it's actually used in a conceptual topic. If an image is used in both conceptual topics and XML comments, you can set it to True so that in the event that the conceptual link goes away, the image is still copied for the XML comments reference if it still exists.