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

HTML, API, MAML style best practice

Aug 10, 2011 at 4:45 PM

I'm trying to achieve having two top level topics. The first, conceptual information (i.e. help/how-to/tutorial/etc.). The second, the API. For my conceptual I can style things easily in HTML and just include the entire folder into SHFB and it builds fine with all images/etc. I cannot figure out how to control the ordering of the conceptual and API topics. The API shows up first. I created a content layout and can specify a containing folder for my API, but how do I specify where my HTML goes?

Second question. I prefer using HTML but am not opposed to going with MAML. The one concern I have is styling the MAML to the same degree I can style the HTML. I'm not very familiar with MAML. I saw that I can include a styles/presentation.css file to override the style. How can I have my conceptual files be styled in one way while having my API styled with the default presentation?


Aug 12, 2011 at 8:19 PM

Content layout files are only for MAML topics.  You need to use a site map file if you want to control the layout and ordering of additional HTML content.  Be aware that site maps and HTML content are deprecated and are not supported for MS Help Viewer output.  MAML and a content layout file are the preferred method now and work with all output formats.  Regarding MAML topics, the main point of using them is so that they look and feel the same as the API topics.  The two use the same Presentation.css file and share many common elements so it's unlikely you'd be able to get much differentiation between the two as that's not the point.  MAML is used to define the content and the selected presentation style applies the styling and layout.  The Sandcastle MAML Guide can get you up to speed on the various MAML elements and how to use them.