rlamana/docusaurus-plugin-sass

Provides support for SASS/SCSS to Docusaurus v2 and v3

docusaurus-plugin-sass

Provides support for SASS/SCSS to Docusaurus v2 and v3.

Installation

yarn add docusaurus-plugin-sass sass

sass-loader requires you to install either Dart Sass or Node Sass on your own (more documentation can be found at sass-loader).

How to use

1. Include the plugin in your docusaurus.config.js file.

// docusaurus.config.js
module.exports = {
  ...
+ plugins: ['docusaurus-plugin-sass'],
  ...
}

2. Write and import your stylesheets in Sass/SCSS as normal for both global styles and CSS modules.

Global styles

Assuming you are using @docusaurus/preset-classic (or @docusaurus/theme-classic), you can set the customCss property to point to yous Sass/SCSS file:

// docusaurus.config.js
module.exports = {
  presets: [
    [
      '@docusaurus/preset-classic',
      {
        ...
        theme: {
          customCss: require.resolve('./src/css/custom.scss'),
        },
        ...
      },
    ],
  ],
};

Sass/SCSS modules

To style your components using modules, name your stylesheet files with the .module.scss suffix (e.g. welcome.module.scss). Webpack will load such files as CSS modules and you have to reference the class names from the imported CSS module (as opposed to using plain strings). This is similar to the convention used in Create React App.

/* styles.module.scss */
.main {
  padding: 12px;

  article {
    color: #ccc;
  }
}

import styles from './styles.module.scss';

function MyComponent() {
  return (
    <main className={styles.main}>
      <article>Lorem Ipsum</article>
    </main>
  );
}

TypeScript support

To enable TypeScript support for Sass/SCSS modules, the TypeScript configuration should be updated to add the docusaurus-plugin-sass type definitions. This can be done in the tsconfig.json file:

{
  "extends": "@tsconfig/docusaurus/tsconfig.json",
  "compilerOptions": {
    ...
+    "types": ["docusaurus-plugin-sass"]
  }
}

docusaurus-plugin-sass's Issues

README.md setup instructions

Issue

I followed the README instructions to set up SCSS in my Docusaurus 3 repo.

When updating the module style name from styles.module.css to styles.module.scss, the import statements inside of the index.tsx files throw a false error (the styles still work) of Cannot find module './styles.module.scss' or its corresponding type declarations.

Proposed Solution

Add instructions to the README to include setting up the type declarations file: typings.d.ts

declare module "*.module.scss"

Support for Docusaurus V3

Would be great to understand what's needed to support Docusaurus V3, which recently came out in alpha. Getting the following peer dep warning:

warning " > [email protected]" has incorrect peer dependency "@docusaurus/core@^2.0.0-beta".

Is there a convention to target documentation styles only?

Does this module require a specific pattern to target documentation only h1,h2,h3 etc.. ?

When I inspect docusaurus 2 titles it seems to carry interesting class names along the lines of docTitle_node_modules-@docusaurus-theme-classic-src-theme-DocItem-, is it best practice to target these specifically using this sass module or should I approach it differently?

I am trying to avoid creating a global h1, h2, h3 style so I can have a different look on my documentation pages compared to the rest of the website.

PS: Great module, thanks for this!

Maintained? Website down...

Is this still maintained? The website appears to have gone offline with Vercel?

Add types to support imports

Like is done for @docusaurus/module-type-aliases and react-scripts. This enables IDE helpers.

I believe there are four in total:

declare module '*.module.scss' {
  const classes: { readonly [key: string]: string };
  export default classes;
}

declare module '*.module.sass' {
  const classes: { readonly [key: string]: string };
  export default classes;
}

declare module '*.scss' {
  const src: string;
  export default src;
}

declare module '*.sass' {
  const src: string;
  export default src;
}

Plugin won't install in gitlab CI

I've recently added this plugin to my docusaurus website. However when deploying to gitLab the yarn install job fails everytime with :

[4/4] Building fresh packages... error /builds/ion-energy/edison-kb-private/node_modules/node-sass: Command failed.

Thank you !

Latest version is not aligned with master

0.2.3 was released at Jan where latest fix about sass-loader was merged at end of Feb, can you please release a 0.2.4 which includes the latest fixset?

Thanks alot, cheers

Invalid Options in Docusaurus Alpha 62

Not sure if this is an anomaly or if its here to stay, but docusaurus alpha.62 is passing an id to options

docusaurus-plugin-sass/docusaurus-plugin-sass.js

Line 1 in a0f1749

module.exports = function(_, options) {

ValidationError: Invalid options object. Sass Loader has been initialized using an options object that does not match the API schema.
 - options has an unknown property 'id'. These properties are valid:
   object { implementation?, sassOptions?, prependData?, sourceMap?, webpackImporter? }

Happy to send a PR, but I guess it might be better to wait and see?

Use inside other plugins?

I had made a plugin for docusaurus, https://github.com/rohit-gohri/redocusaurus, and I wanted to use sass files for my theme components. Is there a way I could use this plugin inside my plugin so that people don't have to install it separately?

And would it be a problem if people also have this installed separately?

Problem with dependency tree with npm 7

Hi,

I use npm 7, docusaurus 2.0.0-beta and your docusaurus-plugin-sass.

I have a problem with the peer dependencies. Actually you set "@docusaurus/core": "^2.0.0" but npm 7 does not install pre-release dependencies with a '^'.

This possible for you to change and put >2.0.0-beta by example ?

As long as the release version of docusaurus hasn't officially been released.

This my stack trace when I install your plugin :

npm ERR! code ERESOLVE
npm ERR! ERESOLVE unable to resolve dependency tree
npm ERR! 
npm ERR! While resolving: frontend-documentation@0.0.0
npm ERR! Found: @docusaurus/[email protected]
npm ERR! node_modules/@docusaurus/core
npm ERR!   @docusaurus/core@"^2.0.0-beta.ff31de0ff" from the root project
npm ERR! 
npm ERR! Could not resolve dependency:
npm ERR! peer @docusaurus/core@"^2.0.0" from docusaurus-plugin-sass@0.2.1
npm ERR! node_modules/docusaurus-plugin-sass
npm ERR!   docusaurus-plugin-sass@"*" from the root project
npm ERR! 
npm ERR! Fix the upstream dependency conflict, or retry
npm ERR! this command with --force, or --legacy-peer-deps
npm ERR! to accept an incorrect (and potentially broken) dependency resolution.
npm ERR! 
npm ERR! See /home/lejes/.npm/eresolve-report.txt for a full report.

npm ERR! A complete log of this run can be found in:
npm ERR!     /home/lejes/.npm/_logs/2021-07-12T15_37_39_084Z-debug.log

node version : v14.17.2
npm version : 7.19.1

Thanks

@debug/@warn messages produce no output

expected:
the debug msg to work

reality:
the debug msg did not work

reproduce:
add a @debug or @warn message and watch

Would you consider supporting the use of the `sass` package?

For example, instead of set the dependency on node-sass in this package, let users set and install it themselves:

yarn add docusaurus-plugin-sass sass

Add includePaths

I need add custom includePaths like

style: {
                    sass: {
                        loaderOptions: (sassLoaderOptions, { env, paths }) => {
                            sassLoaderOptions.sassOptions = {
                                ...sassLoaderOptions.sass,
                                includePaths: [path.resolve(__dirname, "node_modules")],
                            };
                            return sassLoaderOptions;
                        },
                    },
                },

Is possible?