Tiara's HTML Theming Reference

This project is a HTML theming reference implementation for CSS-first, frameworkless, static, modular, yet modern and contemporary HTML-theming for traditionalist UNIX & GNU enthusiasts. It contains a complete workflow for developing and distributing tested, decoupled, optimized and documented assets for theming HTML documents. It has minimal build environment requirements and UNIX-principled choices of matured build subsystems were made, avoiding dependencies wherever possible.

This HTML theme is not a standalone component, even though it provides a functional usability demonstration. Its output is meant to be integrated into other components, say a Sphinx, or Wordpress theme.

This project serves as a personal reference implementation and demonstration of HTML document theming principles. It is shared in the spirit of openness, with no immediate plans for external contributions.

Requirements

Build environment

The build environment requires the following programs:

• Git >=2.14
• GNU Autoconf >=v2.69 (optional, required only for maintenance)
• GNU Make >=v4.2.1
• Node.js >=v20.11.0
• npm (any version supported by Node.js)

Integration

The web engine/browser displaying HTML documents themed with this reference implementation MUST support (at least) the following standards:

• (WHATWG) HTML Living Standard
• ECMAScript 2015 (ES6)
• CSS3 (exhaustive, it's gotten pretty difficult to assess properly)

Usage

Generate distribution

$ sh ./configure

It automatically checks for required programs. If any are missing, the script halts and provides guidance on how to resolve the issue.

$ make

That's all. You will find a tarball distribution under dist/, including a usability demonstration under package/docs/ inside the tarball.

To exclude the usability demonstration, execute the following:

$ make NO_DOCS=1

In order for tests not to be run, execute the following:

$ make CI=1

This asserts, you are executing test targets separetely, such as in the case of integrating with CI services.

For local user acceptance testing, execute:

make uat

Refer to Makefile for insights into my development principles and workflows. Documentation is scattered throughout the sources and each directory within this repository.

Use distribution

Acquire the distribution, untar everything in the archive listed in package/assets.txt. Note that the paths specified in package/assets.txt are relative to package/.

NOTICE: Please refer to Continuous Integration for retrieving a distribution. You may currently download the artifact of the Dist step of any pipeline executed upon the master branch. This will change soon to Bitbucket Download artifacts, which is similar to GitHub releases.

In addition you'll find a usability demonstration under package/docs/ within it.

The distribution has been generated by a modified npm pack workflow (scripts/npm-pack.ts) as to not require an executable outside of the Node.js/npm runtime environment. This comes at the cost of having to adhere to the npm packaging layout, which results in the distribution being nested inside a package/ directory.

Continuous Integration

For an up-to date status on the health of this repository, you may check the status of the CI service:

byteb4rb1e / html-theme-ref Pipelines — Bitbucket

References

Useful references (in no particular order) that guided this reference implementation. This list is not exhaustive and will grow eventually. For explicit references on information about the tools used, R(Their)FM.

• Scalable and Modern Architecture for CSS (SMACSS)
• Sass: Syntactically Awesome Style Sheets
• Sass Guidelines - The 7-1 pattern
• OddBird True - Unit testing for Sass developers
• What is TSDoc? | TSDoc
• GNU Autoconf - Shellology
• HTML Standard - Semantics, structure, and APIs of HTML documents
• Concepts | webpack
• Rules | stylelint
• Rootless Root - The UNIX Koans of Master Foo
• Accessibility Fundamentals Overview | Web Accessibility Initiative (WAI) | W3C
• Understanding Success Criterion 1.4.1: Use of Color | WAI | W3C
• Realtime Colors
• WebAIM Contrast Checker
• Browser Fingerprinting: An Introduction and the Challenges Ahead | The Tor Project

Issues

Vendor

Node.js | jest - deprecated dependencies

• affects npm install.
• results in deprecation notice during npm install.
• remediated by adding override in package.json for upgrading child dependencies.

Node.js | html-webpack-plugin - using wrong webpack hooks

• affects webpack-dev-server
• results in changes applied to watched files not emitting updated outputs
• likely an issue with incorrect usage of hooks for proper cache handling
• suggested workaround did not work
• remediated by instructing webpack-dev-middleware to write to disk, instead of handling changes solely in memory. This was my intended behavior anyway...

Node.js | ts-node - unable to correctly parse with ESM options

• affects npx ts-node scripts/*.ts
• results in scripts not being executed with error TypeError [ERR_UNKNOWN_FILE_EXTENSION]: Unknown file extension ".ts" for ..., if type in package.json is set to module.
• suggested workaround does not work
• (accidentally) remediated by setting type in package.json to commonjs. This is contradictory to the entire build environment being authored as ESM, but since I'm explicitly defining each module as an ESM module through the .mjs extension name (you've been hit by, you've been struck by a smooooth criminal 🕺), this will override the default behavior of the package.json

Licensing

Sharing is caring! This project is licensed under a Creative Commons Attribution 4.0 International License, as my focus is on monetizing services rather than products.

You should have received a copy of the license along with this work. If not, see https://creativecommons.org/licenses/by/4.0/.