Support

Documentation pages for using Creodocs.


  • Manual Entry

Adding a Template to Creodocs

This page takes you through the process of adding a template or updating an existing template with a new version. Templates must be submitted in the format detailed on the Template Specifications page. Upon submitting your new template, the following steps must occur before it is available for creating documents:

  1. Validation of template and specifications
  2. Report on critical issues with template specifications
  3. Report on optional improvements to template specifications
  4. Test document creation

Submitting a Template

You can submit a new template from your Workshop or add a new version for an existing template from its Template Settings page. In both locations, you are presented with a simple form to upload a single file containing everything needed to use the template on Creodocs.

Templates must be packaged as a single zip file with a filename no longer than 100 characters, consisting of alphanumeric characters, dashes, underscores or periods. The maximum file size of templates is 20MB to minimise document creation time. The zip file can contain sub-directories for template assets such as images or fonts, but the following two files must be present at the root level: a main.tex template code file and a creodocs.json template and variable specification file.


Step 1. Validation of Template and Specifications

The creodocs.json file contains information about both the template itself and the variables present within it. This information is critical for classifying the template and interacting with its LaTeX code, so this file is the first to be validated for quality. Being a JSON file, it must contain valid JSON syntax and it is recommended to copy the contents of the file into an online JSON validation tool prior to submitting the template. Something as small as a missing quotation mark or bracket is enough to break a JSON file, so mistakes can occur frequently. Template and variable information is extracted from the creodocs.json file to be validated against the template code.

Template code that is parsed for variables and variable groups includes all TeX .tex, class .cls and style .sty files in the template (including recursively in sub-directories). Variables and groups can be specified anywhere in these files. Variables always occur on a single line but groups can span any number of lines. The same variable or group can occur in multiple places in one file and within multiple files. The only restriction is that all variables in a multi-group must always be present in a group together, but their order within the group can change when the multi-group is used more than once.

At least one variable must be present in at least one TeX file. All variables in the variable specification must be used at least once in the template files and no variables can be used in the template files that aren't defined in the specification.

Step 2. Critical Errors Report

Critical errors are issues that prevent a template from being usable in its submitted state. This could include: missing/invalid required information about the template, incorrect variable usage in the code, or something else of similar importance. Any critical errors found during the validation of a new template will cause the template addition to fail. This means the uploaded template will be deleted and you will be presented with a report of the issues identified so you can correct them and resubmit.


Step 3. Optional Improvements Report

During the validation of the specifications and template code, the submitted template is also scanned for improvements that could be implemented that would make it more user-friendly. If no critical errors are found, a report of these improvements is displayed after the template is saved.

You will be presented with the option to act on the suggested improvements and update the template by submitting a new version to overwrite the original one, or you can can disregard the suggestions and continue to the next step.


Step 4. Creating a Test Document

The final step of adding a template is to produce a test document to validate the template code. The demo_value variable values from the specifications will be used as the document data to produce a test document using the typesetting engine from the specifications. The resulting PDF document and typesetting log will be presented to you for inspection.

If any critical errors are issued by the typesetting engine which preclude the creation of a document PDF, you will only receive the typesetting log to diagnose the problem and you will be unable to approve the test document.

You should carefully look over the test document and logs to validate that there are no issues. It may be helpful to use demo variable values that show off the functionality and layout of the template rather than using the variable names. This is especially true as the preview image for the template is automatically created using the first page of the test document once you accept the test document.