refactor: self-host KaTeX assets #6429

pranabdas · 2022-01-21T14:20:16Z

Motivation

Self-host KaTeX stylesheet and fonts instead of using external CDN. Total asset size increases about 328 KB. Please see related discussions here.

CC: @slorber

Have you read the Contributing Guidelines on pull requests?

Yes.

Test Plan

Deploy preview.

Related PRs

#4821

Josh-Cena · 2022-01-21T14:25:37Z

website/docusaurus.config.js

@@ -73,11 +73,9 @@ const config = {
  trailingSlash: isDeployPreview,
  stylesheets: [
    {
-      href: 'https://cdn.jsdelivr.net/npm/[email protected]/dist/katex.min.css',
+      // style lint fails for katex.min.css


If stylelint fails, add it to the ignore file and commit with --no-verify. I have no idea why stylelint isn't respecting the ignore option in priority to the files passed to it during precommit—eslint/prettier are able to do that

I see. Not much of a difference using the minified css though.

I think we do get a size reduction? Even if it's just a few KBs? Since we never touch the CSS, no need to keep the original :P

netlify · 2022-01-21T14:26:15Z

✔️ [V2]
Built without sensitive environment variables

🔨 Explore the source changes: 0c25d93

🔍 Inspect the deploy log: https://app.netlify.com/sites/docusaurus-2/deploys/61ecb9656a225d0007ffa609

😎 Browse the preview: https://deploy-preview-6429--docusaurus-2.netlify.app

github-actions · 2022-01-21T14:26:38Z

⚡️ Lighthouse report for the changes in this PR:

Category	Score
🟠 Performance	60
🟢 Accessibility	100
🟢 Best practices	93
🟢 SEO	100
🟢 PWA	92

Lighthouse ran on https://deploy-preview-6429--docusaurus-2.netlify.app/

website/docs/guides/markdown-features/markdown-features-math-equations.mdx

Josh-Cena · 2022-01-21T14:30:28Z

Not sure if we need so many fonts. If we never use things like \mathfrak, maybe the font files can go, or be replaced with a placeholder file? Is it possible to trick the CSS? 🤔

Josh-Cena · 2022-01-21T14:33:32Z

Of course, I'm not in favor of this move for the reasons you outlined in the docs (cache, request load, our bundle size...) but since Sebastien wants it I'll respect that😄

pranabdas · 2022-01-21T14:44:51Z

I think without bundled katex fonts, they are replaced with user installed fonts. But sometimes equations/symbols does not look good without proper fonts (sometime they don't scale proportionately, spacing not exact etc.). To ensure full LaTeX compatibility, probably we need all fonts. But there are .ttf, .woff, and .woff2 versions. We can perhaps include .woff2 version only. I think old browsers may not support it, so .woff for legacy usage, and .ttf are not generally required for web usage.

Josh-Cena · 2022-01-21T14:47:13Z

We don't support old browsers anyways. Our website doesn't polyfill flatMap so it doesn't even work on Chrome <68. woff2 is compatible enough for the browsers we target.

As for font rendering, things like SansSerif and Fraktur are never used on our website so they are safe to remove.

…quations.mdx Co-authored-by: Joshua Chen <[email protected]>

Josh-Cena · 2022-01-21T15:13:45Z

website/docs/guides/markdown-features/markdown-features-math-equations.mdx

+
+Loading stylesheets, fonts, and javascript libraries from CDN sources is a good practice for popular libraries and assets. Provided such assets are widely used across various websites, those assets will not be downloaded every time we visit a new website that uses the same assets, rather they would be cached by the browser reducing network load. In case you prefer to self-host the `katex.min.css` (along with required KaTeX fonts), you can download the latest version from [KaTeX GitHub releases](https://github.com/KaTeX/KaTeX/releases). Extract and copy `katex.min.css` and `fonts` directory (only `.woff2` font types should be enough) to docusaurus `static` directory. And in `docusaurus.config.js`, replace the css `href` from CDN url to your local path (say, `/katex/katex.css`).
+
+````js title="docusaurus.config.js"


Wrong number of ticks :D

Oops! Thank you :D

slorber · 2022-01-21T17:43:20Z

The preview does not seem to work, I think it's because of the .min.css

https://deploy-preview-6429--docusaurus-2.netlify.app/docs/markdown-features/math-equations/

Also there's a stylelint copyright issue, you should add this file in .stylelintignore or at the top of the CSS file:

/* stylelint-disable docusaurus/copyright-header */

slorber · 2022-01-21T17:45:05Z

.eslintignore

@@ -17,3 +17,4 @@ copyUntypedFiles.mjs

 packages/create-docusaurus/lib/*
 packages/create-docusaurus/templates/facebook/.eslintrc.js
+website/static/katex/katex.min.css


in .stylelintignore

Full file path in .stylelintignore seems to be problematic.

Josh-Cena · 2022-01-26T02:16:53Z

https://www.stefanjudis.com/notes/say-goodbye-to-resource-caching-across-sites-and-domains/ Oh, okay... I feel less strongly about using CDNs now. Particularly if we can tailor the bundle ourselves to make it smaller.

slorber · 2022-01-27T10:39:36Z

thanks, looks like it works fine 👍

pranabdas added 2 commits January 21, 2022 22:01

docs: self-hosting KaTeX assets

486e4e9

refactor: self-host KaTeX assets

536405d

pranabdas requested review from Josh-Cena, lex111 and slorber as code owners January 21, 2022 14:20

facebook-github-bot added the CLA Signed Signed Facebook CLA label Jan 21, 2022

Josh-Cena reviewed Jan 21, 2022

View reviewed changes

website/docs/guides/markdown-features/markdown-features-math-equations.mdx Outdated Show resolved Hide resolved

Josh-Cena added the pr: documentation This PR works on the website or other text documents in the repo. label Jan 21, 2022

pranabdas and others added 4 commits January 21, 2022 22:49

Remove .ttf and .woff font files

2a19151

Update website/docs/guides/markdown-features/markdown-features-math-e…

2e333b2

…quations.mdx Co-authored-by: Joshua Chen <[email protected]>

Merge branch 'facebook:main' into main

ebc31f1

Merge branch 'main' of https://github.com/pranabdas/docusaurus

91c1fb6

Josh-Cena reviewed Jan 21, 2022

View reviewed changes

pranabdas added 2 commits January 21, 2022 23:51

minor changes to doc, use katex.min.css, add this file to eslintignore

16e96d1

try to fix lint

5f624d8

slorber reviewed Jan 21, 2022

View reviewed changes

pranabdas and others added 3 commits January 22, 2022 09:58

try to fix lint again

40d3b6f

Merge branch 'main' into pranabdas/main

302487d

fixes

0c25d93

slorber merged commit f415da1 into facebook:main Jan 27, 2022

Josh-Cena mentioned this pull request Jan 27, 2022

docs: remove mention that CDN resources are cached cross-domain #6484

Merged

slorber mentioned this pull request Jun 15, 2022

fix(website): make KaTeX fonts available on alternative locales #7574

Merged

3 tasks

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

refactor: self-host KaTeX assets #6429

refactor: self-host KaTeX assets #6429

pranabdas commented Jan 21, 2022 •

edited

Loading

Josh-Cena Jan 21, 2022 •

edited

Loading

pranabdas Jan 21, 2022

Josh-Cena Jan 21, 2022

netlify bot commented Jan 21, 2022 •

edited

Loading

github-actions bot commented Jan 21, 2022 •

edited

Loading

Josh-Cena commented Jan 21, 2022

Josh-Cena commented Jan 21, 2022

pranabdas commented Jan 21, 2022

Josh-Cena commented Jan 21, 2022

Josh-Cena Jan 21, 2022

pranabdas Jan 21, 2022

slorber commented Jan 21, 2022 •

edited

Loading

slorber Jan 21, 2022

pranabdas Jan 22, 2022

Josh-Cena commented Jan 26, 2022

slorber commented Jan 27, 2022


		Loading stylesheets, fonts, and javascript libraries from CDN sources is a good practice for popular libraries and assets. Provided such assets are widely used across various websites, those assets will not be downloaded every time we visit a new website that uses the same assets, rather they would be cached by the browser reducing network load. In case you prefer to self-host the `katex.min.css` (along with required KaTeX fonts), you can download the latest version from [KaTeX GitHub releases](https://github.com/KaTeX/KaTeX/releases). Extract and copy `katex.min.css` and `fonts` directory (only `.woff2` font types should be enough) to docusaurus `static` directory. And in `docusaurus.config.js`, replace the css `href` from CDN url to your local path (say, `/katex/katex.css`).

		````js title="docusaurus.config.js"

refactor: self-host KaTeX assets #6429

refactor: self-host KaTeX assets #6429

Conversation

pranabdas commented Jan 21, 2022 • edited Loading

Motivation

Have you read the Contributing Guidelines on pull requests?

Test Plan

Related PRs

Josh-Cena Jan 21, 2022 • edited Loading

Choose a reason for hiding this comment

pranabdas Jan 21, 2022

Choose a reason for hiding this comment

Josh-Cena Jan 21, 2022

Choose a reason for hiding this comment

netlify bot commented Jan 21, 2022 • edited Loading

github-actions bot commented Jan 21, 2022 • edited Loading

Josh-Cena commented Jan 21, 2022

Josh-Cena commented Jan 21, 2022

pranabdas commented Jan 21, 2022

Josh-Cena commented Jan 21, 2022

Josh-Cena Jan 21, 2022

Choose a reason for hiding this comment

pranabdas Jan 21, 2022

Choose a reason for hiding this comment

slorber commented Jan 21, 2022 • edited Loading

slorber Jan 21, 2022

Choose a reason for hiding this comment

pranabdas Jan 22, 2022

Choose a reason for hiding this comment

Josh-Cena commented Jan 26, 2022

slorber commented Jan 27, 2022

pranabdas commented Jan 21, 2022 •

edited

Loading

Josh-Cena Jan 21, 2022 •

edited

Loading

netlify bot commented Jan 21, 2022 •

edited

Loading

github-actions bot commented Jan 21, 2022 •

edited

Loading

slorber commented Jan 21, 2022 •

edited

Loading