Customizing the Template

When filling out a file location for the template-json input, any members that points to a file location specified in that template.json file, it will override the premade template's code with the code provided in that file provided. You can use this to customize the premade template and generate the information you want in the way you want it to.

Recommended Practice: Download and look at the files in the premade template (they should be .zip files and should be publically available). Understand the format of the file you're trying to override and work off of that. Also recommended is to create a private repository and test out how your template files will generate documentation before implementing it into your desired repository.

Typically, creating the template.json file and all it's underlying template code should be placed in a private folder where GitHub pages won't process and make available publically (website-wise). To do this, make a folder outside of where GitHub pages is set up. Alternatively, create a new folder called _template located where GitHub pages is set up. The underscore prefix tells GitHub pages (jekyll) not to look into that folder.

To create your own templates, please get acquainted with the EJS templating framework, the Template URIs JSON format for details on the contents of the template.json, and look into the Template API for further understanding of the variables and functions implemented in each individual template.

Example Template

As an example, let's say you are using the default template and want to override the header and method templates. Create a new file, template.json and place it into your folder (typically in the _template folder inside where GitHub pages is set up). Then in your template.json you would write the following:

{
	"header": "header.ejs",
	"method": {
		"compact": "method-compact.ejs",
		"full": "method-full.ejs"
	}
}

With this template.json created, create three separate .ejs files: header.ejs, method-compact.ejs, and method-full.ejs. Place these files in the same folder as the template.json. Files specified in the template.json are relative to where the template.json file is located.

Contents of header.ejs

For the contents of header.ejs, type in the following and play with it:

<h1><%= project.name %></h1>
<h2><%= project.description %></h2>
<h3>This is a custom header!</h3>

Contents of method-compact.ejs

For the contents of method-compact.ejs, type in the following and play with it:

<tr>
	<td>
		<a class="name" href="#<%= getIdFrom(details); %>">
			<%= details.name %><% details.genericDeclaration %><% details.parameterDeclaration %>
		</a>
		<%- xmlDocs.summary %>
	</td>
</tr>

Contents of method-full.ejs

For the contents of method-full.ejs, type in the following and play with it:

<div>
	<div class="doc-desc">
		<%- xmlDocs.summary %>
	</div>
	
	<div class="declaration">
		<%- codeDeclaration %>
	</div>
	
	<% if(xmlDocs.parameters.exists) { %>
		<h4>Parameters</h4>
		
		<div class="padded-content">
			<% xmlDocs.parameters.value.forEach(function(parameter) { %>
				<div class="param-id">
					<span class="param-type">
						<%- createAnchorToType(getParameterType(details.parameters, parameter.name)); %>
					</span>
					<span class="param-name"><%= parameter.name %></span>
				</div>
				<div class="doc-desc">
					<%- parameter.description %>
				</div>
			<% }); %>
		</div>
	<% } %>
</div>

That's it!

With those four files created and the template.json linked to the workflow input, you have now successfully overriden the premade template for your repository! Congratulations!

If you want to continue to tinker around, do so at your leisure as any of the template pages can be overriden by the user including which CSS and JS files are included! For more information please check out the Template URIs JSON format as it will give more details on the contents of a template.json.

If you want to create your own premade template, please follow the guide on creating your own premade template.