Special Folder Locations
The help file builder has the ability to utilize third-party custom build components, plug-ins,
syntax generators, and presentation styles. In addition, the project system allows you to add files based on
user-defined template files. Build components and plug-ins can also create configuration or cache files to use
across builds if needed. In order to work correctly, each type of file must be located in the correct place.
None of the folders mentioned below exist by default so you will need to create them yourself.
The exception is the root local application data folder. It will be created on first use by the help file
builder if referenced by a build component or a plug-in configuration.
Project-specific build components, plug-ins, syntax generators, and presentation styles are also
supported. To utilize project-specific components either place the components in the project folder or a
subfolder beneath it or point to the component location using the project's Component Path
property.
If third-party components are available as NuGet packages, they can be added to the project using
the Component Packages node in the project explorer tool window.
There are two root application data folders (Common Application Data and
Local Application Data). These equate to one of the following folders based on your
operating system:
Operating System | Folder Location |
|---|
Windows Vista or later | Common Application Data: %ProgramData%\EWSoftware\Sandcastle Help File Builder Local Application Data: %LOCALAPPDATA%\EWSoftware\Sandcastle Help File Builder |
Windows XP | Common Application Data: %ALLUSERSPROFILE%\Application Data\EWSoftware\Sandcastle Help File Builder Local Application Data Folder: %USERPROFILE%\Local Settings\Application Data\EWSoftware\Sandcastle Help File Builder |
The {@AppDataFolder} substitution tag will resolve to the root common
application data folder for the help file builder. The {@LocalDataFolder} substitution
tag will resolve to the root local application data folder for the help file builder.
Third-party build components that you want to use from within the help file builder via the
ComponentConfigurations project property and custom syntax filter generators accessible
via the SyntaxFilters project property must be placed in the Common
Application Data folder. This equates to one of the following folders based on your operating
system:
Operating System | Folder Location |
|---|
Windows Vista or later | %ProgramData%\EWSoftware\Sandcastle Help File Builder\Components and Plug-Ins |
Windows XP | %ALLUSERSPROFILE%\Application Data\EWSoftware\Sandcastle Help File Builder\Components and Plug-Ins |
Put the build components and any of their required configuration and supporting files within the
noted folder or a subfolder beneath it. These will be shared by all users on the same computer.
Third-party build process plug-ins that you want to use from within the help file builder via the
PlugInConfigurations project property must be placed in the Common
Application Data folder. This equates to one of the following folders based on your operating
system:
Operating System | Folder Location |
|---|
Windows Vista or later | %ProgramData%\EWSoftware\Sandcastle Help File Builder\Components and Plug-Ins |
Windows XP | %ALLUSERSPROFILE%\Application Data\EWSoftware\Sandcastle Help File Builder\Components and Plug-Ins |
Put the plug-ins and any of their required configuration and supporting files within the noted
folder or a subfolder beneath it. These will be shared by all users on the same computer.
Third-party presentation styles that you want to use from within the help file builder via the
PresentationStyle project property must be placed in the Common Application
Data folder. This equates to one of the following folders based on your operating system:
Operating System | Folder Location |
|---|
Windows Vista or later | %ProgramData%\EWSoftware\Sandcastle Help File Builder\Components and Plug-Ins |
Windows XP | %ALLUSERSPROFILE%\Application Data\EWSoftware\Sandcastle Help File Builder\Components and Plug-Ins |
Put the presentation styles and any of their required configuration and supporting files within the
noted folder or a subfolder beneath it. These will be shared by all users on the same computer.
Due to various folder/file permission issues and in order to allow multiple users on the same
computer to have their own custom settings and cache files used by build components and plug-ins, these types of
files must be stored in the Local Application Data folder (see the
Root Application Data Folders section above).
As an example, the cached build components supplied with the help file builder create their cache
files in the following location based on the operating system:
Operating System | Folder Location |
|---|
Windows Vista or later | %LOCALAPPDATA%\EWSoftware\Sandcastle Help File Builder\Cache |
Windows XP | %USERPROFILE%\Local Settings\Application Data\EWSoftware\Sandcastle Help File Builder\Cache |
Each user is free to delete such files to get back to a default state without affecting other users
on the same computer. Likewise, they can give copies of their settings files to other users for them to place in
a like named folder in their settings area to make use of them as well.
Due to various folder/file permission issues and in order to allow multiple users on the same
computer to have their own custom file templates, these types of files must be stored in the Local
Application Data folder. This equates to one of the following folders based on your operating
system:
Operating System | Folder Location |
|---|
Windows Vista or later | %LOCALAPPDATA%\EWSoftware\Sandcastle Help File Builder\Item Templates %LOCALAPPDATA%\EWSoftware\Sandcastle Help File Builder\Conceptual Templates |
Windows XP | %USERPROFILE%\Local Settings\Application Data\EWSoftware\Sandcastle Help File Builder\Item Templates %USERPROFILE%\Local Settings\Application Data\EWSoftware\Sandcastle Help File Builder\Conceptual Templates |
Use the Item Templates folder to store custom templates for project files such
as images, HTML files, style sheets, script files, tokens, code snippets, or XML files. Use the
Conceptual Templates folder to store custom MAML topic template files. These template files
appear on the Custom Templates submenus within the project explorer, site map editor, and content layout
file editor.
Each user is free to delete such files to get back to a default state without affecting other users
on the same computer. Likewise, they can give copies of their template files to other users for them to place in
the templates folder in their settings area to make use of them as well.
This only applies to the standalone GUI. To define custom file templates for the Visual Studio
package, see the Item File Templates topic.
