Skip to Main Content
17/23

Customizations

Tagging Customized Files

Any files outside of the content directory, or that are .js or .css / .scss files within the content directory (other than custom.css and variables.scss), that are customized or changed in any way for a specific book project need to be marked as such. Do this by adding a comment to the top of the file itself, and by listing the change in the project’s README file. The specifics are detailed here, but you can also look at past projects for examples in use.

For the README file, list the relative file path and filename of the customized file in bold, and then on the next line include a brief description of the customization made. Group files together in cases where multiple files where changed to achieve a specific customization. 

## Customizations

          **_includes/components/copyright/licensing.js**
          Updated the language around exceptions

          **_includes/components/menu/item.js**
          **_includes/components/table-of-contents/item/list.js**
          **_includes/components/table-of-contents/item/grid.js**
          Don't render menu or TOC links if page is landing: false

          **_includes/components/object-filters/object-filters.webc**
          Add formatOptionLabel function to strip out custom sort encoding for date ranges

          **_layouts/cover.liquid**
          Added publication.cover_title in place of the default title

For the comment in the file itself, it should always be at least four lines, following the pattern below.

  • First line: Blank
  • Second line: “CUSTOMIZED FILE” in all caps
  • Third line: Brief description of the change made, line number(s) where the change was made
  • Last line: Blank

For the description, use the same as included in the README file. Add additional lines here for any additional changes made in the file.

Javascript

Most template files are written in Javascript (.js). Below is an example of how a customization would look at the top of a Javascript file. The double slashes // make this text a comment so that it doesn’t interfere with the code. 

//
// CUSTOMIZED FILE
// Updated the language around exceptions, line 20
//

Liquid

A few template files are written in Liquid (.liquid). Below is an example of how a customization would look at the top of a Liquid file. In Liquid files you use {% comment %} and {% endcomment %} for commenting out text. 

{% comment %}
          CUSTOMIZED FILE
          Added page layout and order to debug messaging, line 30
          {% endcomment %}

Liquid with YAML at the top

Many of the Liquid template files are the primary layout templates. These have a block of YAML at the top. Below is an example of how a customization would look at the top of a Liquid file that has YAML at the top. Note that you have to maintain the top three dashes on the top line, this starts the YAML block. And then instead of using {% comment %} and {% endcomment %}, you use ## which is the syntax for commenting in YAML files. 

---
## CUSTOMIZED FILE
## Added publication.cover_title in place of the default, line 25
##

Web Components

A few template files are written as web components (.webc). Below is an example of how a customization would look at the top of a web component file. In these files you use the HTML standrd <!-- and --> for commenting out text. 

<!--
            CUSTOMIZED FILE
            Add function to strip out encoding for date ranges, lines 84–90
          -->

Custom CSS

TK

Prototype Branch

TK