Click or drag to resize
Sandcastle Help File BuilderConceptual Content

Conceptual content is similar in nature to the additional content used in prior versions of the help file builder. It allows you to define non-API documentation that is included in the help file for usage notes, walkthroughs, tutorials, etc. Instead of HTML, conceptual content topics use Microsoft Assistance Markup Language (MAML). This is basically XML conforming to a well defined schema that describes the structure of the conceptual content much like XML comments describe the structure of the code comments. There is no layout or style information within the MAML files. Instead, they are ran through a series of XSL transformations using Sandcastle's BuildAssembler tool similar to the reference (API) content so that they match it in appearance and features. This allows you to utilize the various build components to alter and extend the presentation style of the topics.

Tip Tip

A guide to using MAML with Sandcastle is included with the Sandcastle tools installer. Open it using the Sandcastle MAML Guide link in the Sandcastle group of the All Programs menu after installing Sandcastle.

Tip Tip

If you need to convert HTML topics to MAML topics, the HTML to MAML Converter is also available as part of the Sandcastle tools installer.

Conceptual Content Files

Conceptual content is composed of several different file types within a project. You can use folders within the project to group these files as you see fit.

  • Content layout files define which topics are included in the help file and how they are arranged in the help file's table of contents. Content layout files have a BuildAction of ContentLayout.

  • Topic files contain the MAML that defines each topic. These files should have a BuildAction of None. The build process handles converting the topics to HTML and adding them to the help file based on a content layout file.

  • Image files define image resources used in the conceptual content. These have a BuildAction of Image.

  • Token files allow the definition of common MAML snippets or content used in topic files. These have a BuildAction of Tokens.

  • Code snippets files allow you to define code snippets that will be used in conceptual content topics and are rendered by Sandcastle's ExampleComponent. These have a BuildAction of CodeSnippets. See the MAML Guide for more information on creating code snippets files.

Custom Template Files

The designer uses template files to create new conceptual topics. You can create your own templates for use in the designer by creating a Conceptual Templates folder in the Local Application Data folder. Any MAML (.aml) files found in this folder will be added to the Custom Templates menu option in the Add Sibling Topic and Add Child Topic submenus. See the Special Folder Locations topic for more information. See the Item File Templates topic for information on creating file templates for use with the Visual Studio package.

See Also