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

Question

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

2.1k Views Asked by jedatu At 24 May 2011 at 04:17

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.

Original Q&A

There are 3 best solutions below

**Jim Schubert** · Answer 1 · 2012-04-11T15:45:38.227000

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>

**Fabian Tamp** · Answer 2 · 2013-01-08T01:41:02.983000

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.

**dcastro** · Answer 3 · 2014-05-12T12:08:15.517000

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.

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

There are 3 best solutions below

Related Questions in SANDCASTLE

Related Questions in MAML

Trending Questions

Popular # Hahtags

Popular Questions