Skip to content

Latest commit

 

History

History
262 lines (172 loc) · 6.6 KB

README.md

File metadata and controls

262 lines (172 loc) · 6.6 KB
Raw

Mediacurrent Theme Generator

The Theme Generator is a scafolding tool built by your friends at Mediacurrent, which lets you quickly set up a Drupal 8 or 9 theme with sensible defaults and best practices.

Using the Theme Generator

While the theme generator can be run anywhere, it's happiest when it's run from an empty directory you'd like to become your theme.

While not a requirement we like to use NVM to manage the version of Node per project.

1. Creating a new Drupal theme

Create a new directory. Example:

themes/custom/my_awesome_theme

2. Setup NodeJS & NPM

1. Move into the new directory and install Node:

cd my_awesome_theme
nvm install 16 && node -v > .nvmrc

  • This will install the latest release of NodeJS v16.

  • It will create .nvmrc in the root of your project.

From now on, when working on this theme change into its directory and run nvm use and NVM will switch to the specified version for you.

2. Install dependencies

npm install -g libnpx

3. Generate the theme

Run the generator (Do not change this command):

npm create yo mc-d10-theme
  • You should be taken through a series of questions that allow you to pick the best options for your theme.

IMPORTANT: Your theme's machine name should always match the directory name you created above.

More info if you're interested in how this stuff works:

npm create is an alias of npm init and uses npx under the hood. Find out more about npm init.

Note about Drupal 10

If you are building a Drupal 10 theme, make the following updates after your theme has been created:

  • Remove node_modules

  • Run npm install

About the New Theme

Drupal Module Dependencies

This theme uses Twig namespaces. In order for these to work in Drupal you must install the Components Library module.

Support

The following is supported by your new theme.

  • Storybook
  • Component-Based Workflow
  • ES6+ (With Source Maps)
  • Sass
  • Image Compression
  • Live reloading
  • Sass and JavaScript linting

Starter Kit

The theme generator allows you to (optionally) add editorial components.

  • Accordion Group
  • Card List
  • Carousel
  • Carousel Multi
  • CTA
  • Embed
  • Form
  • Gallery
  • Hero
  • Map
  • Newsletter Form
  • Promo Banner
  • Quote
  • Stats
  • 50-50 Teaser
  • Text Block
  • Video Block

These can include both component and Drupal templates that are added to the appropriate place during theme generation. Your theme.libraries.yml is also updated to include the relevant libraries.

This can also be run within a pre-existing theme using:

npx yo mc-d10-theme:starter-kit

Create new Components

You can also generate base components with the right files in place using:

npm run generate

This is helpful if you are building out a new theme and would like to quickly create lots of new components with the libraries already wired up.

A Word About Commiting ./dist Files

TLDR: Don't do it if you can avoid it.

Optimally we want to gitignore all /.dist files and run npm run build as part of a continuous integration process.

Stuff You Might Want To Change

Supported Browsers

Change what browsers your theme supports by updating browserslist within package.json. For options take a look at browserslist.

This impacts CSS browser prefixes and JavaScript compiled files.

Demo Files

  • Swap out screenshot.png with your own theme image.
  • Remove or replace the font files in ./src/stories/global/fonts/.
  • Change the colors in ./src/stories/global/colors/.

Go Team

Provided by default are seven npm scripts that point to Gulp tasks. We run gulp through npm scripts.

  1. Run the default build task (gulp in this instance) and everything in it. This is the equivalent to running gulp on the command line with Gulp installed globally.

    npm run build

  2. Compile Sass and JS.

    npm run compile

  3. Watch files and run tasks when they change.

    npm run watch

  4. Compress png and svg assets.

    npm run compress

  5. Build Storybook style guide.

    npm run storybook

  6. Lint Sass and JS files.

    npm run lint

  7. Delete compiled Sass, JS and style guide files from the /dist directory.

    npm run clean

Links

Contributing

Would you like to contribute? Want to make a few changes or fix a bug? COME ON OVER!

Clone down this repo

git clone [email protected]:mediacurrent/theme_generator_10.git
cd theme_generator_10

Remove generator-mc-d10-theme if you have previously installed it:

Tip: use npm ls -g -depth=0 to see what global node modules are installed.

npm uninstall generator-mc-d10-theme -g

Use the node version of the generator

nvm install

nvm use

Install the generator's dependencies

npm install

Link your local generator files to npm:

npm link

Now whenever you run yo mc-d10-theme it'll use your locally cloned mc-d10-theme generator. Any updates done to the generator can be tested in real time.

Break off a feature branch dive right in. After you've got something you'd like to add, push back to the repo and pull request against develop.

IMPORTANT

To test the changes you've made locally, ensure your new theme uses the same version of node as the generator.