Lightweight Website Style Plug-In

This plug-in adds lightweight table of contents and search elements to each topic in website builds. It is utilized by newer presentation styles such as the VS2013 style that contain the necessary elements that it looks for in order to insert the required elements.

  Note

This plug-in currently has no configurable options and is hidden from the Plug-Ins property page. It is added automatically as a dependency plug-in at build time by the presentation styles that utilize it.

Advantages of the Lightweight Style

The lightweight website style has several advantages over the frame-based website format used by the older presentation styles.

  • Since the frame is omitted, the browser's address bar always contains the direct URL to the topic being viewed. This makes it much simpler to create links to topics from external sites.

  • Site performance is improved. This is especially true of sites that formerly used the old index.html page that contained the full table of contents. In the lightweight style, each page contains only the table of content fragment that it needs to navigate to nearby topics. The content of collapsed topic nodes in the table of contents tree are loaded on demand.

  • ASP.NET or PHP is no longer required for viewing or searching the site. This allows for the sites to be hosted on servers that can only serve static content. ASP.NET or PHP will be utilized for site searches if available since they provide better performance. If not, a client-side script implementation is available for use.

Known Issues

There are a few issues to be aware of when using a presentation style that utilizes the lightweight website style.

  • When you switch to a presentation style that uses the lightweight website style, it will break existing links to topics from external sites. Correcting those links is simple. All that needs to be done is to remove the "Index.aspx?topic=" or "?topic=" query string section from the URLs. For example:

     
    Old URL Formats:
https://ewsoftware.github.io/SHFB/Index.aspx?topic=html/1aea789d-b226-4b39-b534-4c97c256fac8.htm
https://ewsoftware.github.io/SHFB/?topic=html/1aea789d-b226-4b39-b534-4c97c256fac8.htm

New URL Format:
https://ewsoftware.github.io/SHFB/html/1aea789d-b226-4b39-b534-4c97c256fac8.htm

  • As noted above, if ASP.NET or PHP is not available, site searches will be performed using a client-side script implementation. While it does work, it is not optimal since it has to download the keyword index files used for the search to the client. The files are cached after their first use but this will slow initial searches, especially on larger sites and when the browser cache is cleared.

  • The index feature has been dropped and is not available.

Requirements

If you create a new presentation style that utilizes this plug-in, the following requirements must be met.

  • A shared content file must contain a resource item with the id resizeToolTip that defines the tool tip used for the resizing element.

  • A div element must appear in each topic with a class attribute value of pageHeader. The search box will be inserted inside this element.

  • A div element must appear in each topic with a class attribute value of topicContent. The element containing the table of contents fragment and resizing element will be inserted ahead of it.

  • Image, style sheet, and script resources used by the lightweight table of contents and search elements must be included as part of the website output for the presentation style. See the VS2013 presentation style for an example, specifically the files in the .\Web folder and the additional style sheet .\styles\branding-Website.css.

  • The BuildAssembler configuration files must include the Additional Header Resources Component to insert the necessary resource items and metadata into each topic based on the file format. See the VS2013 presentation style configuration files for an example.

See Also

Other Resources