Project specifications

This section describes the various specifications you need to be aware of as you read the code or contribute towards the codebase.

Naming conventions

There are few standard naming conventions followed throughout the project for files of different types. Adhering to these is crucial to keep the codebase standardised and professional.

General rules

• All file names should be in lowercase
• If the file name contain more than one word, use kebab casing to split the word

HTML files

• The HTML (layout) file for a particular page determines the corresponding names of its corresponding content and CSS files
  • E.g. If the events page is rendered from an HTML page that goes by events.html, the corresponding content and CSS files would be events.md and events.css respectively, unless nested in other subdirectories. In that case, the content directory containing the events data should be named events/ itself.

Markdown files

• As much as possible, keep the file name same as the title of the markdown file

CSS files

• They are named in accordance with the corresponding layout file, unless otherwise required
• There is one exception to the above rule. The index.css file contains base CSS for the whole website, CSS related to common partials (like the header, footer, etc., and global CSS variables.

Asset management

• Any asset that can be grouped with one more assets of the same type should be placed in its own directory (or placed into an existing one)
• It is recommended to upload icons in the .svg format as it prevents loss of quality

Frontmatter for content files

• The format of the frontmatter of markdown files is crucial to serving the correct data to the website. Any inaccuracies give rise to the possibility of website crashes.
• The archetypes/ contains the template to be followed for each kind of markdown file present in the project. By default, any markdown content file follows the default.md format template.

Adding a new content file

There are two ways new content files can be created for the website.

• Copy-paste-and-update This is a high risk method but allows non-tech contributors to make changes to the content on the website

  • Identify the target directory where the new markdown file has to be added
  • Create a new file <file-name>.md that conforms to the above mentioned file naming conventions
  • Copy the frontmatter from another file in the same directory (or of the same type) and paste it in the new file
  • Modify the values of the frontmatter fields appropriately and add new content

• The Hugo way

  • Run the hugo new <directory-name>/<file-name>.md command
  • Examples
    • hugo new events/example.md adds a new file in the events/ directory with the required frontmatter as specified in its archetype file
    • hugo new careers/example.md adds a new file in the careers/ directory with the required frontmatter as specified in its archetype file