Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: bundle assets with Hugo #38993

Merged
merged 5 commits into from
Mar 19, 2024
Merged

docs: bundle assets with Hugo #38993

merged 5 commits into from
Mar 19, 2024

Conversation

XhmikosR
Copy link
Member

@XhmikosR XhmikosR commented Aug 2, 2023

Description

Motivation & Context

Type of changes

  • Bug fix (non-breaking change which fixes an issue)
  • New feature (non-breaking change which adds functionality)
  • Refactoring (non-breaking change)
  • Breaking change (fix or feature that would change existing functionality)

Checklist

  • I have read the contributing guidelines
  • My code follows the code style of the project (using npm run lint)
  • My change introduces changes to the documentation
  • I have updated the documentation accordingly
  • I have added tests to cover my changes
  • All new and existing tests passed

Live previews

Related issues


Fixes #27412 (only some of the examples are still using libraries from the CDN)

Note that at some point we need to switch to dart sass for docs, but I couldn't make it to work and it requires the manual installation of Dart Sass, see #39700.

TODO:

  • Include @docsearch/css in docs or search.css
  • Move search to its own css file instead of docs.css after the above is sorted?
  • Split unrelated patches to separate PRs
  • make a final rebase before the merge to clean up/squash any patches

For reviewers:

  • see that assets load faster now
  • we don't include unused assets like docsearch in examples
  • verify individual zip examples work
  • confirm StackBlitz works the same
  • no (new) errors are logged in the browser console

@XhmikosR XhmikosR force-pushed the xmr/docs-esbuild branch 3 times, most recently from 2ac7d3f to 0a4e3a3 Compare August 4, 2023 19:11
Copy link
Member

@mdo mdo left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Poked around locally, looks great!

@XhmikosR
Copy link
Member Author

XhmikosR commented Aug 6, 2023

This needs a little love regarding StackBlitz changes, so I'm going to hold off a bit for now. :)

Also, I couldn't make @docsearch/css work because libsass, which we are currently using for docs, does not load CSS partials and instead converts them to @import url(), which we definitely don't want.

@XhmikosR XhmikosR force-pushed the xmr/docs-esbuild branch 5 times, most recently from 1abfd22 to ae59a6c Compare August 22, 2023 12:50
@XhmikosR XhmikosR force-pushed the xmr/docs-esbuild branch 5 times, most recently from e69ca90 to a91c27f Compare December 23, 2023 17:23
@XhmikosR XhmikosR force-pushed the xmr/docs-esbuild branch 7 times, most recently from 2763174 to b68e1cc Compare March 6, 2024 19:00
@XhmikosR XhmikosR force-pushed the xmr/docs-esbuild branch 2 times, most recently from 521b089 to 9ec51cd Compare March 7, 2024 05:13
@julien-deramond
Copy link
Member

Quickly tried something to move the search part to its own CSS file as suggested in the description's TODO list via bea1430

Feel free to drop this commit if it's not what you had in mind.

https://deploy-preview-38993--twbs-bootstrap.netlify.app//docs/5.3/assets/css/search.css contains some duplicate code from docs.css in the :root part to define some CSS variables. But it's not that much IMO.

@XhmikosR XhmikosR marked this pull request as draft March 12, 2024 19:38
@XhmikosR XhmikosR force-pushed the xmr/docs-esbuild branch 3 times, most recently from 7fecb1a to 4a5b848 Compare March 13, 2024 06:53
@XhmikosR XhmikosR marked this pull request as ready for review March 13, 2024 06:53
@XhmikosR XhmikosR force-pushed the xmr/docs-esbuild branch 5 times, most recently from b7b48b3 to e28541b Compare March 16, 2024 06:04
Copy link
Member

@julien-deramond julien-deramond left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Great PR! Few things in comments to tackle and I think we're good to go!

I have mixed feelings about the split of docs.css, one one hand it's clearer and StackBlitz can embed only this file without the search part, on the other hand, search.css and docs.css have some duplicate code:

