Use Hugo for our docs Sass and JS. (#29280)

Now there's only one command needed to run the docs: `npm run docs-serve`.

Also, simplify the npm scripts.

README.md

@@ -120,7 +120,7 @@ Have a bug or a feature request? Please first read the [issue guidelines](https:
 
 Bootstrap's documentation, included in this repo in the root directory, is built with [Hugo](https://gohugo.io/) and publicly hosted on GitHub Pages at <https://getbootstrap.com/>. The docs may also be run locally.
 
-Documentation search is powered by [Algolia's DocSearch](https://community.algolia.com/docsearch/). Working on our search? Be sure to set `debug: true` in `site/static/docs/4.3/assets/js/src/search.js` file.
+Documentation search is powered by [Algolia's DocSearch](https://community.algolia.com/docsearch/). Working on our search? Be sure to set `debug: true` in `site/assets/js/src/search.js` file.
 
 ### Running documentation locally
 

config.yml

@@ -23,6 +23,8 @@ module:
   mounts:
     - source:           dist
       target:           static/docs/4.3/dist
+    - source:           site/assets
+      target:           assets
     - source:           site/content
       target:           content
     - source:           site/data

package.json

@@ -20,45 +20,34 @@
   "scripts": {
     "start": "npm-run-all --parallel watch docs-serve",
     "bundlesize": "bundlesize",
+    "coveralls": "shx cat js/coverage/lcov.info | coveralls",
     "css": "npm-run-all css-compile css-prefix css-minify",
-    "css-main": "npm-run-all css-lint css-compile-main css-prefix-main css-minify-main",
+    "css-compile": "node-sass --output-style expanded --source-map true --source-map-contents true --precision 6 scss/ -o dist/css/",
-    "css-docs": "npm-run-all css-compile-docs css-prefix-docs* css-minify-docs",
-    "css-compile": "npm-run-all --parallel css-compile-*",
-    "css-compile-main": "node-sass --output-style expanded --source-map true --source-map-contents true --precision 6 scss/ -o dist/css/",
-    "css-compile-docs": "cross-env-shell node-sass --output-style expanded --source-map true --source-map-contents true --precision 6 site/static/docs/$npm_package_version_short/assets/scss/docs.scss site/static/docs/$npm_package_version_short/assets/css/docs.min.css",
     "css-lint": "npm-run-all --continue-on-error --parallel css-lint-*",
     "css-lint-stylelint": "stylelint \"**/*.{css,scss}\" --cache --cache-location .cache/.stylelintcache",
-    "css-lint-vars": "fusv scss/ site/static/",
+    "css-lint-vars": "fusv scss/ site/assets/scss/",
-    "css-minify": "npm-run-all --parallel css-minify-*",
+    "css-minify": "cleancss --level 1 --format breakWith=lf --source-map --source-map-inline-sources --output dist/css/bootstrap.min.css dist/css/bootstrap.css && cleancss --level 1 --format breakWith=lf --source-map --source-map-inline-sources --output dist/css/bootstrap-grid.min.css dist/css/bootstrap-grid.css && cleancss --level 1 --format breakWith=lf --source-map --source-map-inline-sources --output dist/css/bootstrap-utilities.min.css dist/css/bootstrap-utilities.css && cleancss --level 1 --format breakWith=lf --source-map --source-map-inline-sources --output dist/css/bootstrap-reboot.min.css dist/css/bootstrap-reboot.css",
-    "css-minify-main": "cleancss --level 1 --format breakWith=lf --source-map --source-map-inline-sources --output dist/css/bootstrap.min.css dist/css/bootstrap.css && cleancss --level 1 --format breakWith=lf --source-map --source-map-inline-sources --output dist/css/bootstrap-grid.min.css dist/css/bootstrap-grid.css && cleancss --level 1 --format breakWith=lf --source-map --source-map-inline-sources --output dist/css/bootstrap-utilities.min.css dist/css/bootstrap-utilities.css && cleancss --level 1 --format breakWith=lf --source-map --source-map-inline-sources --output dist/css/bootstrap-reboot.min.css dist/css/bootstrap-reboot.css",
-    "css-minify-docs": "cross-env-shell cleancss --level 1 --format breakWith=lf --source-map --source-map-inline-sources --output site/static/docs/$npm_package_version_short/assets/css/docs.min.css site/static/docs/$npm_package_version_short/assets/css/docs.min.css",
     "css-prefix": "npm-run-all --parallel css-prefix-*",
     "css-prefix-main": "postcss --config build/postcss.config.js --replace \"dist/css/*.css\" \"!dist/css/*.min.css\"",
-    "css-prefix-docs": "cross-env-shell postcss --config build/postcss.config.js --replace \"site/static/docs/$npm_package_version_short/assets/css/*.css\"",
+    "css-prefix-examples": "postcss --config build/postcss.config.js --replace \"site/content/**/*.css\"",
-    "css-prefix-docs-examples": "postcss --config build/postcss.config.js --replace \"site/content/**/*.css\"",
     "js": "npm-run-all js-compile js-minify",
-    "js-main": "npm-run-all js-lint js-compile js-minify-main",
-    "js-docs": "npm-run-all js-lint js-minify-docs",
     "js-compile": "npm-run-all --parallel js-compile-*",
     "js-compile-standalone": "rollup --environment BUNDLE:false --config build/rollup.config.js --sourcemap",
     "js-compile-standalone-esm": "rollup --environment ESM:true,BUNDLE:false --config build/rollup.config.js --sourcemap",
     "js-compile-bundle": "rollup --environment BUNDLE:true --config build/rollup.config.js --sourcemap",
     "js-compile-plugins": "node build/build-plugins.js",
     "js-lint": "eslint --cache --cache-location .cache/.eslintcache --report-unused-disable-directives .",
-    "js-minify": "npm-run-all --parallel js-minify-main js-minify-docs",
+    "js-minify": "npm-run-all --parallel js-minify-*",
-    "js-minify-main": "npm-run-all js-minify-standalone* js-minify-bundle",
     "js-minify-standalone": "terser --compress typeofs=false --mangle --comments \"/^!/\" --source-map \"content=dist/js/bootstrap.js.map,includeSources,url=bootstrap.min.js.map\" --output dist/js/bootstrap.min.js dist/js/bootstrap.js",
     "js-minify-standalone-esm": "terser --compress --mangle --comments \"/^!/\" --source-map \"content=dist/js/bootstrap.esm.js.map,includeSources,url=bootstrap.esm.min.js.map\" --output dist/js/bootstrap.esm.min.js dist/js/bootstrap.esm.js",
     "js-minify-bundle": "terser --compress typeofs=false --mangle --comments \"/^!/\" --source-map \"content=dist/js/bootstrap.bundle.js.map,includeSources,url=bootstrap.bundle.min.js.map\" --output dist/js/bootstrap.bundle.min.js dist/js/bootstrap.bundle.js",
-    "js-minify-docs": "cross-env-shell terser --mangle --comments \\\"/^!/\\\" --output site/static/docs/$npm_package_version_short/assets/js/docs.min.js site/static/docs/$npm_package_version_short/assets/js/vendor/anchor.min.js site/static/docs/$npm_package_version_short/assets/js/vendor/clipboard.min.js site/static/docs/$npm_package_version_short/assets/js/vendor/bs-custom-file-input.min.js \"site/static/docs/$npm_package_version_short/assets/js/src/*.js\"",
     "js-test": "npm-run-all --parallel js-test-karma js-test-integration",
     "js-debug": "cross-env DEBUG=true karma start js/tests/karma.conf.js",
     "js-test-karma": "karma start js/tests/karma.conf.js",
     "js-test-integration": "rollup --config js/tests/integration/rollup.bundle.js",
     "js-test-cloud": "cross-env BROWSER=true npm run js-test-karma",
     "lint": "npm-run-all --parallel js-lint css-lint",
-    "coveralls": "shx cat js/coverage/lcov.info | coveralls",
+    "docs": "npm-run-all docs-build docs-lint",
-    "docs": "npm-run-all css-docs js-docs docs-build docs-lint",
     "docs-build": "hugo --cleanDestinationDir",
     "docs-compile": "npm run docs-build",
     "docs-production": "cross-env HUGO_ENV=production npm run docs-build",
@@ -67,7 +56,7 @@
     "docs-lint": "npm-run-all --parallel docs-vnu docs-linkinator",
     "docs-serve": "hugo server --port 9001 --disableFastRender",
     "docs-serve-only": "serve _gh_pages --listen 9001",
-    "update-deps": "ncu -a -x karma-browserstack-launcher && npm update && cross-env-shell echo Manually update \\\"site/static/docs/$npm_package_version_short/assets/js/vendor/\\\"",
+    "update-deps": "ncu -a -x karma-browserstack-launcher && npm update && cross-env echo Manually update site/assets/js/vendor",
     "release": "npm-run-all dist release-sri release-zip docs-production",
     "release-sri": "node build/generate-sri.js",
     "release-version": "node build/change-version.js",
@@ -76,10 +65,10 @@
     "test": "npm-run-all lint dist js-test docs-build docs-lint",
     "netlify": "npm-run-all dist release-sri docs-production",
     "watch": "npm-run-all --parallel watch-*",
-    "watch-css-main": "nodemon --watch scss/ --ext scss --exec \"npm run css-main\"",
+    "watch-css-main": "nodemon --watch scss/ --ext scss --exec \"npm-run-all css-lint css-compile css-prefix\"",
-    "watch-css-docs": "nodemon --watch \"site/static/**/assets/scss/\" --ext scss --exec \"npm run css-docs\"",
+    "watch-css-docs": "nodemon --watch site/assets/scss/ --ext scss --exec \"npm run css-lint\"",
-    "watch-js-main": "nodemon --watch js/src/ --ext js --exec \"npm run js-compile\"",
+    "watch-js-main": "nodemon --watch js/src/ --ext js --exec \"npm-run-all js-lint js-compile\"",
-    "watch-js-docs": "nodemon --watch \"site/static/**/assets/js/src/\" --ext js --exec \"npm run js-docs\""
+    "watch-js-docs": "nodemon --watch site/assets/js/src/ --ext js --exec \"npm run js-lint\""
   },
   "style": "dist/css/bootstrap.css",
   "sass": "scss/bootstrap.scss",
@@ -155,6 +144,9 @@
     "!js/src/**/*.spec.js",
     "scss/**/*.scss"
   ],
+  "hugo-bin": {
+    "buildTags": "extended"
+  },
   "jspm": {
     "registry": "npm",
     "main": "js/bootstrap",

site/assets/scss/docs.scss

@@ -24,9 +24,9 @@
 // Happy Bootstrapping!
 
 // Load Bootstrap variables and mixins
-@import "../../../../../../scss/functions";
+@import "../../../scss/functions";
-@import "../../../../../../scss/variables";
+@import "../../../scss/variables";
-@import "../../../../../../scss/mixins";
+@import "../../../scss/mixins";
 
 // Load docs components
 @import "variables";

site/content/docs/4.3/getting-started/build-tools.md

@@ -55,10 +55,10 @@ Our [package.json]({{< param repo >}}/blob/v{{< param current_version >}}/packag
     </tr>
     <tr>
       <td>
-        <code>npm run docs</code>
+        <code>npm run docs-serve</code>
       </td>
       <td>
-        Builds and lints CSS and JavaScript for docs. You can then run the documentation locally via <code>npm run docs-serve</code>.
+        Builds and runs the documentation locally.
       </td>
     </tr>
   </tbody>

site/layouts/partials/scripts.html

@@ -8,12 +8,13 @@
 <script src="https://cdn.jsdelivr.net/npm/docsearch.js@2/dist/cdn/docsearch.min.js"></script>
 {{- end }}
 
-{{- if eq (getenv "HUGO_ENV") "production" -}}
+{{- $vendor := resources.Match "js/vendor/*.js" -}}
-  <script src="/docs/{{ .Site.Params.docs_version }}/assets/js/docs.min.js"></script>
+{{- $js := resources.Match "js/src/*.js" -}}
-{{- else -}}
+{{- $targetDocsJSPath := printf "/docs/%s/assets/js/docs.js" .Site.Params.docs_version -}}
-  <script src="/docs/{{ .Site.Params.docs_version }}/assets/js/vendor/anchor.min.js"></script>
+{{- $docsJs := append $js $vendor | resources.Concat $targetDocsJSPath -}}
-  <script src="/docs/{{ .Site.Params.docs_version }}/assets/js/vendor/clipboard.min.js"></script>
+
-  <script src="/docs/{{ .Site.Params.docs_version }}/assets/js/vendor/bs-custom-file-input.min.js"></script>
+{{- if (eq (getenv "HUGO_ENV") "production") -}}
-  <script src="/docs/{{ .Site.Params.docs_version }}/assets/js/src/application.js"></script>
+  {{- $docsJs = $docsJs | resources.Minify -}}
-  <script src="/docs/{{ .Site.Params.docs_version }}/assets/js/src/search.js"></script>
+{{- end }}
-{{- end -}}
+
+<script src="{{ $docsJs.Permalink | relURL }}"></script>

site/layouts/partials/stylesheet.html

@@ -9,6 +9,17 @@
 {{- "<!-- Documentation extras -->" | safeHTML }}
 <link href="https://cdn.jsdelivr.net/npm/docsearch.js@2/dist/cdn/docsearch.min.css" rel="stylesheet">
 {{- end -}}
+
 {{- if (ne .Page.Layout "examples") }}
-<link href="/docs/{{ .Site.Params.docs_version }}/assets/css/docs.min.css" rel="stylesheet">
+{{- $targetDocsCssPath := printf "/docs/%s/assets/css/docs.css" .Site.Params.docs_version -}}
+{{- $sassOptions := dict "targetPath" $targetDocsCssPath "precision" 6 -}}
+{{- $postcssOptions := dict "use" "autoprefixer" "noMap" true -}}
+
+{{- if (eq (getenv "HUGO_ENV") "production") -}}
+  {{- $sassOptions = merge $sassOptions (dict "outputStyle" "compressed") -}}
+{{- end -}}
+
+{{- $style := resources.Get "scss/docs.scss" | toCSS $sassOptions | postCSS $postcssOptions }}
+
+<link rel="stylesheet" href="{{ $style.Permalink | relURL }}">
 {{- end }}