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.
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 |
Clone jekyll-tailwind-starter from mhanberg.
Follow the instructions in the README which basically are:
$ git clone git@github.com: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/startOpen 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.
Optional additional PostCSS packages to install:
To add support for CSS variables just add the postcss/postcss-custom-properties package.
$ yarn add -D postcss-custom-propertiesExample:
:root {
--color: red;
}
h1 { color: var(--color); }To add support for SASS/SCSS nested syntax just add the postcss/postcss-nested package.
$ yarn add -D postcss-nestedExample:
body {
@apply bg-gray-100;
h1 {
@apply text-3xl;
}
}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.
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.
In VS Code install / activate the stylelint/vscode-stylelint extension.
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-standardThere were some recommendadtions for including stylelint-config-recommended as well, so we add that too.
$ yarn add -D stylelint-config-recommendedTo 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-matterCreate 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
}
}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"
]
}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.
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-standardThe 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.
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.
Thanks, this completely sorted out an error I was getting regarding frontmatter in scss 💯 :