This project has moved and is read-only. For the latest updates, please go here.

Custom html pages and formatting

Topics: User Forum
Mar 10, 2010 at 11:25 PM

I have about 10 adidtional html pages that I need to stuff into the .CHM and the web help.  I can get them to link without any problem.  Is there a way I can set these to pickup the formatting of the particular environment that they will be in.  If I use the style sheet settings from vs2005, they look just fine in the .CHM (font, pretty colors, etc) but on the web they look horrid as best.  If I use the styles from one of the web generated files, sample problem in reverse.

Is there a way to make this consistent across the different formats, in regards to additional .html files?

Mar 11, 2010 at 3:05 AM

The preferred approach for additional content is to use MAML so that the topics utilize the selected presentation style from the project.  There's an HTML to MAML converter available at the Sandcastle Styles project site.  It does a pretty good job of converting the HTML to the equivalent MAML but the output does need some review and clean-up.  There's also a MAML guide to get you familiar with MAML if you haven't used it before.  The other alternative is to move the content of the HTML files to XML files with a .topic filename extension.  These are ran through a default XSL transformation that will apply the basic presentation style to them.  This method was used prior to SHFB's support of MAML and has been deprecated.  If interested, see the Topic File Transformation help topic.



Mar 11, 2010 at 4:54 PM


Thanks for the follow up.  The MAML method will probably work.  These are pretty simple pages, and contain mostly references and notes, so little coversion should be required. 


Mar 11, 2010 at 10:08 PM

Does anyone have a sample of an HTML file that has markups for MAML?  There is no clear pointer in the documentation provider on how it actually works and there seems to be a lack of samples for html->maml conversion.

Also, the goal of this is to wrap it into an msbuild project with the shfb.  The shfb project works fine, so any pointers on implementing the post html->maml file in that would be greatly appreciated.

Mar 12, 2010 at 2:40 AM

I'm not sure I understand the question.  HTML files don't contain MAML markup and vice versa.  MAML is effectively an XML file that gets ran through the Sandcastle XSL transformations to output an HTML topic in the selected presentation style.  If you're asking how the HTML tags are mapped to equivalent MAML elements, you can take a look at the configuration file for the HTML to MAML converted noted above.  The help file included with it goes into more detail about how it converts an HTML file to a MAML file.  The resulting MAML files are added to the SHFB project and a content layout file is added to which you add the topics and define their layout for the TOC.  The converter will create a layout file for you based on the files it converts.  If images are found, it also creates a media content file that can be imported into the project.



Mar 12, 2010 at 4:38 AM


I'm usually not this dense, but I'm missing something.  So, here is my problem.  I have about 10 html files; 1 is a FAQ, 1 is a notes file, 8 are sample code files.  They are currently in html (in a simple layout) but I can manually convert them to any format (xml/whatever).  There isn't much layout to be concerned about (colorized code which isn't imporant, but thats it).

I have read the MAML, but I'm not understanding plug in the code/MAML/SHFB.  Can some provider a bear sample in this scenario.  I just don't see how these tie together at this point.

Mar 12, 2010 at 4:59 AM

Less dense now.  I see where and how to create the MAML files and the xml tags for that.  Looking at it, it seems there are only a few things I need to add for now, which is fine.  So the next question, which should get me there, is now that I have the MAML file, what's the best way to add this to the SHFB msbuild script.  I can't find any samples on this.

Mar 12, 2010 at 8:15 PM
Edited Mar 12, 2010 at 8:17 PM

Add a content layout file to the SHFB project in the Project Explorer window.  Edit the content layout file and add the topics to it in the order that you want.  You can use the Add Existing Topic option in the file editor if you've got existing files or create new topics from there.  If you used the HTML to MAML converter, just add the content layout file and the topics it generated to the project.  You can edit the layout file to adjust the topic order as needed.  SHFB will use the content layout file to figure out which files to build and how to arrange them in the TOC.  There's a section on conceptual content and the editors in the help file if you need specific details.  The SHFB help file itself is built from MAML topics and the source code download contains the project file for it if you want to see how it is put together.



Mar 13, 2010 at 1:52 AM


Thanks for the follow up.  Followed instructions by create new content layout, added new topic, edited XML there, and it worked perfectly.  I now have a sample topic online.  I thing I will convert everything by hand (since it won't change very often).