Help: Migrate to Go Module; Error: Error building site: TOCSS: failed to transform "scss/main.scss"

[aimeeu]

My docs site currently uses Docsy as as submodule (docsy @ efdc5bf) and Hugo 0.71. So I am trying to migrate to the Go module v0.60.0 and Hugo v0.110.0. I followed the https://www.docsy.dev/docs/updating/convert-site-to-module/ instructions. Compile errors because Hugo couldn't locate my custom shortcodes. I searched and found a discussion item that mentions I have to map the local theme directories in config.yaml. (#1095, https://github.com/google/docsy/pull/1184/files, https://github.com/fluxcd/website/pull/1136/files). I did that, but the build still fails locally and in Netlify with the SCSS error.

The error: Undefined variable: "$rfs-mq-value" - I have zero idea what that's about. That variable is not overridden in assets/scss/_variables_project.css (which a web contractor created) and that variable doesn't exist locally.

Repo: https://github.com/armory/docs
Pull Request: armory/docs#1807

Local build error:

aimeeu@aimeeuMBP16:~/Dev/git/github.com/armory/docs$ hugo server
Start building sites …
hugo v0.110.0+extended darwin/amd64 BuildDate=unknown
Error: Error building site: TOCSS: failed to transform "scss/main.scss" (text/x-scss): "/var/folders/f1/wp5gkfwn7tx8_cnjn1f1bly40000gn/T/hugo_cache/modules/filecache/modules/pkg/mod/github.com/twbs/bootstrap@v5.2.3+incompatible/scss/utilities/_api.scss:20:20": Undefined variable: "$rfs-mq-value".
Built in 2480 ms

Netlify build error:

1:44:18 PM: $ hugo
1:44:20 PM: hugo: downloading modules …
1:44:28 PM: hugo: collected modules in 10026 ms
1:44:28 PM: Start building sites …
1:44:28 PM: hugo v0.110.0-e32a493b7826d02763c3b79623952e625402b168+extended linux/amd64 BuildDate=2023-01-17T12:16:09Z VendorInfo=gohugoio
1:44:31 PM: Error: Error building site: TOCSS: failed to transform "scss/main.scss" (text/x-scss): "/opt/build/cache/hugo_cache/modules/filecache/modules/pkg/mod/github.com/twbs/bootstrap@v5.2.3+incompatible/scss/utilities/_api.scss:20:20": Undefined variable: "$rfs-mq-value".
1:44:31 PM: Total in 12905 ms

Relevant section of config.yaml:

module:
  proxy: direct
  hugoVersion:
    extended: true
    min: 0.110.0
  imports:
    - path: github.com/google/docsy
      disable: false
      mounts: # https://github.com/google/docsy/discussions/1095
        # without mapping the mounts, Hugo can't find any of the theme files we override in the layouts directory
        # https://github.com/google/docsy/commit/215f68033bbc7bddf8dbec2bbabf8749d1998a17
        - source: assets
          target: assets
        - source: node_modules/bootstrap
          target: assets/vendor/bootstrap
        - source: node_modules/@fortawesome/fontawesome-free
          target: assets/vendor/Font-Awesome
        - source: i18n
          target: i18n
        - source: layouts
          target: layouts
        - source: static
          target: static
        - source: data
          target: data
        - source: node_modules/@fortawesome/fontawesome-free/webfonts
          target: static/webfonts
    - path: github.com/google/docsy/dependencies
      disable: false
  mounts:
    - source: content/en
      target: content

Does anyone know what's causing the build error and how to fix it? I've never been a web developer so I am beyond lost with this one.

Thanks.

[deining]

You came quite far with your upgrade!

The error message

1:44:31 PM: Error: Error building site: TOCSS: failed to transform "scss/main.scss" (text/x-scss): "/opt/build/cache/hugo_cache/modules/filecache/modules/pkg/mod/github.com/twbs/bootstrap@v5.2.3+incompatible/scss/utilities/_api.scss:20:20": Undefined variable: "$rfs-mq-value".

indicates that you are using bootstrap 5.2.3, but docsy 0.6.0 needs v4.6.2.

The solution is quite easy. At project root, issue:

hugo mod get -u github.com/twbs/bootstrap@v4.6.2

This will bring bootstrap dependency to the correct version. Afterwards, you can successful preview your project via hugo server.

[aimeeu]

Thank you @deining for the quick reply and solution!