Setting up VS Code with Jekyll, Tailwind CSS, PostCSS ('jekyll-postcss') and stylelint with SCSS-like syntax support

After a few hours of struggling I have finally gotten all this setup to work as wanted, so I'm sharing this for future reference and to save time for others.

SETUP NOTES:

This is the system all this works on:

Key:	Value:
OS	Linux Mint 19.3 Cinnamon
VS Code	1.47.3
Node	v12.18.1
Ruby	2.6.2p47
Stylelint	13.6.1
Jekyll	4.1.1 (upgraded from 3.8.5)
Tailwind	1.6.1

Step 1: Getting Jekyll Installed

Clone jekyll-tailwind-starter from mhanberg.

Follow the instructions in the README which basically are:

$  git clone [email protected]:mhanberg/jekyll-tailwind-starter PROJECT_NAME

$  cd PROJECT_NAME

   # Install your Ruby and JavaScript dependencies.
   # Initialize your Tailwind configuration.
   # Reinitialize your git repository.
$  bin/setup


# And finally, Start the server 
$  bin/start

Open http://localhost:5000/ in your browser to confirm things are working OK.

TIP:

Upgrade the default version of Jekyll to v4.x in the Gemfile straight away and rerun bundle install.

Step 2: Improving PostCSS workflow

Optional additional PostCSS packages to install:

CSS var() support

To add support for CSS variables just add the postcss/postcss-custom-properties package.

$ yarn add -D postcss-custom-properties

Example:

:root {
  --color: red;
}
h1 { color: var(--color); }

Nested SCSS-like syntax support

To add support for SASS/SCSS nested syntax just add the postcss/postcss-nested package.

$ yarn add -D postcss-nested

Example:

body {
  @apply bg-gray-100;

  h1 {
    @apply text-3xl;
  }
}

Configuring the postcss.config.js file

In the postcss.config.js file add the new packages as shown below.

Please note their location after the tailwindcss package and before the autoprefixer package.

require("tailwindcss")("./_includes/tailwind.config.js"),

require('postcss-custom-properties'),
require('postcss-nested'),

require("autoprefixer"),

NOTE:

I was unable to get SASS/SCSS // comments to work, so I'm handling that problem in the stylelint configuration below.

Restart the server bin/start and try out the support for the new additions above. They should work.

Step 3: Setting Up VS Code

At this stage your CSS files should have some VS Code syntax complaints relating to the Tailwind @tailwind and @apply and the Jekyll frontmatter parts.

To fix this we need to setup VS Code locally via a Workspace Settings file in the .vscode/settings.json file.

Which should include the following:

{
  "css.validate": false,
  "less.validate": false,
  "scss.validate": false,
  "postcss.validate": false
}

NOTE! It is really important to add the "postcss.validate": false part.

We also need to install the following VS Code extension: MhMadHamster/vscode-postcss-language to add better PostCSS support in VS Code.

Your .css file(s) should now be silent (without errors), but you also have no validation of the files. Not so good.

Step 4: Installing and Configuring StyleLint

In VS Code install / activate the stylelint/vscode-stylelint extension.

Install Node packages

Then you need to install the following node packages to make things work:

Install the main stylelint and stylelint-config-standard packages as recommended on the StyleLint User Guide page.

$  yarn add -D stylelint stylelint-config-standard

There were some recommendadtions for including stylelint-config-recommended as well, so we add that too.

$  yarn add -D stylelint-config-recommended

Silence the Jekyll Frontmatter Error

To silence the Jekyll frontmatter errors we are getting, we add the sasaplus1/stylelint-processor-ignore-front-matter processor and then add it to the .stylelintrc.json file (see below).

$  yarn add -D stylelint-processor-ignore-front-matter

Creating The .stylelintrc.json File

Create a .stylelintrc.json file in the root of your jekyll app, and don't forget to add it to the exclude: section of the _config.yml file.

{
  "extends": ["stylelint-config-recommended"],
  "processors": ["stylelint-processor-ignore-front-matter"],
  "rules": {
    "at-rule-no-unknown": [true, { 
      "ignoreAtRules": ["tailwind", "apply", "variants", "responsive", "screen"] 
    } ],
    "declaration-block-trailing-semicolon": "always",
    "no-descending-specificity": [true, { "ignore": ["selectors-within-list"] } ],
    "no-invalid-double-slash-comments": true
  }
}

Getting VS Code Happy Too

To keep VS Code happy with all this I had to add the following to the local .vscode/settings.json file:

{
  // snip (see above)

  // Help VS Code know that .css is actually a .postcss file in disguise
  "files.associations": {
    "*.css": "postcss"
  },

  // enable StyleLint
  "stylelint.enable": true,

  // the default StyleLint is checking way too much, so let's silence all that ;-)
  "stylelint.validate": [
    "css",
    "postcss"
  ]
}

Testing StyleLint works

In your Terminal inside the root of your Jekyll app, type the following command:

$  npx stylelint "**/*.css"

IF there are no errors in the CSS, then there should be no output from that command.

To make sure things work, just add a bad color, such as: color: #xyz; and you should get an Unexpected invalid hex color "#xyz" color-no-invalid-hex error returned.

Getting It To Really Work

After all the above VS Code was still a bit reluctant to work with StyleLint and threw up some errors. To overcome those errors I added and global installation of styleint like this:

$ npm install -g stylelint stylelint-config-standard

Step 5: Enjoy life!

The above instructions should hopefully have resulted in a solid pleasant work experience going forward.

IF not, then please fork this gist and change what's wrong.

---

CREDITS

A lot of googling took place and unfortunately I didn't keep track of the pages that eventually assisted me the most, but they are out there somewhere.