Skip to content

Latest commit

 

History

History
87 lines (71 loc) · 4.01 KB

ARCHITECTURE.md

File metadata and controls

87 lines (71 loc) · 4.01 KB
Raw

Architecture

This project has two major domains:

  • tool: Concerning data.
  • site: Concerning presentation.

Tool

The roar tool is written in Go, and lives in the root of the repository. That is, the repo itself is the roar Go module. The implementation of the command-line program lives under cmd/roar.

The roar tool gathers data about the Roblox engine API from multiple sources. It is generally structured such that each subdirectory is a package that handles one source of data.

Data is formatted in a way that can be understood by Hugo. This mostly takes the form of data templates, which live under site/data. The tool also generates minimal content files representing pages for each API entity, which live under site/content. It also generates several types of assets that live under site/assets.

Site

The site directory represents a site (mostly) ready to be processed by Hugo. It contains everything needed to produce a website, except for the files generated by the roar tool. A typical procedure for generating a complete website might have the following steps:

  1. Prepare a copy of the site directory.
  2. Run the roar tool on the directory to generate the data.
  3. Run Hugo on the directory to generate the final website.

The .gitignore file indicates the locations of files that are expected to be generated by the roar tool.

HTML

The generation of HTML is handled by Hugo templates. The site is themeless; everything is handled directly through the layouts directory, which has the following subdirectories:

  • _default (Hugo): Contains default templates for when a more specific template is not defined.
  • shortcodes (Hugo): Templates that can be invoked by content pages.
  • partials: Templates that can be used by other templates. Contains the bulk of non-Hugo roar-specific architecture. Templates are organized roughly by subject.
  • Directories for each content type, which contain templates applying only to the corresponding type of page.

JavaScript

JavaScript is handled entirely through Hugo's js.Build function, which deals with bundling, transpiling, tree shaking, and minifying. Very handy.

The structure for JavaScript is relatively simple. All JavaScript files live under site/assets/js. main.js is used as the main entrypoint, and other files are imported through it directly or indirectly. An exception is quick-theme.js, which is meant to run as soon as possible so that the user's configured theme is presented without artifacts.

A guiding principle of JavaScript-use is to enhance only. The website should be entirely usable without JavaScript, and JavaScript should be used only to enhance the experience.

CSS

CSS is handled through Hugo's toCSS function, which transpiles SASS into CSS using the version of LibSass embedded into the extended version of Hugo. While Hugo is able to utilize DartSass, this requires installing it separately. For now, this is avoided to keep dependencies low.

All CSS files live under site/assets/css. The main entrypoint is main.scss, which typically contains only import statements.

The bulk of the CSS architecture consists of the following concepts:

  • variables: Defines global CSS variables.
  • mixins: Defines SASS mixins.
  • themes: Defines variables for theme colors.
  • layouts: Defines layouts for different viewport sizes, as well as classes related to these layouts. More information in layout.scss.
  • components: Independent reusable components identified by the class attribute. Some components may have a corresponding partial template.
  • singletons: Specific elements identified by the id attribute. Some singletons may have a corresponding partial template.
  • pages: Involves specific pages or page types. Identified by classes generated on the body element.