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

Additional Content/SiteMap Bug of omission

Topics: User Forum
Apr 6, 2012 at 5:57 AM

I understand that Additonal Content and SiteMap are depreciated features and that one possible answer to this question is just a statement of that fact. However, these features actually are truly useful to me - except for one small flaw.
I have a fairly large collection of Html pages which I would like to use in both a web site and in a .chm file. These pages are stored in several directories (a key point).
I organize the pages into an TOC type heirarchy, which is not fully expressed in the directory structure. The logical structure is stored in a SiteMap file in SHFB acceptable format (which I use for other purposes as well).
Each Html page has Navigation and other references to other pages - which may not necessarily reside in the directory of the referring page.
I add the Site Map.sitemap file to my SHFB project and all is good - the SHFB TOC is as I want it, the pages are properly included in the .chm, etc.
However, many (most) of the links within those pages are broken.

A little investigation shows that if I were to not use the Sitemap but rather, simply add the directories of pages to the SHFB project, the references within the pages work. Of course the SHFB TOC reflects the directory structure, not the proper logical structure. In this case, the intermediate htm pages are copied to a directory structure that mimics the structure of the original directories.

With the Sitemap, the intermediate .htm pages are all copied to a single intermediate directory, thus breaking the internal links.

Ideally and logically wouldn't it be best to have the intermediate copy operation actually respect the directory structure expressed in the Sitemap's urls?

I can get around this, at some cost, but it seems to me that there is a bug of omission lurking here and the Sitemap feature is so close to ideal as it stands that this frustrates me.


Apr 6, 2012 at 8:39 PM

It should be working as you indicate as long as a couple of conditions are met.  It's been a while since I worked with the deprecated additional content model and site maps but the processing goes like this:

1. SHFB builds a file system based TOC from any content items it finds in the project (i.e. HTML files with a BuildAction of Content).  These are copied to the output folder with a folder structure that duplicates their structure in the project.  So, if you've got subfolders in the project with content items, they will be copied to like-named subfolders in the output that gets compiled into the help file.

2. It then loads site map files it finds in the project.  If any source files in the site map match project files copied in the first step, it associates the site map entry with that file in the output folder complete with subfolder location.  If not, the source file from the site map is copied to the root output folder.

3. If no site map files are found, it will use the TOC generated in step 1 for the help file TOC.  If any site maps are found, the TOC from step 1 is discarded and the site maps are used to create the TOC.

Since your files are ending up in the root folder, my guess is that either you haven't included the HTML files referenced by the site map in the project and/or they do not have a BuildAction of Content.  Make sure both of those requirements are met and you should get the results that you want.



Apr 6, 2012 at 9:59 PM

Thank you Eric. Your clear & concise explanation immediately solved my problem.

For some reason I was treating the SHFB project requirements to include "Content Folders" OR "Site Map.sitemap" when, in fact  I should have been treating the requirement as "Content Folders" AND "Site Map.sitemap".  I hadn't read more than half way thru your response before I knew what my problem was.
I made the necessary adjustments and, no surprise, it worked perfectly.