Welcome

Welcome to the Sandcastle MAML Guide. This is intended to be a reference that you can use to find out all that you need to know about Microsoft Assistance Markup Language (MAML) as used with Sandcastle to produce help files containing conceptual content. If you have any information, tips, updates, or corrections that you would like to see added to the guide, feel free to submit them to the author using the Send Comments link in the page footer.

Conceptual content 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 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 Sandcastle and third-party build components to alter and extend the presentation style used in the topics.

The term "conceptual content" is actually a catch-all term used to refer to the various types of content that may appear in the help file. MAML actually defines several different content types, each used for a specific type of document (conceptual, glossary, how-to, reference, etc.). Each type has a specific structure with various required and optional XML elements. This help file will let you get to know the various document and element types.

Creating the actual topic files is just a matter of entering the content using a text editor. Creating a help file from them requires several configuration files and the Sandcastle tools. If you are going to build a help file using Sandcastle alone, see the topics in the Conceptual Content File Types section. They cover the various file types that are used in the build process.

If you prefer a more visual and automated approach to managing and building help files, it is strongly recommended that you use one of the third-party tools such as the Sandcastle Help File Builder. They contain all of the necessary features and tools required to make building help files with Sandcastle a much simpler process. This help file was produced using the Sandcastle Help File Builder and is an example of what the Default 2022 presentation style looks like.

Other Resources