roblib_ill_theme/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

What this is

A Drupal 9/10/11 custom theme for the Roblib ILL (interlibrary loan) site. Based on the stable9 base theme. It's a fork/customization of "The X" base theme (see README.txt, changelog.txt, credit.txt).

Key naming gotcha: the directory is roblib_ill_theme but the theme's machine name is ill. All the config files (ill.info.yml, ill.libraries.yml, ill.theme, ill.breakpoints.yml) and the Twig namespace (@ill/...) use ill. Don't rename one without the other.

Common commands

Local dev with browser-sync

The intended local workflow proxies a DDEV site and live-reloads on CSS/JS changes:

node bs.js

bs.js is hardcoded to proxy https://drupal-theme-dev.ddev.site and watch css/**/*.css and js/**/*.js. Edit bs.js if your local Drupal URL differs.

Deploy

./deploy.sh "commit message" does the full deploy: git add --all, commit, push, then SSH to the production server (137.149.52.34), git pull in the theme dir, and run drush cr. Edit the SERVER/THEME_DIR/SITE_ROOT/DRUSH_PATH constants at the top for new environments. Requires SSH key auth set up in advance.

Drupal cache

After Twig template, library, or .theme changes on a running site, the cache must be cleared (drush cr). The deploy script does this automatically; locally you'll need to run it yourself.

Build/lint scripts (currently non-functional)

package.json declares yarn scripts for PostCSS / Babel builds, stylelint, and prettier (e.g. yarn build, yarn watch:css, yarn lint:css). These scripts reference ./scripts/css/... and ./scripts/js/... which do not exist in this repo. Don't run them expecting them to work; CSS and JS in css/ and js/ are edited and shipped directly. If a build step gets restored later, the package.json declarations show what was intended.

Architecture

Theme entry points

• ill.info.yml — declares regions (header_top_left/right, header, primary_menu, search_box, page_header, highlighted, content, content_top/bottom, content_home_top/bottom, sidebar_first/second, footer_top, footer_one..four, footer_bottom_left/right/last, hidden) and pulls in the ill/global-styling library.
• ill.libraries.yml — defines the libraries. global-styling lists every CSS file in css/ individually (base, layout, then ~15 component files); js/ill.js is the only JS, and it depends on core/jquery. Additional libraries are defined for book, fontawesome4, fontawesome5, bootstrap-icons, and maintenance.
• ill.theme — only three preprocess hooks: ill_preprocess_page (exposes site_name, site_slogan, base_path, scrolltotop_on), ill_preprocess_breadcrumb (appends current page title to the breadcrumb trail and sets breadcrumb_icon_style = '/'), and ill_preprocess_html (exposes is_front).
• ill.breakpoints.yml — three breakpoints: mobile, narrow (560–850px), wide (≥851px).

Template structure

templates/layout/page.html.twig is the assembly point: it conditionally {% include %}s partials from templates/template-parts/{header,footer,sidebar,content-parts,components}/ using the @ill namespace. When adding regions or restructuring page chrome, edit page.html.twig and add the matching partial under template-parts/.

Other template subdirectories (block/, content/, content-edit/, dataset/, field/, form/, misc/, navigation/) hold standard Drupal template overrides (e.g. breadcrumb.html.twig, menu.html.twig, book-navigation.html.twig).

CSS organization

Many small files in css/, each loaded explicitly by ill.libraries.yml (so adding a new CSS file requires registering it there or it won't load). Roughly organized by page region (header.css, footer.css, sidebar.css, node.css) and concern (base.css, layout.css, responsive.css, components.css, shortcodes.css). Several large vendor files are vendored in (bootstrap-icons.css, font-awesome.css, font-awesome5.css, fontawesome5.css).

JS

js/ill.js is jQuery-based (jQuery(document).ready(...)) and handles: mobile menu toggle, header search box open/close (with click-outside and Esc handling), and scroll-to-top button visibility. No build pipeline — edit and ship.

Block placement config

config/optional/block.block.ill_*.yml defines default block placements (branding, breadcrumbs, content, footer, help, local actions/tasks, main menu, messages, page title, powered, search, tools, account menu) so that a fresh install of the theme has a sane out-of-the-box layout.