Note
To include conceptual content topics in a help file, add a content layout file to the project and use it to set the order and titles of the topics. For images that appear in conceptual content topics, use the Image build action.
Sandcastle Help File Builder Documentation
Build Actions
All file project items have a BuildAction property that determines how they will be handled at build time.
None
This is the default build action for all files without a recognized file extension as well as all conceptual content topic files (.aml). Files with this build action are ignored at build time and will not be compiled into the help file.
Tip
Setting the build action to None on any file type will cause it to be ignored during the build. This is useful for testing a different content layout while retaining the old file or perhaps creating different content layouts that can be selected by altering the build action to select the one you want for a given build.
Content
This is the default build action for any file that is considered to be HTML-based additional content or a supporting file. File extensions recognized include: .asp, .aspx, .ascx, .config, .css, .htm, .html, .js, .md, .txt, .zip
Note
Content files added to the root project folder will be copied to the root folder of the compiled help file. Files in subfolders will be copied to like-named subfolders in the compiled help file.
Image
Select this build action for images that appear in conceptual content topics. This is the default build action for files with the following extensions: .bmp, .gif, .jpg, .jpeg, .png. The ImageId property value is used in the mediaLink and mediaLinkInline MAML elements to reference them. Changes can be made to the image properties such as the file associated with the ID and its AlternateText without having to visit each topic in which it is referenced.
Caution
The value of the ID assigned to an image should not be changed. If it is, you will be required to manually locate and update the old ID in all topics that reference it.
The CopyToMedia property can be used to specify whether or not the image is copied to the .\Media folder even if not referenced in a media link. The default is False to only copy the image if referenced. Setting it to True is useful if the image is used for other purposes such as in an HTML content file, if used by a custom build component, or if it is only referenced in an externalLink MAML element.
Note
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.
This build action also causes the file to appear in the Entity References window when Images is selected in it.
CodeSnippets
Selecting this build action identifies the file as a code snippets file. These allows you to define code samples outside of conceptual topic files. Each snippet has a unique ID that can be referenced in multiple topics using a codeReference MAML element so that the snippets do not have to be copied into each one. Files with a .snippets extension are automatically assigned this build action. Multiple snippets files can exist in the project and all will be included in the conceptual content build. This build action also causes the file to appear in the Entity References window when Code Snippets is selected in it.
Tip
When using the Sandcastle Help File Builder, the Code Block Component offers the same set of features and several others for both inline and external code snippets. In addition, it supports many other languages and can import code from working source code files which allows you to pull in examples from working projects that you can maintain and build without having to update a separate example snippets file. As such, you may prefer to use it rather than manage the code snippets in an XML file.
Tokens
A token is used as a replaceable tag within a conceptual content 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. Selecting this build action identifies the file as a token file. Files with a .tokens extension are automatically assigned this build action. Multiple token files can exist in the project and all will be included in the conceptual content build. This build action also causes the file to appear in the Entity References window when Tokens is selected in it.
ResourceItems
Resource items are used by Sandcastle to insert localizable or parameterized text into help topics. The resource items are defined in various files that differ based on the selected presentation style. Adding your own file to a project and selecting this build action identifies it as a resource item file and allows you to override the values used for the stock resource items defined by Sandcastle and/or the help file builder. Files with a .items extension are automatically assigned this build action. Multiple resource item files can exist in the project and all will be included in the build. If a resource item is defined in multiple files, the last definition encountered will be used.
ContentLayout
This is the default build action for content layout files (those with a .content extension). These are used to define the layout of conceptual content topics in the table of contents and the additional topic properties such as their title and index keywords.
Note
Without at least one content layout file, no conceptual content will appear in the compiled help file.
Multiple content layout files can appear in a project. Each has a SortOrder property that is used to determine how their root entries are ordered within the overall table of contents. Each content layout and site map file is sorted based on the sort order and their items are then merged into the table of contents in that order.
SiteMap
This is the default build action for site map files (those with a .sitemap extension). These are used to define the layout of HTML and markdown based additional content topics in the table of contents and their title.
Note
Items referenced in a site map file must have a Content build action.
Unlike conceptual content, HTML and markdown based items in a project will be compiled into the help file if they have a Content build action with or without a site map. In the absence of a site map that references them, items will not appear in the table of contents. Files at the root level appear at the root level of the help file. Files in subfolders will appear in like-named subfolders in the help file.
Note that conceptual content is now the preferred method of adding non-API topics to the help file.
Multiple site map files can appear in a project. Each has a SortOrder property that is used to determine how their root entries are ordered within the overall table of contents. Each content layout and site map file is sorted based on the sort order and their items are then merged into the table of contents in that order.
XamlConfiguration
Files with a .xamlcfg file extension will get a build action of XamlConfiguration by default. These files are used to pass additional configuration information to the BuildAssembler tool's XAML Usage syntax generation component. The settings include classes to exclude from getting XAML usage syntax, the assemblies that contain types that should receive XAML usage syntax, and the XAML namespaces to associate with each API namespace. See the comments in the template file for more information.
Note
These files will only be included in the build if the XamlUsage syntax filter is enabled.