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
• 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
• 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 using eslint

• npm run lint:php Lints only PHP files which have changed in the current branch, using phpcs. To run PHPCS on all files, run composer 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 by running gulp or npm run build-spritesheet within the assets/src/svg folder. This is segregated from the rest of the build because this asset rarely changes, and because the sprite generation relies on Gulp when the remainder of the build has been migrated to wp-scripts.

In order to keep the file size of this spritesheet 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 asset is generated in assets/src/svg/spritesheet and copied to assets/dist/icons.svg as part of the main build.

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.

Additional Documentation

• Code repository wiki
• Meta-Wiki page