How to add a colorized HTML code snippet in Sandcastle documentation?

Question

I am using the Sandcastle Help File Builder and would like to include colorized HTML code snippets in the "Conceptual Content". Is this possible and if so, how?

I have tried <code>, <codeExample>, and <sampleCode language="HTML" />.

The best result so far is to HTML-encode the sample HTML and place it in a .snippets file like so.

<?xml version="1.0" encoding="utf-8" ?>
<examples>
   <item id="htmlSnippet">
      <sampleCode language="HTML">
         &lt;span&gt;My Html&lt;/span&gt;
      </sampleCode>
   </item>
</examples>

Then reference it in the .aml file.

<codeReference>htmlSnippet</codeReference>

I would prefer to have it colorized, but I can't figure out a way to add the formatting.

score 2 · Answer 1 · answered May 12 '14 at 12:08

According to the MAML Guide, the proper way of doing this is to use a <code> tag with a CDATA section:

<code language="xml" title="Example Configuration">
<![CDATA[
    <span>My Html</span>]]>
</code>

The contents of the CDATA section will be treated as a literal string, and indentation will be preserved.

score 1 · Answer 2 · answered Apr 11 '12 at 15:45

I know this is old, but Sandcastle supports html as xml. I figured I should comment in case anyone else comes across this post as I did.

This should work:

<?xml version="1.0" encoding="utf-8" ?>
<examples>
   <item id="htmlSnippet">
      <sampleCode language="xml"><!CDATA[[
         <span>My Html</span>
       ]]>
      </sampleCode>
   </item>
</examples>

If you're using Sandcastle Help File Builder, you may create your own syntax parser as described here and here, although xml is available by default... using the XAML filter's generator, which is defined here if you want to look at the config:

<generator type="Microsoft.Ddue.Tools.XamlUsageSyntaxGenerator"
    assembly="{@SandcastlePath}ProductionTools\SyntaxComponents.dll">
    <filter files="{@SandcastlePath}Presentation\Shared\configuration\xamlSyntax.config" />
</generator>

score 1 · Answer 3 · answered Jan 08 '13 at 01:41

According to the SHFB documentation for the Code Block Component, you should be able to just use the <code>.

I got it to work without a problem; here's what I did:

test.html

<html>
    <head>Something!</head>
    <body>
        <h1>Heading</h1>
<!-- #region myhtml -->
        <p>Paragraph</p>
        <div>Div for <strong>Good</strong> <em>measure</em>.</div>
<!-- #endregion -->
    </body>
</html>

SomethingorOther.aml

<code language="html" source="../Examples/test.html" region="myhtml" />

Result:

HTML Highlighting in SHFB

Please note that in the preview, your sample will appear as unhighlighted XML, but when you build the documentation, everything should like just fine.

How to add a colorized HTML code snippet in Sandcastle documentation?

3 Answers3