Wikimedia's Shiro Theme
This theme was originally forked from the Reaktiv Studios starter theme and Underscores with quite a few additions. The following documentation runs through the basics of the theme and any commands you may need to follow.
Folder Structure
The basic folder structure keeps things fairly simple and organized by type.
The assets
folder contains front-end files in the src
sub-directory. Any files that need to be generated or built from source are output into dist
, and files are enqueued by the theme from that directory.
The inc
folder contains all PHP files that aren't required in the root directory by WordPress.
The template-parts
folder contains template parts used by larger templates in the root directory.
Deploy Process
The release and release-develop versions of the Shiro theme are built using GitHub Actions. Any time a pull request is merged into the main
or develop
branches, that code is built and pushed to the corresponding release
and release-develop
branches. You should not commit to the release branches directly, nor submit pull requests against them.
Development workflow:
- Implement a feature or bugfix in a feature branch created off of
main
- Submit a pull request from that feature branch back into
main
, and get code review - Merge the feature branch into
develop
manually.- The
release-develop
branch will be automatically rebuilt
- The
- Update the preproduction or development environment for your project to reference the newest built version of the
release-develop
branch, to deploy and test the theme PR. - Once approved, merge the pull request into
main
- The
release
branch will be automatically rebuilt
- The
- Update the production branch in your project repository to reference the newest built version of the
release
branch, to deploy the change to production.
Build Process
This theme uses Gulp & Webpack for all its build process needs. They will help you to concatenate, lint and build your files. This also includes livereload, which will automatically inject CSS changes, and reload the live page whenever changes are made to JS or PHP files.
The following tasks are available to you:
-
npm run build
This builds out the assets and runs the following tasks:styles
,scripts
-
npm run lint
Lints JavaScript and (modified) PHP files. -
npm run lint:js
Lints only JavaScript usingeslint
-
npm run lint:php
Lints only PHP files which have changed in the current branch, usingphpcs
. To run PHPCS on all files, runcomposer phpcs
. -
npm run start
Begins watching front-end assets (scripts and styles) and compiles them when changed. This will also start the livereload script, which refreshes the page when changes are made. -
npm run download-style-guide-sass
Download the variables file in the style-guide. This is only required when the style guide has changed.
Important
This theme's dependencies currently require Node 14. If you use nvm to manage your local Node install, you may run nvm use
to select the appropriate Node version for the commands above.
CSS
CSS should follow the BEM naming convention and files should be clearly commented.
JS
JS should follow the project linting standards, which are based on the WordPress core coding standards and Human Made coding standards. In addition, please use JSDoc to document functions.
Due to evolving JavaScript best practices over the lifecycle of this project, different pieces of JS code are held to slightly different coding standards. ESLint is configured in .eslintrc
.
PHP
PHP should follow the WordPress coding standards. PHP Codesniffer is configured in phpcs.xml
.
Icons
An SVG icon system has been included as a sprite sheet generated by gulp with gulp svg
. In order to keep the file size of this sprite down, only icons which are added to the theme's assets/src/svg/individual
folder are compiled and included in this sprite file. The compiled icon sprite is located at assets/dist/icons.svg
. Instructions on how to add additional icons to this sprite are included below.
Using icons in the theme
The helper function wmf_show_icon
is available to make using icons as simple as possible. The parameters for this function are the name of the SVG to display and optional classes to add. The name matches the name of the original SVG file.
wmf_show_icon( 'search' );
When the SVG is output, it will include the icon
and icon-{icon-name}
CSS classes so that it can be targeted and styled.