:root,
[data-bs-theme="light"] {
  --bd-purple: #4c0bce;
  --bd-violet: #712cf9;
  --bd-accent: #ffe484;
  --bd-violet-rgb: 112.520718, 44.062154, 249.437846;
  --bd-accent-rgb: 255, 228, 132;
  --bd-pink-rgb: 214, 51, 132;
  --bd-teal-rgb: 32, 201, 151;
  --bd-violet-bg: var(--bd-violet);
  --bd-toc-color: var(--bd-violet);
  --bd-sidebar-link-bg: rgba(var(--bd-violet-rgb), 0.1);
  --bd-callout-link: 10, 88, 202;
  --bd-callout-code-color: #ab296a;
  --bd-pre-bg: var(--bs-tertiary-bg);
}
[data-bs-theme="dark"] {
  --bd-violet: #9461fb;
  --bd-violet-bg: #712cf9;
  --bd-toc-color: var(--bs-emphasis-color);
  --bd-sidebar-link-bg: rgba(84, 33, 187, 0.5);
  --bd-callout-link: 110, 168, 254;
  --bd-callout-code-color: #e685b5;
  --bd-pre-bg: #1b1f22;

But I don't have a strong opinion, so let's try it :)

However, I'm not sure if it's needed, but the generated search.css doesn't have any legal header like docs.css; something like:

/*!
 * Bootstrap Docs (https://getbootstrap.com/)
 * Copyright 2011-2024 The Bootstrap Authors
 * Licensed under the Creative Commons Attribution 3.0 Unported License.
 * For details, see https://creativecommons.org/licenses/by/3.0/.
 */

site/layouts/partials/header.html Show resolved Hide resolved
"cssCdn" .Site.Params.cdn.css
"jsBundleCdn" .Site.Params.cdn.js_bundle
"docsVersion" .Site.Params.docs_version
"jsSnippetFile" (os.ReadFile "site/assets/js/snippets.js")
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Isn't it "site/assets/js/partials/snippets.js"?

IDK if it's linked directly, but when going to https://deploy-preview-38993--twbs-bootstrap.netlify.app/docs/5.3/components/tooltips/#tooltips-on-links and click on the StackBlitz button, the index.js is empty, and locally it's not.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This needs more debugging.

I'll try to fix it but if not I'll just drop the whole snippetFile. I'm generally not a fan of complicating things and if this means some examples don't have a StackBlitz, that's OK to me compared to the previous situation.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

BTW any help is welcome here. It seems we were evaling the script before, not sure how to keep the same behavior.

site/assets/js/partials/snippets.js Show resolved Hide resolved
@XhmikosR
Copy link
Member Author

Don't get too fixated on the license headers, it's useless but in your patch you missed to add it 😛

As for the duplicate vars, I don't care too much. I'd like them deduplicated, but I can live with it because the gains are bigger.

The rest should be fixed with the latest pushes :)

@XhmikosR XhmikosR force-pushed the xmr/docs-esbuild branch 7 times, most recently from a1c0980 to 3206c49 Compare March 18, 2024 12:55
@julien-deramond julien-deramond self-requested a review March 19, 2024 08:19
Copy link
Member

@julien-deramond julien-deramond left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Your latest modifications fix the issues I encountered during my first tests. There are a lot of use cases, I've tested locally and via Netlify deployment only the trickiest; and it works well!
Neat! LGTM!

XhmikosR and others added 5 commits March 19, 2024 11:21
Also:

* load any docs' third-party dependencies from node_modules (except for examples)
* exclude docsearch from layouts that don't use it
* preconnect to algolia only when not examples layout
* switch to `RelPermalink`
* refactor JS assets into partials
* tweak indentation
* stop extending the sdk object
* conditionally add `index.js`
@XhmikosR XhmikosR merged commit f7f0026 into main Mar 19, 2024
14 checks passed
@XhmikosR XhmikosR deleted the xmr/docs-esbuild branch March 19, 2024 09:25
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
Status: Done
Development

Successfully merging this pull request may close these issues.

Find a way to consistently use deps accross the whole codebase
3 participants