As mentioned in the best practices, it is not advised to modify the default templates provided with HelpNDoc usually located in the "program files" directory. Furthermore, some templates might need only subtle changes to a subset of the files to suit the requirements. That's why HelpNDoc introduces the template inheritance concept where a template can "inherit" from a parent template, thus using all its template files, and only override the required files.
Inheriting from a parent template
From the final children template, just add the "inherits" key in the template.info file's "config" section and mention the parent template's name as the value. As an example:
inherits=Default HTML Template
This configuration file instructs HelpNDoc to use the template named "Default HTML Template" as the parent template. Only template files from the same documentation format can be used as a parent template.
Overriding a template file
To change the content of a file, just place a file with the same name in the same directory within the child template. HelpNDoc will use this file instead of the one from the parent template. As an example, if the parent template contains the file "index.pas.html" it is possible to override this file by creating a file named "index.pas.html" in the child template's folder with alternative content.
How is it working
At generation time, HelpNDoc reads the template selected for the project. If that template inherits from a parent template, HelpNDoc will first generate a new temporary template as follows:
- The parent template's entire content is copied into a temporary folder;
- The child template (the one selected for the documentation generation) is copied over this parent template, replacing any duplicate file if required;
- The template.info files are merged to preserve the sections and keys from both templates, and override the duplicate ones using the child template's data.
Some limitations apply to the template inheritance feature:
- It is not possible to inherit from a template from a different documentation format: an HTML template can't inherit from a CHM template and a Word template can't inherit from a PDF template for example;
- It is not possible to remove files from the original template, just add or override existing files