Skip to content
GitLab

Use Hugo for our docs Sass and JS.

Merged XhmikosR requested to merge master-xmr-hugo-doc-assets into master

Pros:

  1. we simplify our docs development process and makes the whole process faster; npm run docs-serve and everything doc-related will be handled by Hugo
  2. we get rid of the versioned folder for CSS and JS
  3. we get rid of docs.min.css, docs.min.css.map and docs.min.js files from the repo
  4. the assets/scss folder is no longer output to the build folder
  5. we have SRI for the docs CSS, but perhaps I should remove this in case we want to edit docs.css in the future so that we don't have to edit the SRI too? - EDIT: reverted this

Cons:

  1. the JS minifier is pretty basic. That's OK, we won't have the possible best compression of docs.min.js, but being that we already use minified vendor JS files, the difference shouldn't be that big. EDIT: it's ~350 bytes gzipped.
  2. for CSS I opted to not minify the CSS at all, but rather just use the minified output from Sass. The CSS minifier does some stuff I don't like, so we better not add another POF. The difference is negligible, ~15 bytes gzipped - Beautified diff: https://www.diffchecker.com/AWtS29IX
  3. we don't have sourcemaps for production. There's nothing we can do currently about this. I have them enabled for Sass only for development
  4. we don't have PostCSS for development. It's either sourcemaps or PostCSS due to a limitation. Let me know how to proceed. Upstream issue: https://github.com/gohugoio/hugo/issues/6189
  5. there's a chance the Sass lib Hugo is using has a bug, but it's well tested. It's just that this adds another potential POF. We shouldn't worry about it a lot I guess, though.

To try it, switch to this branch and do rm -rf ./node_modules/ && npm i; this is because we switch to the Extended Hugo version which has Sass support.

@mdo @MartijnCuppens @Johann-S @ysds @bardiharborow please try it and let me know your thoughts.