Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
167 lines (115 loc) · 4.04 KB

CONTRIBUTING.md

File metadata and controls

167 lines (115 loc) · 4.04 KB
Raw

Contributing

Quick reference

Stack:

  • Blog: Jekyll (Ruby)
  • CLI scripts to help manage the theme: Node.js (TypeScript + Playwright e2e tests)

Known gotchas

  • Sass @import deprecation: The theme intentionally uses @import (not @use). This is blocked by GitHub Pages / jekyll-sass-converter 1.5.2 using Ruby Sass 3.7.4. Do not migrate to @use yet. quiet_deps: true in _config.yml silences Font Awesome's own warnings.
  • Jest virtual mocks: External packages not in .github/cli/node_modules must be mocked with jest.mock('pkg', factory, { virtual: true }).
  • CSS variables for theming: Light/dark mode and skin colors are all CSS custom properties defined in _sass/base/_variables.scss. The data-theme attribute is set by JavaScript in head.liquid on page load.
  • Remote theme vs gem: _config.yml has both remote_theme and theme (commented). For local dev the gem is used; for GitHub Pages the remote_theme is used.
  • Jekyll exclude list: package.json, package-lock.json, and .github/ are excluded from Jekyll build. Any new tooling files at root should be added to the exclude: list in _config.yml.
  • Gem includes: The gemspec in type-on-strap.gemspec only includes assets/(js|css|fonts|data)/, _(includes|layouts|sass)/, and _data/(icons_builder|language).yml. Content files (_posts/, _portfolio/, pages/) are NOT shipped in the gem.

Prerequisites

  • Node.js >= 18 and npm — for the CLI tooling and tests
  • Ruby and Bundler — for running Jekyll locally

Install Node dependencies from the project root:

npm install

Install Ruby dependencies:

bundle install

Blog commands

Using bundler instead of Jekyll directly.

bundle exec jekyll serve        # Serve locally at http://localhost:4000
bundle exec jekyll build        # Build to _site/

CLI scripts

All scripts live in .github/cli/src/ and are run from the project root.

Build

Minify JS:

npm run build        # minify JS
npm run build:js     # minify JS

Images

npm run compress         # compress images in place
npm run thumbnails       # create thumbnails for feature-img/ only
npm run thumbnails-all   # create thumbnails for all images
npm run webp             # convert images to WebP

Create a post

npm run post 'title of the post'

Creates _posts/YYYY-MM-DD-title-of-the-post.md with default frontmatter. Does nothing if the file already exists.

Vendor dependencies

Validate that local vendor files match their upstream sources:

npm run validate            # all vendors
npm run validate:katex
npm run validate:mermaid
npm run validate:fa
npm run validate:masonry
npm run validate:search

Update a vendor to its latest version:

npm run update:katex [version]
npm run update:mermaid [version]

Testing

Unit tests

npm test

Typecheck

npm run typecheck

End-to-end tests

Requires a built site (bundle exec jekyll build) and Playwright browsers (npm run playwright:install):

npm run test:e2e

Visual regression tests

Visual tests are tagged @visual and run against 5 browser/device projects (desktop Chrome, Firefox, Safari, mobile Chrome, mobile Safari).

Run only the visual tests:

npm run test:e2e -- --grep @visual

Or target a single browser:

npm run test:e2e -- --project=visual-chromium

Update the baseline screenshots when visual changes are intentional:

npm run test:e2e -- --grep @visual --update-snapshots

Git hooks

A pre-commit hook is provided that checks for non-staged assets before committing.

Enable it:

ln .github/hooks/pre-commit .git/hooks/pre-commit

Bypass it when needed:

git commit -n

Pull requests

  • PRs must remain compatible with GitHub Pages
  • Include a screenshot if the change affects the layout or visual appearance
  • Run npm test and npm run typecheck before submitting