# Transforming your output with skins
> [HTML Version](hm_working_configoutput_skins.html)
You may already be familiar with the concept of "skins" from other programs: You select a skin file and the appearance and layout of the entire program is transformed in seconds. Help+Manual enables you to do this with your HTML-based output. You can save your entire design with all its HTML templates and relevant HTML settings in a **.hmskin** file. You then select this file when you publish to apply the layout to the current project without changing any of the project's own settings.
Please note that you can only save your own projects as skins if you have the Professional or Floating license version of Help+Manual. Basic version users can use skins without limitations and edit existing skins (for example skins from the Help+Manual Plus Packs) but they cannot create new skins from their own projects.
**(./images/prod_tip.gif) Productivity Tip**
Skins can only be used for HTML-based output formats. You can style your PDF files and printed manuals with [print manual templates](hm_working_pdf_templates.md), which work in the same way as skins. Word files use [DOCX templates](hm_working_configoutput_docx_edtemplate.md).
[] How to use skins - try it now\!
1. Open a project of your own, select _Publish_ in the Project tab, then select WebHelp or HTML Help as the output format.** **
2. On the [Publish page](hm_ref_ribbon_file_publish.md) click on the drop-down menu in the _Select Skin_ section and select one of the standard **.hmskin** files in the Skins folder in the Help+Manual program directory. You can also select the _Open Skin..._ option to select a skin file directly.
When you publish your output it will have the "look and feel" applied by the skin. You didn't have to do any design work at all\! Cool, no?
[] How to create a skin file
Skin files contain everything you need to style your HTML-based output: Text and table styles, user-defined variables, your Baggage files (template graphics and logos), HTML page templates and all the settings and templates for WebHelp. You can turn any project into a skin file just by saving it as a skin and you can edit skin files in Help+Manual, just like normal projects.
1. Open a project with a design that you want to use for other projects.** **
2. Select _Save As..._ in the File menu and choose the _Skin XML File_ option.
3. Choose a place to save the skin, enter a name and save.
4. You will be asked which configuration components of your project you want to include in your skin.
_(./images/dlg_saveskinoptions.png)_
### Skin components you can include or exclude when creating a skin
| | |
|------|------|
| HTML Page Templates: | Should generally always be included. This includes both the templates for topic pages and the various WebHelp HTML templates. Without them, your skin will not replace the HTML templates from your project. In most cases, that would be pretty pointless. |
| Baggage Files: | Should generally always be included. The [Baggage Files](hm_advanced_baggage.md) section is the place in your skin where you store your additional JavaScript, CSS and other files for your skin. Putting them there exports them automatically when you publish. |
| Variables: | Should generally always be included. Having variables in the skin allows you to set up configuration options that you can adjust without having to adjust the source code in your templates or baggage files. Variables can be used in all HTML templates in your skin and in JavaScript and CSS files in your baggage files – they are scanned and replaced by Help+Manual on publishing.
All variables you use in your HTML templates and baggage files must be written with the standard **<%VARIABLE\_NAME%>** syntax, otherwise they won't be found. You can also use variables from your project (both global and user-defined). |
| Custom Builds: | Should generally always be included, but delete any custom builds from your project in the skin after creating the skin. Custom builds defined only in the skin are displayed in the additional Skin Include Options box displayed in the Publish screen. Having custom builds in your skin allows you to create configuration options that can be activated or deactivated on publishing.
You can include or exclude code in your HTML templates or in your JavaScript and CSS files in your baggage files with custom builds. For example, suppose you have a custom build called TOPICFOOTER:
Include code when your build option is active with:
**Code you want to include when TOPICFOOTER is selected goes here**
Include code when your build option is inactive with:
**Code you want to include when TOPICFOOTER is NOT selected goes here**
[See this topic](hm_advanced_htmltemplates_conditions.md) for more details. |
[] How to edit skin files
Skin files are actually normal single-file projects with some special limitations. You can open them and edit them like normal projects but you can only edit those components that are included in the skin, everything else is unavailable.
1. Select _Open_ in the File menu and then select _Help+Manual skin files (.hmskin)_ as the type of file to be opened. (If you don't select this you won't be able to see the skin files\!)** **
2. Select an **.hmskin** file to load and edit. You can find some sample skins in the _Skins_ folder in the Help+Manual program directory.
3. Now you can edit the settings of your skin. This is exactly the same as editing the corresponding sections of normal projects to configure your output.
Skins have no topics, you can only edit the relevant sections in the Configuration and Baggage Files sections in the Project Explorer and the text and table styles in Write > Styles.
[] Using subfolders for CSS, JS and image files
When you edit a skin in Help+Manual 10 and later you can activate an option to create separate subfolders for your JavaScript, CSS and image files. This function is available for both CHM and WebHelp/eWriter skins.
Important: Changing this setting requires skin editing\!
Enabling this option in the skin causes Help+Manual to generate subfolders and store all corresponding files within them. However, it does not—and cannot—automatically update the references within the skin templates and code. If you simply change this setting in an existing skin without also updating the references in your skin code to reflect the new file locations, you will encounter numerous errors in your output. While images in your topics will still display correctly, the skin’s user interface will be defective.
Location of the setting
This setting is only displayed when you are editing a skin. It is located in Configuration > Publishing > Output Folders. The standard folders are called CSS, JS and Images and these are generally recommended unless you have a specific reason for changing them.
No subfolder for topic files
Note that you cannot add a subfolder for topic files. These are always on the root level for a number of important reasons:
- In WebHelp, Google and other search engines provide the best indexing for content on the root level.
- Changing the location of the topic files in WebHelp would break all existing links to existing documentation.
- Changing the location of the topic files inside CHM files would also break any existing context links to the CHM file.
- In our WebHelp 3.0 format used in Premium Pack skins each topic file is a landing page and must be on the root level. (And anyway the Premium Pack skins already implement subfolders for JS, CSS and images.)
[] Using include conditions to configure features in skins
**(./images/flag_green.gif) Key Information**
Include options in skins must be defined in the skin\! Include options defined in normal H+M projects will not be saved in the skin when you save the project as a skin. You must edit the skin file and add the include options you want to use.
**For advanced users:**
You can use [include options](hm_advanced_htmltemplates_conditions.md) to turn features in skins on and off. This makes it possible for the user to choose features in the skin when they publish their projects because include options stored in skins are loaded into the _Include Options:_ box in the Publish dialog when the skin is selected.
For example, suppose you want to give the user the option of having a subtitle underneath the title in the table of contents in your WebHelp output. It would work like this:
1. Define an include option in the skin, let's say it's called OPT\_SUBTITLE, and let's also say that we've entered _TOC header subtitle_ as the include option description. ** **
2. Add code using the include option to the HTML template for the WebHelp table of contents, for example (you would also have to define the <%SUBTITLE%> variable in this example, of course):
````
<%TITLE%>
````
` <%SUBTITLE%>
`
3. When the user loads the skin in the Publish dialog the option _\[ \] TOC header subtitle_ will automatically be loaded from the skin file and displayed in the _Include Options:_ box. The header will only be displayed if the user selects this option.
You can take this concept as far as you like: For example, you can use the same include option to change the CSS definitions in the same HTML template so that the formatting will be different depending on whether the subtitle is included or not.
[] Including a preview image in a skin
When the user selects a skin in the Publish dialog Help+Manual automatically looks for a PNG graphic file called `\$HMSKINPREVIEW.PNG` in the skin's Baggage files. If this file is found a thumbnail version of the preview image is displayed in the Publish dialog. The user can then click on this image to display a full-size preview.
1. Create your preview image – this will generally be a screenshot of a help file using your skin – and save it in the PNG format as `\$HMSKINPREVIEW.PNG.`** **
2. Add the PNG preview file to the Baggage Files section of your skin.
3. Select the PNG file in the Baggage Files section, right-click on it, select Include in Builds and deactivate all build options for the file. This will prevent the file from being exported to your published output, where it is not needed.
[] Using skins to redefine variables and other settings
You don't have to save all your settings in your skin files. For example, it's possible to create a skin that only defines the user variables in your project – you just need to deselect everything except Variables when you save the skin file. Then you can redefine your variables in your entire project by selecting the skin file when you publish your project.
You can do the same with your Baggage files, text and table styles, HTML Page Templates or any combination.
[] Applying multiple skins in command lines and batch files
When you publish manually you can only select one skin for the project you are publishing. However, when you use Help+Manual's command line options you can specify as many skins as you like one after another.
When you do this the settings in the last skin you specify always have priority for duplicate settings – for example, if you redefine the same variables in two skins the settings in the second skin are those that will be applied.
See [Command Line Options](hm_advanced_commandline.md) and [Skins \& redefining variables](hm_advanced_commandline_variables.md) for more information on this.
See also:
[The Publish Dialog](hm_ref_ribbon_file_publish.md)
[Command Line Options](hm_advanced_commandline.md)