{"id":14968539,"url":"https://github.com/psu-libraries/psulib_base","last_synced_at":"2026-02-13T17:11:43.562Z","repository":{"id":222337329,"uuid":"756941962","full_name":"psu-libraries/psulib_base","owner":"psu-libraries","description":"Drupal Base Theme","archived":false,"fork":false,"pushed_at":"2026-01-13T14:19:01.000Z","size":9768,"stargazers_count":0,"open_issues_count":17,"forks_count":0,"subscribers_count":3,"default_branch":"main","last_synced_at":"2026-01-16T07:15:35.122Z","etag":null,"topics":["drupal","theme"],"latest_commit_sha":null,"homepage":"","language":"Twig","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/psu-libraries.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2024-02-13T15:53:53.000Z","updated_at":"2026-01-13T14:19:03.000Z","dependencies_parsed_at":"2024-05-29T18:30:11.596Z","dependency_job_id":"c41b6fd3-8eb3-415b-b855-3e21f756ab31","html_url":"https://github.com/psu-libraries/psulib_base","commit_stats":{"total_commits":163,"total_committers":10,"mean_commits":16.3,"dds":"0.31288343558282206","last_synced_commit":"697c8d8fa66efc82c6fcdf0bfd2eccdf3478c8fb"},"previous_names":["psu-libraries/psulib_base"],"tags_count":96,"template":false,"template_full_name":null,"purl":"pkg:github/psu-libraries/psulib_base","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/psu-libraries%2Fpsulib_base","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/psu-libraries%2Fpsulib_base/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/psu-libraries%2Fpsulib_base/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/psu-libraries%2Fpsulib_base/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/psu-libraries","download_url":"https://codeload.github.com/psu-libraries/psulib_base/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/psu-libraries%2Fpsulib_base/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28634787,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-21T04:47:28.174Z","status":"ssl_error","status_checked_at":"2026-01-21T04:47:22.943Z","response_time":86,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["drupal","theme"],"created_at":"2024-09-24T13:40:05.286Z","updated_at":"2026-01-21T14:04:05.095Z","avatar_url":"https://github.com/psu-libraries.png","language":"Twig","funding_links":[],"categories":[],"sub_categories":[],"readme":"# PSU Libraries Base Theme (psulib_base)\n\nThis theme is intended to be used for PSU Branded Libraries Drupal sites.  This is based on the [Bootstrap 5](https://getbootstrap.com/docs/5.3/getting-started/introduction/) framework.\n\n## Development\n\nThis base theme is easiest to develop using a theme generated using the [drupal-site-template](https://github.com/psu-libraries/drupal-site-template) or using the site template itself.  This will use the psul-web site as an example.\n\n### New DDEV Environment\n\n```bash\ngh repo clone psu-libraries/psul-web;\ncd psul-web;\nddev start;\nddev composer install;\nddev drush si --existing-config;\nddev develop-theme;\nddev theme-build;\nddev launch;\n```\n\n### Existing DDEV Environment\n\n```bash\nddev develop-theme;\nddev theme-build;\nddev launch;\n```\n\n### Global SCSS\n\nSCSS used to generate styles that will be used everywhere are defined in the `./scss` directory.  Styles cannot or should be associated with a single components will live here.  These can be organized in to separate files in the `./scss/base` directory.\n\nTo compile the theme you will need install the node dependencies `npm install`.\n\n- `npx mix watch` to compile the scss/js and watch for addition changes (standalone)\n- `ddev theme-watch psulib_base` to compile the scss/js and watch for additional changes. This can only be used within a PSU Libraries Drupal site.\n\n### Storybook\n\nThis theme also includes the ability to stand up an instance of Storybook.  This is using the [Storybook SDC Addon](https://storybook.js.org/addons/storybook-addon-sdc) to pull the stories directly from the single directory components. Run `npm run storybook` to stand up a development version of storybook. This will also `npm mix watch` concurrently to update any scss or js changes live.\n\n#### Known issues with twig.js\n\nThe implementation of twig.js does not 100% match PHP Twig. There are few issues with the twig.js that need to be worked around.\n\n- `|merge` will only work if you merge a array literal into a array variable.  You also need to ensure that utility class array exists before merging.\n- `trans` is not defined.\n- macros need to be defined before they are used.\n- `attribute.removeClass()` remove the attribute entirely and cannot be used.\n\n#### Links\n- https://storybook.js.org/\n- https://storybook.js.org/addons/storybook-addon-sdc\n- https://github.com/iberdinsky-skilld/sdc-addon\n\n### Single Directory Components (SDC)\n\nThe theme has a number of [Single Directory Components (SDC)](https://www.drupal.org/docs/develop/theming-drupal/using-single-directory-components) defined in the `./components` directory.  We should use SDC where appropriate.  This allows for easier development and code reusability.\n\n#### Creating a template\nTo add a new components you will need to do the following.  This will create a SDC component for you to start with.\n\n```bash\nddev drush generate sdc\n```\n\n#### Applying the template\n\nIf your component is only using props then you can use an include:\n\n```twig\n{% include 'psulib_base:COMPONENT' with {\n  prop_name: variable,\n} %}\n```\n\nIf your component is using slots then you will need to use an embed:\n\n```twig\n{% embed 'psulib_base:header' with {\n    prop_name: variable,\n  }\n%}\n  {% block slot %}\n    {{ page.region }}\n  {% endblock %}\n\n{% endembed %}\n```\n\n#### Replace a SDC in a Sub Theme\n\nIf you want to completely override a SDC in a subtheme you can do with the following steps:\n\n1. Copy the component from the base theme to the subtheme\n1. Add `replaces: psulib_base:COMPONENTNAME` to the `COMPONENTNAME.component.yml` file\n1. Update templates, css, twig, e\u0026c.\n\nNote you should NOT change the props or slots because that will cause issues.\n\n#### Replace SCSS for a SDC\n\nIf you only need to change the styles for a SDC you can remove the SDC css file and build the desired styles in your subtheme SCSS.  There is an open ticket to implement a better way of handling this so we should probably avoid doing this for the time being.\n\n1. Update your `subtheme.info.yml` file to override the component stylesheet.\n```\nlibraries-override:\n  core/components.psulib_base--COMPONENTNAME:\n    css:\n      component:\n        ../../../themes/custom/psulib_base/components/COMPONENTNAME/COMPONENTNAME.css: {}\n```\n1. Add styles to your subtheme style sheet.\n\n#### Links\n\n- [SDC Documentation](https://www.drupal.org/docs/develop/theming-drupal/using-single-directory-components)\n- [Using/Attaching only css/js](https://www.drupal.org/docs/develop/theming-drupal/using-single-directory-components/faq-frequently-asked-questions#s-can-i-use-attach-only-the-assets-library-cssjs-of-a-component-inside-a-twig-template)\n- [Radix Theme](https://git.drupalcode.org/project/radix/-/tree/6.0.x/components?ref_type=heads) - This theme has large number of components that can be used as inspiration.\n\n## Using this Theme\n\nThe psulib_base theme can be used as a standalone theme but can also act as a base theme if custom styles are required.    There are 3 ways to use this base theme, which are listed below.\n\n### Installing\n\nTo use this base theme, you must first add the base theme repository in your site's composer.json (either manually or with this command):\n\n```bash\nddev composer config repositories.psul/theme-base github \"https://github.com/psu-libraries/psulib_base.git\"\n```\n\nThen, require the actual base theme:\n\n```bash\nddev composer require psu-libraries/psulib_base\n```\n\nand install it with Drush\n```bash\nddev drush theme:enable psulib_base\n```\n\n### Standalone\n\nIf you are using this as a standalone theme then you will need to run the following command after the theme has been installed.\n\n```bash\nddev drush config-set system.theme default psulib_base;\n```\n\n### Base Theme Extended Styles\n\nIf you want to use all styles in the base theme BUT add additional styles for your site.  You will be able to use scss `variables` and `mixins` but NOT `extends` as the\n\n```bash\nddev generate-subtheme SUBTHEMENAME;\n```\n\nUpdate the styles.scss with the following.\n\n```scss\n// Include bootstrap.\n@import '../../../../themes/contrib/psulib_base/scss/init';\n\n// Sub theme styling.\n```\n\nUpdate `webpack.mix.js` file to add alias for bootstrap and exclude base theme specific components. This should look like the following.\n\n```js\n// webpack.mix.js\n\nlet mix = require('laravel-mix');\nconst path = require('path');\n\nmix.alias({\n  'bootstrap': path.join(__dirname, 'node_modules/bootstrap')\n});\n\n// Use relative URL so fonts will work.\nmix.sass('scss/style.scss', 'dist/css')\n    .options({\n        processCssUrls: false\n    });\n\n// Combine custom javascript into the application.js file.\nmix.combine('js/base', 'dist/js/application.js');\n```\n\n### Base Theme Override Styles\n\nIf you want to override ALL styles coming from the base theme.\n\n```bash\nddev generate-subtheme SUBTHEMENAME;\n```\n\nUpdate the styles.scss with the following to re-build the styles in the base theme. (**THIS NEEDS WORK. The scss does not allow you to override variables.**)\n\n```scss\n// Include bootstrap.\n@import '../../../../themes/contrib/psulib_base/scss/style';\n\n// Sub theme styling.\n```\n\nAdd the following to the subtheme `*.info.yml` file to exclude the base theme library so styles are lot loaded twice:\n\n```yaml\nlibraries-override:\n  psulib_base/global-styling:\n    css:\n      theme:\n        dist/css/style.css: {}\n```\n\nUpdate `webpack.mix.js` file to exclude base theme specific components. This should look like the following.\n\n```js\n// webpack.mix.js\n\nlet mix = require('laravel-mix');\n\n// Use relative URL so fonts will work.\nmix.sass('scss/style.scss', 'dist/css')\n    .options({\n        processCssUrls: false\n    });\n\n// Combine custom javascript into the application.js file.\nmix.combine('js/base', 'dist/js/application.js');\n```\n\n## Boostrap Icons\n\nSince there is no current CI/CD process to build out the assets on demand, the bootrap icons are copied into the target theme on npm install.\n\nThere is a postinstall script to copy fonts/icons into ./assets/bootstrap/fonts\n\nOnce this has run you can use it as documented on https://icons.getbootstrap.com:\n\n```html\n\u003ci class=\"bi-alarm\" style=\"font-size: 2rem; color: cornflowerblue;\"\u003e\u003c/i\u003e\n```\n\n## Material Icons\nMaterial Icons can be used. These are saved as SVGs in the theme.\n\n### Usage\n- TBD.\n\n### Adding Icons\n- Go to https://fonts.google.com/icons?icon.style=Rounded\u0026selected=Material+Symbols+Rounded:group:FILL@0;wght@400;GRAD@0;opsz@24\u0026icon.size=24\u0026icon.color=%23005FA9\u0026icon.query=group\u0026icon.set=Material+Symbols\n- Find and download the desired icon svg\n- Rename the svg to something simple (the file name is used to find the icon)\n- Add the file to assets/icons\n- Update `components/icon/icon.component.yml` to update\n- Update `stories/icon-usage.stories.js` with details about how the icon shoudl be used withing the libraries site\n\n## Peripheral\n\nThe theme can be used to generate assets that can be used on peripheral applications. This requires that the application in question supports bootstrap.\n\n- Run `ddev theme-build`\n- Copy the `dist/peripheral` directory into the `src/psulib_base/dist` directory in the `psu-libraries/assets` project.\n- Copy the `dist/bootstrap-icons` directory into the `src/psulib_base` directory in the `psu-libraries/assets` project.\n- Copy the `assets` directory into the `src/psulib_base` directory in the `psu-libraries/assets` project.\n\n## Resources\nFor more information about creating a subtheme:\n- [Drupal.org - Subtheming](https://www.drupal.org/node/2165673)\n- [Drupalize.me - Use a Base Theme](https://drupalize.me/tutorial/use-base-theme)\n- [Bootstrap 5 Documentation](https://getbootstrap.com/docs/5.3/getting-started/introduction/)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpsu-libraries%2Fpsulib_base","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpsu-libraries%2Fpsulib_base","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpsu-libraries%2Fpsulib_base/lists"}