Site Map File Editor?

Oct 29, 2009 at 4:28 PM
Edited Oct 29, 2009 at 6:42 PM

All of my documentation information (structure/content) is contained in my assembly and documentation file (doc.xml). Is there a way to add the information contained in these files to the site map via the editor or does each namespace/class need to be added separately? It seems that Microsoft may have its own site map protocol. Is there somewhere I can find a complete discussion of site maps?

So my Namespace convention is as follows:


my site map was created with expectations of the same output prior to using a sitemap so it looks like:

<?xml version="1.0" encoding="utf-8"?>
<siteMap xmlns="">
  <siteMapNode title="Product" url="~\html\N_Product.htm" isDefault="true" />
  <siteMapNode title="Product.Lib1" url="~\html\N_Product_Lib1.htm" />
  <siteMapNode title="Product.Lib1.SubLib1" url="N_Product_Lib1_SubLib1.htm" />
  <siteMapNode title="Product.Lib2" url="~\html\N_Product_Lib2.htm" />
  <siteMapNode title="Product.Lib2.SubLib2" url="~\html\N_Product_Lib2_SubLib2.htm" />
  <siteMapNode title="Product.Lib3" url="~\html\N_Product_Lib3.htm" />
  <siteMapNode title="Product.Lib4" url="~\html\N_Product_Lib4.htm" />
  <siteMapNode title="Product.Lib5" url="~\html\N_Product_Lib5.htm" />

Resulting in error:

SHFB: Error BE0065: BUILD FAILED: Could not find a part of the path 'C:\Product\Work\~\html\N_Product.htm'.

1) My html files are a product of the compile (assembly and doc.xml) so I'm not sure what the SourceFile property should be in the Site Map Editor.
2) My output path is .\Help so I expected the relative path notation to produce a reference to 'C:\Product\Work\Help\html\N_Product.htm' not 'C:\Product\Work\~\html\N_Product.htm'.


Oct 29, 2009 at 7:16 PM

Why are you trying to create a TOC for the API content?  Sandcastle does that automatically.  You can use the hierarchical TOC plug-in to alter the default structure by having it nest namespaces and use the TOC Exclude plug-in to hide members in the TOC but that's it.  The sitemap file is purely for additional HTML content that you want to add to the help file (intro, walkthroughs, etc).  The sitemap editor in SHFB should be used, not an external sitemap editor.  The file structure is similar but not all features are supported (i.e. the "~" in the folder path).  If you really do want to rearrange the TOC for the API content differently than the default and the current plug-ins won't do what you want, you should look into creating a new plug-in for SHFB that will do it since you can modify the toc.xml file created during the build and won't have to manage a site map outside of the build process.



Oct 29, 2009 at 8:27 PM
Edited Oct 29, 2009 at 8:46 PM

Clearly I don't understand the documentation. I was trying to develop a sitemap for the whole project, not rearrange the API. If this is not necessary I'm not sure how to construct the sitemap. The directory structure is as follows:

       |-eqndoc.xml (doc.xml transformed latex equations to img tags, directed at the eqn dir)
             |    |-eqn_0001.png
             |    |-eqn_0002.png
             |    ...
                  |     |-Ex1.html
                  |     |-Ex1.png
                  |     |-Ex1.cs
                  |     |-Ex2.html
                  |     |-Ex2.png
                  |     |-Ex2.cs
                  |     ...

Everything is correct but I don't want the existing Folder "html" in the index. How can I create a "partial" site map file that includes nothing. That is (if the siteMapNode tag had an TOCInclude property) my "partial" site map would consist of one node (to exclude it and everything beneath it):

 <?xml version="1.0" encoding="utf-8"?>
siteMap xmlns="">
    <siteMapNode title="html" url="html" TOCInclude="false"/>



Oct 30, 2009 at 3:16 PM

I guess I misunderstood you.  You said all your documentation was in the assembly and doc.xml file which I took to mean that doc.xml was the XML comments file for the assembly.  Your site map looked like it was using the friendly names produced by Sandcastle so it looked like you were trying to manually define the TOC for the API topics.  If all you want is an empty sitemap, right click the root node in the Project Explorer window and use the Add | New Item | Site Map option to add the file.  Double click it to edit it.  By default, it adds all existing content items in the project.  Just delete all of the entries in the site map file and save it.  When you build, the empty site map will take precedence and it won't add the content items to the TOC.  If you've got other HTML files that you do want to appear in the TOC, do add them to the site map using the site map file editor in SHFB.



Oct 30, 2009 at 3:47 PM

An empty site map... Yep that worked!