Replacing Stock Presentation Style Content

It is possible to replace the stock content files that are included in each help file (style sheets, scripts, icons, images, etc.). The stock content is copied from a presentation style sub-folders which can be found under the .\PresentationStyles folder of the root help file builder installation folder. Each presentation style has its own folder such as .\Default2022, .\VS2013, etc.

The folder structure for the content that gets added to each help file is the typically the same in each and consists of the following:

  • The icons\ folder contains stock help file images (i.e. for property icons, method icons, etc.).

  • The scripts\ folder contains stock JavaScript files.

  • The styles\ or css\ folder contains stock style sheets.

In addition, an html\ folder is created when the help file is built to contain the help pages generated from the documented assemblies and conceptual content. You can place additional HTML files to add to the project in a folder by the same name in your project or you can place them in the root of the project. Be sure to use an appropriate relative path on image references or links to other HTML pages based on the folder in which you place the content.

Modifying the Sandcastle copy of the presentation files directly will affect all help files that you build with the help file builder. For example, if you want to modify the style sheet for all projects you create with the help file builder, edit the branding.css files in the .\styles folders. The files do not need to be added to your project in that case. The downside to this approach is that you must maintain the changes with each new release of the help file builder. In such cases, it is better to create your own presentation style based on the existing one.

If you want to modify the files on a per project basis, that is when you would copy them to your project's folder. By adding the file to the project that resides in a like-named folder and has the same filename, you can replace the default file of the same name copied by the presentation style. In the example above, you would do the following assuming you are using the Default2022 presentation style:

  1. Right click on the project name in the Solution Explorer window and select the option to add a new folder. Call it css to match the folder in the presentation style.

  2. Copy the style sheet files that you want to modify from the presentation file folder to the new project folder (presentationStyle.css for example located in the %ProgramFiles(x86)\EWSoftware\Sandcastle Help File Builder\Components\Default2022\css folder.

  3. Modify the style sheet files as needed. As an example, open the presentationStyle.css file in the project and change the codeHeader style's font and add a color entry to make the text green:

     
    .codeHeader {
                font-family: Arial;
                font-style: normal;
                background-color: #e6e6e6;
                box-sizing: content-box;
                color: green;
                display: flex;
                flex-direction: row;
                margin-top: 1em;
                padding-right: 0.25em
}

  4. Save the changes, build the help project, and then open the resulting help file. Note that the code section headers are now using the new style.

  5. Most of the styles are contained in the branding.css file. The other files are format-specific overrides that change the styles slightly in the help format indicated by the filename suffix so that the topics look fairly consistent across all help formats. You can view the HTML for the rendered topics to determine the elements and/or class names that may need modifying in the style sheet.

  Note

The presentation styles are all different and their files are not interchangeable. As such, if you change the presentation style, you must copy the matching files from the new presentation style and modify them with your changes.

See Also