From a98aacc9b6ba67c6bc555dd79f45b78564eb441f Mon Sep 17 00:00:00 2001 From: Mark Otto Date: Thu, 11 Dec 2025 14:10:51 -0800 Subject: [PATCH] Docs design updates (#41918) * Refactor docs site styling and Shiki integration Code Highlighting: - Enhance Code.astro with Shiki transformers and Bootstrap theme - Add tab support for multi-language code examples - Add toolbar with language labels and copy button - Support diff highlighting via @shikijs/transformers Components: - Update Example.astro styling and structure - Refine DocsSidebar.astro layout - Update Navigation, Versions, and GetStarted components - Update ThemeToggler.astro - Minor updates to ReferenceTable, Swatch components Site SCSS: - Restyle code snippets and examples (_component-examples.scss) - Update syntax highlighting styles (_syntax.scss) - Refine sidebar styling (_sidebar.scss) - Update search component styles (_search.scss) - Update navbar styles (_navbar.scss) - Refresh callouts, clipboard, content styles Config & Assets: - Update astro.config.ts for Shiki - Add sticky.js partial - Update application.js - Update guide screenshots (parcel, vite, webpack) * fixes * update images * update permissions * Optimised images with calibre/image-actions --------- Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com> --- .../workflows/calibreapp-image-actions.yml | 3 +- package-lock.json | 47 +++ package.json | 2 + site/astro.config.ts | 22 +- site/src/assets/application.js | 2 + site/src/assets/partials/sticky.js | 28 ++ site/src/components/DocsSidebar.astro | 4 +- site/src/components/ReferenceTable.astro | 2 +- .../components/UtilityReferenceTable.astro | 2 +- site/src/components/head/Head.astro | 12 + site/src/components/header/Navigation.astro | 12 +- site/src/components/header/Versions.astro | 5 +- site/src/components/home/GetStarted.astro | 24 +- site/src/components/shortcodes/Code.astro | 333 +++++++++++++++--- site/src/components/shortcodes/Example.astro | 45 +-- site/src/components/shortcodes/Swatch.astro | 2 +- site/src/layouts/DocsLayout.astro | 14 +- site/src/layouts/partials/ThemeToggler.astro | 17 +- site/src/scss/_callouts.scss | 6 +- site/src/scss/_clipboard-js.scss | 12 +- site/src/scss/_component-examples.scss | 109 +++--- site/src/scss/_content.scss | 17 +- site/src/scss/_navbar.scss | 61 ++-- site/src/scss/_search.scss | 255 +++++++------- site/src/scss/_sidebar.scss | 27 +- site/src/scss/_syntax.scss | 73 +++- site/src/scss/_variables.scss | 2 +- .../assets/img/guides/bootstrap-npm.png | Bin 0 -> 77980 bytes .../assets/img/guides/bootstrap-npm@2x.png | Bin 0 -> 299129 bytes .../assets/img/guides/bootstrap-parcel.png | Bin 144652 -> 100137 bytes .../assets/img/guides/bootstrap-parcel@2x.png | Bin 511984 -> 738419 bytes .../assets/img/guides/bootstrap-vite.png | Bin 146772 -> 210594 bytes .../assets/img/guides/bootstrap-vite@2x.png | Bin 517193 -> 747658 bytes .../assets/img/guides/bootstrap-webpack.png | Bin 149510 -> 217457 bytes .../img/guides/bootstrap-webpack@2x.png | Bin 532848 -> 766924 bytes 35 files changed, 769 insertions(+), 369 deletions(-) create mode 100644 site/src/assets/partials/sticky.js create mode 100644 site/static/docs/[version]/assets/img/guides/bootstrap-npm.png create mode 100644 site/static/docs/[version]/assets/img/guides/bootstrap-npm@2x.png diff --git a/.github/workflows/calibreapp-image-actions.yml b/.github/workflows/calibreapp-image-actions.yml index 09d038e761..cf21837170 100644 --- a/.github/workflows/calibreapp-image-actions.yml +++ b/.github/workflows/calibreapp-image-actions.yml @@ -18,7 +18,8 @@ jobs: name: calibreapp/image-actions runs-on: ubuntu-latest permissions: - # allow calibreapp/image-actions to update PRs + # allow calibreapp/image-actions to update PRs and commit compressed images + contents: write pull-requests: write steps: - name: Clone repository diff --git a/package-lock.json b/package-lock.json index b84bb31623..bbcc8d32ae 100644 --- a/package-lock.json +++ b/package-lock.json @@ -33,6 +33,7 @@ "@rollup/plugin-commonjs": "^29.0.0", "@rollup/plugin-node-resolve": "^16.0.3", "@rollup/plugin-replace": "^6.0.3", + "@shikijs/transformers": "^3.7.0", "@stackblitz/sdk": "^1.11.0", "@types/js-yaml": "^4.0.9", "@types/mime": "^4.0.0", @@ -40,6 +41,7 @@ "astro": "^5.15.6", "astro-auto-import": "^0.4.5", "autoprefixer": "^10.4.22", + "bootstrap-vscode-theme": "^0.0.9", "bundlewatch": "^0.4.1", "clean-css-cli": "^5.6.3", "clipboard": "^2.0.11", @@ -4686,6 +4688,41 @@ "@shikijs/types": "3.15.0" } }, + "node_modules/@shikijs/transformers": { + "version": "3.19.0", + "resolved": "https://registry.npmjs.org/@shikijs/transformers/-/transformers-3.19.0.tgz", + "integrity": "sha512-e6vwrsyw+wx4OkcrDbL+FVCxwx8jgKiCoXzakVur++mIWVcgpzIi8vxf4/b4dVTYrV/nUx5RjinMf4tq8YV8Fw==", + "dev": true, + "license": "MIT", + "dependencies": { + "@shikijs/core": "3.19.0", + "@shikijs/types": "3.19.0" + } + }, + "node_modules/@shikijs/transformers/node_modules/@shikijs/core": { + "version": "3.19.0", + "resolved": "https://registry.npmjs.org/@shikijs/core/-/core-3.19.0.tgz", + "integrity": "sha512-L7SrRibU7ZoYi1/TrZsJOFAnnHyLTE1SwHG1yNWjZIVCqjOEmCSuK2ZO9thnRbJG6TOkPp+Z963JmpCNw5nzvA==", + "dev": true, + "license": "MIT", + "dependencies": { + "@shikijs/types": "3.19.0", + "@shikijs/vscode-textmate": "^10.0.2", + "@types/hast": "^3.0.4", + "hast-util-to-html": "^9.0.5" + } + }, + "node_modules/@shikijs/transformers/node_modules/@shikijs/types": { + "version": "3.19.0", + "resolved": "https://registry.npmjs.org/@shikijs/types/-/types-3.19.0.tgz", + "integrity": "sha512-Z2hdeEQlzuntf/BZpFG8a+Fsw9UVXdML7w0o3TgSXV3yNESGon+bs9ITkQb3Ki7zxoXOOu5oJWqZ2uto06V9iQ==", + "dev": true, + "license": "MIT", + "dependencies": { + "@shikijs/vscode-textmate": "^10.0.2", + "@types/hast": "^3.0.4" + } + }, "node_modules/@shikijs/types": { "version": "3.15.0", "resolved": "https://registry.npmjs.org/@shikijs/types/-/types-3.15.0.tgz", @@ -5949,6 +5986,16 @@ "dev": true, "license": "MIT" }, + "node_modules/bootstrap-vscode-theme": { + "version": "0.0.9", + "resolved": "https://registry.npmjs.org/bootstrap-vscode-theme/-/bootstrap-vscode-theme-0.0.9.tgz", + "integrity": "sha512-++aMildSGVaDS7qD59FEh4Fh6bJol4Gpo7u3rbEPqcuReRY7zOvLn77sBoK9zhVe+YT7bkPiDut47jErweChdw==", + "dev": true, + "license": "MIT", + "engines": { + "vscode": "^1.0.0" + } + }, "node_modules/boxen": { "version": "8.0.1", "resolved": "https://registry.npmjs.org/boxen/-/boxen-8.0.1.tgz", diff --git a/package.json b/package.json index 019aa97c41..a9c11aabaa 100644 --- a/package.json +++ b/package.json @@ -119,6 +119,7 @@ "@rollup/plugin-commonjs": "^29.0.0", "@rollup/plugin-node-resolve": "^16.0.3", "@rollup/plugin-replace": "^6.0.3", + "@shikijs/transformers": "^3.7.0", "@stackblitz/sdk": "^1.11.0", "@types/js-yaml": "^4.0.9", "@types/mime": "^4.0.0", @@ -126,6 +127,7 @@ "astro": "^5.15.6", "astro-auto-import": "^0.4.5", "autoprefixer": "^10.4.22", + "bootstrap-vscode-theme": "^0.0.9", "bundlewatch": "^0.4.1", "clean-css-cli": "^5.6.3", "clipboard": "^2.0.11", diff --git a/site/astro.config.ts b/site/astro.config.ts index de9a1433bb..d5f3cbdc91 100644 --- a/site/astro.config.ts +++ b/site/astro.config.ts @@ -1,4 +1,7 @@ import { defineConfig } from 'astro/config' +import bootstrapLight from 'bootstrap-vscode-theme/themes/bootstrap-light.json' +import bootstrapDark from 'bootstrap-vscode-theme/themes/bootstrap-dark.json' +import { transformerNotationDiff } from '@shikijs/transformers' import { bootstrap } from './src/libs/astro' import { getConfig } from './src/libs/config' @@ -27,9 +30,22 @@ export default defineConfig({ syntaxHighlight: 'shiki', shikiConfig: { themes: { - light: 'github-light', - dark: 'github-dark' - } + light: bootstrapLight, + dark: bootstrapDark + }, + transformers: [ + transformerNotationDiff(), + { + name: 'add-language-attribute', + pre(node) { + // Add data-language attribute to pre tag so Code component can access it + const lang = this.options.lang + if (lang) { + node.properties['dataLanguage'] = lang + } + } + } + ] } }, site, diff --git a/site/src/assets/application.js b/site/src/assets/application.js index 62f5f88b34..c9fce7fad6 100644 --- a/site/src/assets/application.js +++ b/site/src/assets/application.js @@ -11,6 +11,8 @@ import sidebarScroll from './partials/sidebar.js' import snippets from './partials/snippets.js' +import stickyNav from './partials/sticky.js' sidebarScroll() snippets() +stickyNav() diff --git a/site/src/assets/partials/sticky.js b/site/src/assets/partials/sticky.js new file mode 100644 index 0000000000..8d803fb806 --- /dev/null +++ b/site/src/assets/partials/sticky.js @@ -0,0 +1,28 @@ +// NOTICE!! DO NOT USE ANY OF THIS JAVASCRIPT +// IT'S ALL JUST JUNK FOR OUR DOCS! +// ++++++++++++++++++++++++++++++++++++++++++ + +/* + * JavaScript for Bootstrap's docs (https://getbootstrap.com/) + * Copyright 2011-2025 The Bootstrap Authors + * Licensed under the Creative Commons Attribution 3.0 Unported License. + * For details, see https://creativecommons.org/licenses/by/3.0/. + */ + +export default () => { + const navbar = document.querySelector('.bd-sticky-navbar') + + if (!navbar) { + return + } + + const handleScroll = () => { + navbar.classList.toggle('is-stuck', window.scrollY > 0) + } + + // Check initial state + handleScroll() + + // Update on scroll + window.addEventListener('scroll', handleScroll, { passive: true }) +} diff --git a/site/src/components/DocsSidebar.astro b/site/src/components/DocsSidebar.astro index 2bc4d3f411..cfb6c336ff 100644 --- a/site/src/components/DocsSidebar.astro +++ b/site/src/components/DocsSidebar.astro @@ -91,7 +91,7 @@ const sidebar = getData('sidebar')
  • {item.title} @@ -111,7 +111,7 @@ const sidebar = getData('sidebar')
  • {group.title} diff --git a/site/src/components/ReferenceTable.astro b/site/src/components/ReferenceTable.astro index c98d1528ad..ff9b33838b 100644 --- a/site/src/components/ReferenceTable.astro +++ b/site/src/components/ReferenceTable.astro @@ -74,7 +74,7 @@ function addVarComments(cssValue: string): string { cssValue.replace(/var\((--[a-z0-9-]+)\)/gi, (match, varName) => { const resolvedValue = cssVarValues[varName]; if (resolvedValue) { - comments.push(`/* ${resolvedValue} */`); + comments.push(`/* ${resolvedValue} */`); } return match; }); diff --git a/site/src/components/UtilityReferenceTable.astro b/site/src/components/UtilityReferenceTable.astro index b41902aeaf..14ab1717b9 100644 --- a/site/src/components/UtilityReferenceTable.astro +++ b/site/src/components/UtilityReferenceTable.astro @@ -128,7 +128,7 @@ function addVarComments(cssValue: string): string { cssValue.replace(/var\((--[a-z0-9-]+)\)/gi, (match, varName) => { const resolvedValue = cssVarValues[varName]; if (resolvedValue) { - comments.push(`/* ${resolvedValue} */`); + comments.push(`/* ${resolvedValue} */`); } return match; }); diff --git a/site/src/components/head/Head.astro b/site/src/components/head/Head.astro index 11bf4fedcd..a5e4a2d8f5 100644 --- a/site/src/components/head/Head.astro +++ b/site/src/components/head/Head.astro @@ -44,12 +44,24 @@ const ScssProd = import.meta.env.PROD ? await import('@components/head/ScssProd. + + + + {pageTitle} {robots && } + + + {import.meta.env.PROD && ScssProd && ( diff --git a/site/src/components/header/Navigation.astro b/site/src/components/header/Navigation.astro index 43d8fb7521..6c6df6b19a 100644 --- a/site/src/components/header/Navigation.astro +++ b/site/src/components/header/Navigation.astro @@ -21,7 +21,7 @@ interface Props { const { addedIn, layout, title } = Astro.props --- -
    +