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

Check out my issue tracker

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/.