From e2b028d8c1c5f851dca7d598ccb17f38696b1f52 Mon Sep 17 00:00:00 2001 From: Ayu Date: Wed, 17 Apr 2024 19:21:29 +0100 Subject: [PATCH] feat(website): add docsearch (#966) * feat(website): initial docsearch implementation * fix: style docsearch modal * fix: make searchbox slightly smaller * style: make hit component function declaration consistent * fix: use url paths * fix: clean up docs and use semantic markup better for algolia crawling --- pnpm-lock.yaml | 127 +++++++++++++++--- .../app/components/docs/DocsHeader.module.css | 101 +++++++++++++- website/app/components/docs/DocsHeader.tsx | 107 ++++++++++++--- .../app/components/layout/ContentHeader.tsx | 1 - website/app/components/layout/Header.tsx | 1 - website/app/root.tsx | 11 +- website/app/routes/docs.tsx | 2 +- website/app/utils/mdx/getMdxComponent.tsx | 14 +- website/docs/api/axis-registry.mdx | 15 +-- website/docs/api/font-id.mdx | 14 +- website/docs/api/fontlist.mdx | 16 +-- website/docs/api/fonts.mdx | 19 ++- website/docs/api/introduction.mdx | 10 +- website/docs/api/stats.mdx | 17 +-- website/docs/api/variable.mdx | 16 +-- website/docs/api/version.mdx | 14 +- website/docs/getting-started/cdn.mdx | 16 +-- website/docs/getting-started/display.mdx | 8 +- website/docs/getting-started/faces-mixin.mdx | 27 ++-- .../docs/getting-started/generator-mixin.mdx | 20 +-- website/docs/getting-started/install.mdx | 8 +- website/docs/getting-started/introduction.mdx | 6 +- .../docs/getting-started/material-icons.mdx | 6 +- .../docs/getting-started/material-symbols.mdx | 30 ++--- website/docs/getting-started/migrate-v5.mdx | 13 +- website/docs/getting-started/preload.mdx | 4 +- website/docs/getting-started/sass-import.mdx | 10 +- website/docs/getting-started/subsets.mdx | 4 +- website/docs/getting-started/variable.mdx | 14 +- website/docs/guides/angular.mdx | 12 +- website/docs/guides/nextjs.mdx | 14 +- website/docs/guides/qwik.mdx | 21 +-- website/docs/guides/remix.mdx | 34 ++++- website/docs/guides/svelte.mdx | 8 +- website/docs/guides/vue.mdx | 9 +- website/docs/guides/webpack.mdx | 12 +- website/package.json | 2 + 37 files changed, 479 insertions(+), 284 deletions(-) diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml index 37903df572..c91422b962 100644 --- a/pnpm-lock.yaml +++ b/pnpm-lock.yaml @@ -121,7 +121,7 @@ importers: version: 5.3.3 vitest: specifier: ^0.34.4 - version: 0.34.6 + version: 0.34.6(sass@1.62.1) vitest-environment-miniflare: specifier: ^2.14.1 version: 2.14.1(vitest@0.34.6) @@ -148,7 +148,7 @@ importers: version: 5.3.3 vitest: specifier: ^0.34.4 - version: 0.34.6 + version: 0.34.6(sass@1.62.1) vitest-environment-miniflare: specifier: ^2.14.1 version: 2.14.1(vitest@0.34.6) @@ -325,6 +325,12 @@ importers: website: dependencies: + '@docsearch/css': + specifier: ^3.6.0 + version: 3.6.0 + '@docsearch/react': + specifier: ^3.6.0 + version: 3.6.0(@algolia/client-search@4.23.3)(@types/react@18.2.78)(react-dom@19.0.0-canary-96c584661-20240412)(react@19.0.0-canary-96c584661-20240412)(search-insights@2.13.0) '@esbuild-plugins/node-resolve': specifier: ^0.2.2 version: 0.2.2(esbuild@0.20.2) @@ -484,7 +490,7 @@ importers: version: 5.4.5 vite: specifier: ^5.2.8 - version: 5.2.8(@types/node@20.12.7) + version: 5.2.8(@types/node@20.12.7)(sass@1.62.1) vite-plugin-cjs-interop: specifier: ^2.1.0 version: 2.1.0 @@ -498,6 +504,50 @@ packages: resolution: {integrity: sha512-1Yjs2SvM8TflER/OD3cOjhWWOZb58A2t7wpE2S9XfBYTiIl+XFhQG2bjy4Pu1I+EAlCNUzRDYDdFwFYUKvXcIA==} engines: {node: '>=0.10.0'} + /@algolia/autocomplete-core@1.9.3(@algolia/client-search@4.23.3)(algoliasearch@4.23.3)(search-insights@2.13.0): + resolution: {integrity: sha512-009HdfugtGCdC4JdXUbVJClA0q0zh24yyePn+KUGk3rP7j8FEe/m5Yo/z65gn6nP/cM39PxpzqKrL7A6fP6PPw==} + dependencies: + '@algolia/autocomplete-plugin-algolia-insights': 1.9.3(@algolia/client-search@4.23.3)(algoliasearch@4.23.3)(search-insights@2.13.0) + '@algolia/autocomplete-shared': 1.9.3(@algolia/client-search@4.23.3)(algoliasearch@4.23.3) + transitivePeerDependencies: + - '@algolia/client-search' + - algoliasearch + - search-insights + dev: false + + /@algolia/autocomplete-plugin-algolia-insights@1.9.3(@algolia/client-search@4.23.3)(algoliasearch@4.23.3)(search-insights@2.13.0): + resolution: {integrity: sha512-a/yTUkcO/Vyy+JffmAnTWbr4/90cLzw+CC3bRbhnULr/EM0fGNvM13oQQ14f2moLMcVDyAx/leczLlAOovhSZg==} + peerDependencies: + search-insights: '>= 1 < 3' + dependencies: + '@algolia/autocomplete-shared': 1.9.3(@algolia/client-search@4.23.3)(algoliasearch@4.23.3) + search-insights: 2.13.0 + transitivePeerDependencies: + - '@algolia/client-search' + - algoliasearch + dev: false + + /@algolia/autocomplete-preset-algolia@1.9.3(@algolia/client-search@4.23.3)(algoliasearch@4.23.3): + resolution: {integrity: sha512-d4qlt6YmrLMYy95n5TB52wtNDr6EgAIPH81dvvvW8UmuWRgxEtY0NJiPwl/h95JtG2vmRM804M0DSwMCNZlzRA==} + peerDependencies: + '@algolia/client-search': '>= 4.9.1 < 6' + algoliasearch: '>= 4.9.1 < 6' + dependencies: + '@algolia/autocomplete-shared': 1.9.3(@algolia/client-search@4.23.3)(algoliasearch@4.23.3) + '@algolia/client-search': 4.23.3 + algoliasearch: 4.23.3 + dev: false + + /@algolia/autocomplete-shared@1.9.3(@algolia/client-search@4.23.3)(algoliasearch@4.23.3): + resolution: {integrity: sha512-Wnm9E4Ye6Rl6sTTqjoymD+l8DjSTHsHboVRYrKgEt8Q7UHm9nYbqhN/i0fhUYA3OAEH7WA8x3jfpnmJm3rKvaQ==} + peerDependencies: + '@algolia/client-search': '>= 4.9.1 < 6' + algoliasearch: '>= 4.9.1 < 6' + dependencies: + '@algolia/client-search': 4.23.3 + algoliasearch: 4.23.3 + dev: false + /@algolia/cache-browser-local-storage@4.23.3: resolution: {integrity: sha512-vRHXYCpPlTDE7i6UOy2xE03zHF2C8MEFjPN2v7fRbqVpcOvAUQK81x3Kc21xyb5aSIpYCjWCZbYZuz8Glyzyyg==} dependencies: @@ -1348,6 +1398,39 @@ packages: resolution: {integrity: sha512-+kWfpCkqiepwAKXyHoE0gnkPgkLhz0/9HOBIGhHRsUvUKvhUtm3mbqqoGRWgF1qcjzrDUBbrrOq4MYHfFtc2RA==} dev: true + /@docsearch/css@3.6.0: + resolution: {integrity: sha512-+sbxb71sWre+PwDK7X2T8+bhS6clcVMLwBPznX45Qu6opJcgRjAp7gYSDzVFp187J+feSj5dNBN1mJoi6ckkUQ==} + dev: false + + /@docsearch/react@3.6.0(@algolia/client-search@4.23.3)(@types/react@18.2.78)(react-dom@19.0.0-canary-96c584661-20240412)(react@19.0.0-canary-96c584661-20240412)(search-insights@2.13.0): + resolution: {integrity: sha512-HUFut4ztcVNmqy9gp/wxNbC7pTOHhgVVkHVGCACTuLhUKUhKAF9KYHJtMiLUJxEqiFLQiuri1fWF8zqwM/cu1w==} + peerDependencies: + '@types/react': '>= 16.8.0 < 19.0.0' + react: '>= 16.8.0 < 19.0.0' + react-dom: '>= 16.8.0 < 19.0.0' + search-insights: '>= 1 < 3' + peerDependenciesMeta: + '@types/react': + optional: true + react: + optional: true + react-dom: + optional: true + search-insights: + optional: true + dependencies: + '@algolia/autocomplete-core': 1.9.3(@algolia/client-search@4.23.3)(algoliasearch@4.23.3)(search-insights@2.13.0) + '@algolia/autocomplete-preset-algolia': 1.9.3(@algolia/client-search@4.23.3)(algoliasearch@4.23.3) + '@docsearch/css': 3.6.0 + '@types/react': 18.2.78 + algoliasearch: 4.23.3 + react: 19.0.0-canary-96c584661-20240412 + react-dom: 19.0.0-canary-96c584661-20240412(react@19.0.0-canary-96c584661-20240412) + search-insights: 2.13.0 + transitivePeerDependencies: + - '@algolia/client-search' + dev: false + /@emotion/hash@0.9.1: resolution: {integrity: sha512-gJB6HLm5rYwSLI6PQa+X1t5CFGrv1J1TWG+sOyMCeKz2ojaj6Fnl/rZEspogG+cvqbt4AE/2eIyD2QfLKTBNlQ==} dev: true @@ -3173,7 +3256,7 @@ packages: tar-fs: 2.1.1 tsconfig-paths: 4.2.0 typescript: 5.4.5 - vite: 5.2.8(@types/node@20.12.7) + vite: 5.2.8(@types/node@20.12.7)(sass@1.62.1) ws: 7.5.9 transitivePeerDependencies: - '@types/node' @@ -4194,7 +4277,7 @@ packages: lodash: 4.17.21 mlly: 1.6.1 outdent: 0.8.0 - vite: 5.2.8(@types/node@20.12.7) + vite: 5.2.8(@types/node@20.12.7)(sass@1.62.1) vite-node: 1.5.0(@types/node@20.12.7) transitivePeerDependencies: - '@types/node' @@ -4950,6 +5033,7 @@ packages: readdirp: 3.6.0 optionalDependencies: fsevents: 2.3.3 + dev: true /chokidar@3.6.0: resolution: {integrity: sha512-7VT13fmjotKpGipCW9JEQAusEPE+Ei8nl6/g4FBAmIm0GOOLMua9NDDo/DWp0ZAxCr3cPq5ZpBqmPAQgDda2Pw==} @@ -6430,7 +6514,7 @@ packages: '@typescript-eslint/utils': 6.7.3(eslint@8.50.0)(typescript@5.3.3) eslint: 8.50.0 typescript: 5.3.3 - vitest: 0.34.6 + vitest: 0.34.6(sass@1.62.1) transitivePeerDependencies: - supports-color dev: true @@ -6450,7 +6534,7 @@ packages: '@typescript-eslint/utils': 6.7.3(eslint@8.55.0)(typescript@5.4.5) eslint: 8.55.0 typescript: 5.4.5 - vitest: 0.34.6 + vitest: 0.34.6(sass@1.62.1) transitivePeerDependencies: - supports-color dev: true @@ -7649,6 +7733,7 @@ packages: /immutable@4.3.0: resolution: {integrity: sha512-0AOCmOip+xgJwEVTQj1EfiDDOkPmuyllDuTuEX+DDXUgapLAsBIfkg3sxCYyCEA8mQqZrrxPUGjcOQ2JS3WLkg==} + dev: true /import-fresh@3.3.0: resolution: {integrity: sha512-veYYhQa+D1QBKznvhUHxb8faxlrwUnxseDAbAp457E0wLNio2bOSKnjYDhMj+YiAq61xrMGhQk9iXVk5FzgQMw==} @@ -11235,6 +11320,7 @@ packages: chokidar: 3.5.3 immutable: 4.3.0 source-map-js: 1.0.2 + dev: true /sax@1.2.4: resolution: {integrity: sha512-NqVDv9TpANUjFm0N8uM5GxL36UgKi9/atZw+x7YFnQ8ckwFGKrl4xX4yWtrey3UJm5nP1kUbnYgLopqWNSRhWw==} @@ -11459,6 +11545,7 @@ packages: /source-map-js@1.0.2: resolution: {integrity: sha512-R0XvVJ9WusLiqTCEiGCmICCMplcCkIwwR11mOSD9CR5u+IXYdiseeEuXCVAjS54zqwkLcPNnmU4OeJ6tUrWhDw==} engines: {node: '>=0.10.0'} + dev: true /source-map-js@1.2.0: resolution: {integrity: sha512-itJW8lvSA0TXEphiRoawsCksnlf8SyvmFzIhltqAHluXd88pkCd+cXJVHTDwdCr0IzwptSm035IHQktUu1QUMg==} @@ -12463,7 +12550,7 @@ packages: mlly: 1.4.2 pathe: 1.1.2 picocolors: 1.0.0 - vite: 4.5.1(@types/node@20.12.7)(sass@1.62.1) + vite: 4.5.1(@types/node@20.12.7) transitivePeerDependencies: - '@types/node' - less @@ -12475,7 +12562,7 @@ packages: - terser dev: false - /vite-node@0.34.6(@types/node@20.12.7): + /vite-node@0.34.6(@types/node@20.12.7)(sass@1.62.1): resolution: {integrity: sha512-nlBMJ9x6n7/Amaz6F3zJ97EBwR2FkzhBRxF5e+jE6LA3yi6Wtc2lyTij1OnDMIr34v5g/tVQtsVAzhT0jc5ygA==} engines: {node: '>=v14.18.0'} hasBin: true @@ -12485,7 +12572,7 @@ packages: mlly: 1.6.1 pathe: 1.1.2 picocolors: 1.0.0 - vite: 5.2.8(@types/node@20.12.7) + vite: 5.2.8(@types/node@20.12.7)(sass@1.62.1) transitivePeerDependencies: - '@types/node' - less @@ -12506,7 +12593,7 @@ packages: debug: 4.3.4 pathe: 1.1.2 picocolors: 1.0.0 - vite: 5.2.8(@types/node@20.12.7) + vite: 5.2.8(@types/node@20.12.7)(sass@1.62.1) transitivePeerDependencies: - '@types/node' - less @@ -12539,13 +12626,13 @@ packages: debug: 4.3.4 globrex: 0.1.2 tsconfck: 3.0.3(typescript@5.4.5) - vite: 5.2.8(@types/node@20.12.7) + vite: 5.2.8(@types/node@20.12.7)(sass@1.62.1) transitivePeerDependencies: - supports-color - typescript dev: true - /vite@4.5.1(@types/node@20.12.7)(sass@1.62.1): + /vite@4.5.1(@types/node@20.12.7): resolution: {integrity: sha512-AXXFaAJ8yebyqzoNB9fu2pHoo/nWX+xZlaRwoeYUxEqBO+Zj4msE5G+BhGBll9lYEKv9Hfks52PAF2X7qDYXQA==} engines: {node: ^14.18.0 || >=16.0.0} hasBin: true @@ -12577,12 +12664,11 @@ packages: esbuild: 0.18.20 postcss: 8.4.38 rollup: 3.29.4 - sass: 1.62.1 optionalDependencies: fsevents: 2.3.3 dev: false - /vite@5.2.8(@types/node@20.12.7): + /vite@5.2.8(@types/node@20.12.7)(sass@1.62.1): resolution: {integrity: sha512-OyZR+c1CE8yeHw5V5t59aXsUPPVTHMDjEZz8MgguLL/Q7NblxhZUlTu9xSPqlsUO/y+X7dlU05jdhvyycD55DA==} engines: {node: ^18.0.0 || >=20.0.0} hasBin: true @@ -12614,6 +12700,7 @@ packages: esbuild: 0.20.2 postcss: 8.4.38 rollup: 4.14.2 + sass: 1.62.1 optionalDependencies: fsevents: 2.3.3 dev: true @@ -12629,7 +12716,7 @@ packages: '@miniflare/shared': 2.14.1 '@miniflare/shared-test-environment': 2.14.1 undici: 5.20.0 - vitest: 0.34.6 + vitest: 0.34.6(sass@1.62.1) transitivePeerDependencies: - bufferutil - utf-8-validate @@ -12687,7 +12774,7 @@ packages: strip-literal: 1.3.0 tinybench: 2.5.1 tinypool: 0.7.0 - vite: 4.5.1(@types/node@20.12.7)(sass@1.62.1) + vite: 4.5.1(@types/node@20.12.7) vite-node: 0.34.4(@types/node@20.12.7) why-is-node-running: 2.2.2 transitivePeerDependencies: @@ -12700,7 +12787,7 @@ packages: - terser dev: false - /vitest@0.34.6: + /vitest@0.34.6(sass@1.62.1): resolution: {integrity: sha512-+5CALsOvbNKnS+ZHMXtuUC7nL8/7F1F2DnHGjSsszX8zCjWSSviphCb/NuS9Nzf4Q03KyyDRBAXhF/8lffME4Q==} engines: {node: '>=v14.18.0'} hasBin: true @@ -12752,8 +12839,8 @@ packages: strip-literal: 1.3.0 tinybench: 2.5.1 tinypool: 0.7.0 - vite: 5.2.8(@types/node@20.12.7) - vite-node: 0.34.6(@types/node@20.12.7) + vite: 5.2.8(@types/node@20.12.7)(sass@1.62.1) + vite-node: 0.34.6(@types/node@20.12.7)(sass@1.62.1) why-is-node-running: 2.2.2 transitivePeerDependencies: - less diff --git a/website/app/components/docs/DocsHeader.module.css b/website/app/components/docs/DocsHeader.module.css index df2dfc5ec8..9ec5f5bc0a 100644 --- a/website/app/components/docs/DocsHeader.module.css +++ b/website/app/components/docs/DocsHeader.module.css @@ -1,5 +1,104 @@ /* DocsHeader */ - .title { color: var(--mantine-color-purple-0); } + +.search-button { + height: 40px; + width: 240px; + + padding: 8px 16px; + gap: 10px; + + border-radius: 4px; + + font-size: 15px; + + @mixin light { + background-color: var(--mantine-color-background-2); + color: var(--mantine-color-text-1); + } + + @mixin dark { + background-color: var(--mantine-color-background-6); + color: var(--mantine-color-text-0); + } + + p { + opacity: 0.5; + } + + @media (max-width: $mantine-breakpoint-sm) { + display: none; + } +} + +.docsearch { + --docsearch-primary-color: var(--mantine-color-purple-0); + --docsearch-container-background: rgba(52, 58, 70, 0.8); + --docsearch-modal-shadow: none; + --docsearch-searchbox-shadow: 0 0 0 2px var(--mantine-color-purpleHover-5); + --docsearch-hit-height: 48px; + --docsearch-searchbox-height: 64px; + + @mixin light { + --docsearch-modal-background: var(--mantine-color-background-0); + --docsearch-highlight-color: var(--mantine-color-purple-0); + --docsearch-hit-background: var(--mantine-color-background-1); + + --docsearch-text-color: var(--mantine-color-text-1); + } + + @mixin dark { + --docsearch-modal-background: var(--mantine-color-background-5); + --docsearch-hit-background: var(--mantine-color-background-6); + --docsearch-highlight-color: var(--mantine-color-purple-0); + + --docsearch-text-color: var(--mantine-color-text-0); + --docsearch-hit-color: rgba(255, 255, 255, 0.7); + } + + header { + border-radius: 16px 16px 0 0; + padding-bottom: 16px; + background-color: var(--docsearch-modal-background); + + form { + @mixin light { + background-color: var(--mantine-color-background-0); + color: var(--mantine-color-text-1); + } + + @mixin dark { + background-color: var(--mantine-color-background-5); + color: var(--mantine-color-text-0); + } + } + } + + li { + padding-bottom: 10px; + + a { + box-shadow: none; + } + } + + footer { + @mixin light { + background-color: var(--mantine-color-background-0); + color: var(--mantine-color-text-1); + } + + @mixin dark { + border-top: 2px solid var(--mantine-color-background-3); + box-shadow: none; + background-color: var(--mantine-color-background-5); + color: var(--mantine-color-text-0); + } + + li { + padding-bottom: 0; + } + } +} diff --git a/website/app/components/docs/DocsHeader.tsx b/website/app/components/docs/DocsHeader.tsx index c15b1177f9..f91217f400 100644 --- a/website/app/components/docs/DocsHeader.tsx +++ b/website/app/components/docs/DocsHeader.tsx @@ -1,39 +1,106 @@ -import { Title } from '@mantine/core'; +import '@docsearch/css'; + +import { type DocSearchModal as DocSearchModalComponent } from '@docsearch/react'; +import { Group, Modal, Text, Title, UnstyledButton } from '@mantine/core'; +import { useDisclosure, useMounted } from '@mantine/hooks'; +import { Link, useNavigate } from '@remix-run/react'; +import { lazy, type LazyExoticComponent, useRef } from 'react'; import { ContentHeader } from '@/components/layout/ContentHeader'; +import { IconSearch } from '../icons/Search'; import classes from './DocsHeader.module.css'; -// TODO: Implement DocSearch -/* const DocsSearchBar = ({ ...others }: TextInputProps) => { - const { ref, focused } = useFocusWithin(); - const [inputValue, setInputValue] = useState(''); +interface HitProps { + hit: { url: string }; + children: React.ReactNode; +} - const onChange = (event: React.ChangeEvent) => { - setInputValue(event.currentTarget.value); - }; +const Hit = ({ hit, children }: HitProps) => { + const url = new URL(hit.url); + // If URL comes from fontsource.org, use the pathname + // else, become an external link + if (url.hostname === 'fontsource.org') { + return {children}; + } return ( - } - {...others} - /> + + {children} + + ); +}; + +const DocSearchModal: LazyExoticComponent = + lazy( + async () => + // @ts-expect-error allow dynamic import with no type declarations + await import('@docsearch/react/modal').then((mod) => ({ + default: mod.DocSearchModal, + })), ); -}; */ export const DocsHeader = () => { + // Prevent SSR hydration error where window is not defined + const mounted = useMounted(); + + const searchButtonRef = useRef(null); + const [searchOpen, { open, close }] = useDisclosure(false, { + onClose: () => { + searchButtonRef.current?.focus(); + }, + }); + + // Docsearch modal navigation + const navigate = useNavigate(); + const navigator = useRef({ + navigate({ itemUrl }: { itemUrl?: string }) { + if (itemUrl) { + navigate(itemUrl); + } + }, + }).current; + return ( Documentation + + + + Search documentation + + + + {mounted && ( + + + + + + )} + ); }; diff --git a/website/app/components/layout/ContentHeader.tsx b/website/app/components/layout/ContentHeader.tsx index adc35f6bdf..fa3ae1a861 100644 --- a/website/app/components/layout/ContentHeader.tsx +++ b/website/app/components/layout/ContentHeader.tsx @@ -6,7 +6,6 @@ import classes from './ContentHeader.module.css'; export const ContentHeader = ({ ...other }: ContainerProps) => { return ( - {/* @ts-expect-error - Mantine v7 typing errors */} ); diff --git a/website/app/components/layout/Header.tsx b/website/app/components/layout/Header.tsx index 7294db1613..06f31b9def 100644 --- a/website/app/components/layout/Header.tsx +++ b/website/app/components/layout/Header.tsx @@ -130,7 +130,6 @@ export const Header = ({ ...other }: ContainerProps) => { return ( <> - {/* @ts-expect-error - Mantine v7 typing errors */} diff --git a/website/app/root.tsx b/website/app/root.tsx index efabeff93a..3fce93271d 100644 --- a/website/app/root.tsx +++ b/website/app/root.tsx @@ -8,6 +8,7 @@ import '@mantine/core/styles/UnstyledButton.css'; import '@mantine/core/styles/VisuallyHidden.css'; import '@mantine/core/styles/Popover.css'; import '@mantine/core/styles/Group.css'; +import '@mantine/core/styles/ModalBase.css'; import '@mantine/core/styles/Input.css'; import '@mantine/core/styles/Flex.css'; import '@mantine/core/styles/InlineInput.css'; @@ -29,12 +30,14 @@ import '@mantine/core/styles/Combobox.css'; import '@mantine/core/styles/ActionIcon.css'; import '@mantine/core/styles/Button.css'; // Navigation +import '@mantine/core/styles/Burger.css'; import '@mantine/core/styles/NavLink.css'; import '@mantine/core/styles/Tabs.css'; // Feedback import '@mantine/core/styles/Skeleton.css'; // Overlays import '@mantine/core/styles/Menu.css'; +import '@mantine/core/styles/Modal.css'; import '@mantine/core/styles/Tooltip.css'; // Typography import '@mantine/core/styles/Code.css'; @@ -47,7 +50,6 @@ import '@mantine/core/styles/Title.css'; import '@/styles/global.css'; import interLatinURL from '@fontsource-variable/inter/files/inter-latin-wght-normal.woff2?url'; -import sourceCodeProLatinURL from '@fontsource-variable/source-code-pro/files/source-code-pro-latin-wght-normal.woff2?url'; import { ColorSchemeScript, MantineProvider } from '@mantine/core'; import type { HeadersFunction, @@ -86,13 +88,6 @@ export const links: LinksFunction = () => [ crossOrigin: 'anonymous', href: interLatinURL, }, - { - rel: 'preload', - as: 'font', - type: 'font/woff2', - crossOrigin: 'anonymous', - href: sourceCodeProLatinURL, - }, { rel: 'apple-touch-icon', sizes: '180x180', diff --git a/website/app/routes/docs.tsx b/website/app/routes/docs.tsx index b64dbe4db7..6f4fc2594f 100644 --- a/website/app/routes/docs.tsx +++ b/website/app/routes/docs.tsx @@ -21,7 +21,7 @@ export default function Docs() { - + diff --git a/website/app/utils/mdx/getMdxComponent.tsx b/website/app/utils/mdx/getMdxComponent.tsx index 2a44e5c6d7..4f52776483 100644 --- a/website/app/utils/mdx/getMdxComponent.tsx +++ b/website/app/utils/mdx/getMdxComponent.tsx @@ -10,16 +10,22 @@ import { PackageManagerCode } from '@/components/code/PackageManagerCode'; const mdxComponents = { // Typography h1: (props: any) => ( - + <> + <Title order={1} fw={700} fz={28} mt="lg" mb="sm" {...props} /> + <Divider mb="sm" {...props} /> + </> ), h2: (props: any) => ( - <Title order={2} fw={700} fz={24} mt="lg" mb="sm" {...props} /> + <> + <Title order={2} fw={700} fz={22} mt="lg" mb="sm" {...props} /> + <Divider mb="sm" {...props} /> + </> ), h3: (props: any) => ( - <Title order={3} fw={700} fz={18} mt="lg" mb="sm" {...props} /> + <Title order={3} fw={700} fz={16} mt="lg" mb="sm" {...props} /> ), h4: (props: any) => ( - <Title order={4} fw={700} fz={16} mt="lg" mb="sm" {...props} /> + <Title order={4} fw={700} fz={15} mt="lg" mb="sm" {...props} /> ), p: (props: any) => <Text fw={400} fz={15} {...props} />, diff --git a/website/docs/api/axis-registry.mdx b/website/docs/api/axis-registry.mdx index 889cf2e685..ec0f96f923 100644 --- a/website/docs/api/axis-registry.mdx +++ b/website/docs/api/axis-registry.mdx @@ -3,21 +3,19 @@ title: Axis Registry section: Reference --- -## Axis Registry - ---- +# Axis Registry The Axis Registry endpoint gives detailed descriptions of variable axis tags and their corresponding values. -### HTTP Request +## HTTP Request - `GET https://api.fontsource.org/v1/axis-registry` -### Response +## Response The API response for the Fontlist endpoint is a JSON object. -#### Attributes: +### Attributes: Returns an object of: @@ -27,8 +25,7 @@ Returns an object of: <br /> -**AxisRegistryItem:** - +#### AxisRegistryItem: | Attribute | Type | Description | | ----------- | ------ | ------------------------------- | @@ -39,7 +36,7 @@ Returns an object of: | default | number | Default value for axis | | precision | number | Precision | -#### Response example: +### Response example: ```json { diff --git a/website/docs/api/font-id.mdx b/website/docs/api/font-id.mdx index b62bc95fbf..ea64c1acca 100644 --- a/website/docs/api/font-id.mdx +++ b/website/docs/api/font-id.mdx @@ -3,21 +3,19 @@ title: Font ID section: Reference --- -## Font ID - ---- +# Font ID The Font ID endpoint allows you to retrieve detailed information about a specific font supported by Fontsource. -### HTTP Request +## HTTP Request - `GET https://api.fontsource.org/v1/fonts/{id}` -### Response +## Response The API response for the Font ID endpoint is a JSON object that provides comprehensive details about the font. -#### Attributes: +### Attributes: Returns an object with: @@ -41,7 +39,7 @@ Returns an object with: Variants is an object that creates records starting with `weight`, `style`, `subset` followed by a URL object containing each supported file format (`woff2`, `woff`, `ttf`). -#### Response example: +### Response example: ```json { @@ -74,7 +72,7 @@ Variants is an object that creates records starting with `weight`, `style`, `sub } } ``` -#### Example: +### Example: - `GET https://api.fontsource.org/v1/fonts/abel` - `GET https://api.fontsource.org/v1/fonts/open-sans` diff --git a/website/docs/api/fontlist.mdx b/website/docs/api/fontlist.mdx index 54cc3d692c..5141e507fd 100644 --- a/website/docs/api/fontlist.mdx +++ b/website/docs/api/fontlist.mdx @@ -3,22 +3,20 @@ title: Fontlist section: Reference --- -## Fontlist - ---- +# Fontlist The Fontlist endpoint provides an object that contains a list of fonts and their associated properties. -### HTTP Request +## HTTP Request - `GET https://api.fontsource.org/fontlist` - `GET https://api.fontsource.org/fontlist?{query}` -### Response +## Response The API response for the Fontlist endpoint is a JSON object that represents the available fonts and their corresponding types. -#### Attributes: +### Attributes Returns an object of: @@ -27,7 +25,7 @@ Returns an object of: | [id] | string | The font ID | | type | google | icons | other | The font type | -#### Response example: +### Response example ```json { @@ -39,7 +37,7 @@ Returns an object of: } ``` -### Queries +## Queries The Fontlist API supports the following queries without values: @@ -55,7 +53,7 @@ The Fontlist API supports the following queries without values: | version | Font version | string | | type | Font type | string | -#### Example: +### Example - `GET https://api.fontsource.org/fontlist?family` - `GET https://api.fontsource.org/fontlist?subsets` diff --git a/website/docs/api/fonts.mdx b/website/docs/api/fonts.mdx index 02a9756604..2d0c0b611a 100644 --- a/website/docs/api/fonts.mdx +++ b/website/docs/api/fonts.mdx @@ -3,22 +3,20 @@ title: Fonts section: Reference --- -## Fonts - ---- +# Fonts The Fonts endpoint provides an array of individual font objects. -### HTTP Request +## HTTP Request - `GET https://api.fontsource.org/v1/fonts` - `GET https://api.fontsource.org/v1/fonts?{query}` -### Response +## Response The API response for the Fonts endpoint is an array of font objects. Each font object represents a specific font and provides detailed information about it. -#### Attributes: +### Attributes Returns an array of: @@ -36,7 +34,7 @@ Returns an array of: | version | string | Font version | | type | string | Font type | -#### Response example: +### Response example ```json [ @@ -57,7 +55,7 @@ Returns an array of: ] ``` -### Queries +## Queries The Fonts endpoint allows you to send queries to filter the list of fonts. Multiple queries can be combined using the & operator. Attributes in arrays can be separated using a comma separator `,` which acts as an AND operator. @@ -65,11 +63,10 @@ The Fonts endpoint allows you to send queries to filter the list of fonts. Multi You can include additional queries in the URL to filter the responses based on specific criteria. For example, [`api.fontsource.org/v1/fonts?subsets=latin,latin-ext&variable=true`](https://api.fontsource.org/v1/fonts?subsets=latin,latin-ext&variable=true) will return fonts that match subsets `latin` and `latin-ext`, as well as if it is a variable font. -#### Options +### Options You can use the following queries to filter the list of fonts: - | Query | Type | Example | | ------------ | -------- | ----------------------- | | id | string | id=roboto | @@ -84,7 +81,7 @@ You can use the following queries to filter the list of fonts: | version | string | version=v14 | | type | string | type=google | -#### Example: +### Example - `GET https://api.fontsource.org/v1/fonts?subsets=latin,latin-ext&variable=true` - `GET https://api.fontsource.org/v1/fonts?weights=400,900&styles=normal` diff --git a/website/docs/api/introduction.mdx b/website/docs/api/introduction.mdx index ecd10be6b6..40cf9ece32 100644 --- a/website/docs/api/introduction.mdx +++ b/website/docs/api/introduction.mdx @@ -3,9 +3,7 @@ title: Getting Started API section: Setup --- -## Introduction - ---- +# Introduction The Fontsource API provides developers with access to information about the fonts supported by the Fontsource repository. @@ -13,11 +11,9 @@ The Fontsource API provides developers with access to information about the font ## Usage ---- - The Fontsource API is a read-only API that can be accessed by any HTTP client. An example URL that accepts a GET request is [`api.fontsource.org/v1/fonts`](https://api.fontsource.org/v1/fonts). -### Errors +## Errors | Code | Description | | ---- | ------------------------------------ | @@ -28,7 +24,7 @@ The Fontsource API is a read-only API that can be accessed by any HTTP client. A | 429 | The request was rate limited | | 500 | An internal server error occurred | -### Limits +## Limits - We reserve the right to add more properties to objects, but will never change or remove them. - While the intention is not to throttle the API, we reserve the right to do so if necessary under fair use. The current hard limit is 2500 requests per 10 seconds but constant usage at this rate can result in a temporary ban. diff --git a/website/docs/api/stats.mdx b/website/docs/api/stats.mdx index 9929a4e304..974e35d795 100644 --- a/website/docs/api/stats.mdx +++ b/website/docs/api/stats.mdx @@ -3,21 +3,19 @@ title: Stats section: Reference --- -## Stats - ---- +# Stats The Stats endpoint provides download statistics for each font. -### HTTP Request +## HTTP Request - `GET https://api.fontsource.org/v1/stats/{id}` -### Response +## Response The API response for the Stats endpoint is a JSON object that provides download statistics for each font. -#### Attributes: +### Attributes Returns an object with: @@ -29,8 +27,7 @@ Returns an object with: <br /> - -**DownloadStats:** +#### DownloadStats | Attribute | Type | Description | | ------------------- | ------ | -------------------------- | @@ -39,7 +36,7 @@ Returns an object with: | jsDelivrHitsTotal | number | Total jsDelivr hits | | jsDelivrHitsMonthly | number | Monthly jsDelivr hits | -#### Response example: +### Response example ```json { @@ -64,7 +61,7 @@ Returns an object with: } ``` -#### Example: +### Example - `GET https://api.fontsource.org/v1/stats/abel` - `GET https://api.fontsource.org/v1/stats/open-sans` diff --git a/website/docs/api/variable.mdx b/website/docs/api/variable.mdx index 04ce70fa3c..62017d44e8 100644 --- a/website/docs/api/variable.mdx +++ b/website/docs/api/variable.mdx @@ -3,21 +3,19 @@ title: Variable section: Reference --- -## Variable - ---- +# Variable The Variable endpoint allows you get specific axis data for a variable font. -### HTTP Request +## HTTP Request - `GET https://api.fontsource.org/v1/variable/{id}` -### Response +## Response The API response for the Variable endpoint is a JSON object that provides axis data for a variable font. -#### Attributes: +### Attributes Returns an object with: @@ -28,7 +26,7 @@ Returns an object with: <br /> -**AxesData:** +#### AxesData | Attribute | Type | Description | | --------- | ------ | ------------- | @@ -37,7 +35,7 @@ Returns an object with: | max | number | Maximum value | | step | number | Step value | -#### Response example: +### Response example ```json { @@ -59,7 +57,7 @@ Returns an object with: } ``` -#### Example: +### Example - `GET https://api.fontsource.org/v1/variable/inter` - `GET https://api.fontsource.org/v1/variable/roboto-flex` diff --git a/website/docs/api/version.mdx b/website/docs/api/version.mdx index 5cd7c22bc3..8e4f6f3acb 100644 --- a/website/docs/api/version.mdx +++ b/website/docs/api/version.mdx @@ -3,21 +3,19 @@ title: Version section: Reference --- -## Version - ---- +# Version The Version endpoint provides NPM version information for each package. -### HTTP Request +## HTTP Request - `GET https://api.fontsource.org/v1/version/{id}` -### Response +## Response The API response for the Version endpoint is a JSON object that provides NPM version information for each package. -#### Attributes: +### Attributes Returns an object with: @@ -28,7 +26,7 @@ Returns an object with: | latestVariable | Optional<string> | Latest variable NPM version | | variable | Optional<string[]> | Variable NPM versions sorted newest to oldest | -#### Response example: +### Response example ```json { @@ -61,7 +59,7 @@ Returns an object with: } ``` -#### Example: +### Example - `GET https://api.fontsource.org/v1/version/abel` - `GET https://api.fontsource.org/v1/version/open-sans` diff --git a/website/docs/getting-started/cdn.mdx b/website/docs/getting-started/cdn.mdx index 1d4becfcb1..321ed27776 100644 --- a/website/docs/getting-started/cdn.mdx +++ b/website/docs/getting-started/cdn.mdx @@ -3,35 +3,33 @@ title: CDN section: Contents --- -## CDN - ---- +# CDN Fontsource has partnered with [jsDelivr](https://www.jsdelivr.com/) for a custom proxy for all of its font files, allowing for niche use cases where a stable font file link is required. All files are versioned according to [Semver](https://semver.org/), and using a specific version tag will give you longer lived caches. > **Note:** We recommend self-hosting your fonts if possible, but we understand there are suitable use cases for a CDN. -### Usage +## Usage To leverage the Fontsource CDN for your project, you can use the import generator provided on the install page of each font. For example, to use [Roboto Flex](/fonts/roboto-flex/cdn), you can access its import generator to generate the relevant URLs and CSS necessary for your projec ## URL Formats ---- - The Fontsource CDN provides two primary URL formats for accessing font files: -#### Static URLs +### Static URLs Static font URLs follow this pattern: + - `https://cdn.jsdelivr.net/fontsource/fonts/{id}@{version}/{subset}-{weight}-{style}.{extension}` -#### Variable Fonts URLs +### Variable Fonts URLs Variable fonts URLs have the format: + - `https://cdn.jsdelivr.net/fontsource/fonts/{id}:vf@{version}/{subset}-{axes}-{style}.woff2` -### Example URLs +## Example URLs Here are some example URLs that demonstrate how to use Fontsource's CDN with different fonts and configurations: diff --git a/website/docs/getting-started/display.mdx b/website/docs/getting-started/display.mdx index 23b2f294b5..1a8d6b3570 100644 --- a/website/docs/getting-started/display.mdx +++ b/website/docs/getting-started/display.mdx @@ -3,9 +3,7 @@ title: Font Display section: Contents --- -## Font Display - ---- +# Font Display Font display is a CSS property that controls how fonts appear on your website. By default, Fontsource uses the `swap` value for the `font-display` property. This means that while a custom font is loading, the browser displays a fallback font. Once the custom font is ready, the browser swaps it in place of the fallback font. @@ -13,9 +11,9 @@ Font display is a CSS property that controls how fonts appear on your website. B To customise the `font-display` property for a specific font, you can use the **Advanced** tab on each **[Install](https://fontsource.org/fonts/open-sans/install)** page to generate custom `@font-face` rules with your preferred value. -<br /> +## Example -For example, to set the `font-display` property to `optional` for Open Sans. You can create the following `@font-face` rule: +To set the `font-display` property to `optional` for Open Sans, you can create the following `@font-face` rule: ```css @font-face { diff --git a/website/docs/getting-started/faces-mixin.mdx b/website/docs/getting-started/faces-mixin.mdx index 526f0e622c..f36b9aaa41 100644 --- a/website/docs/getting-started/faces-mixin.mdx +++ b/website/docs/getting-started/faces-mixin.mdx @@ -3,13 +3,11 @@ title: Faces Mixin section: Sass --- -## Faces Mixin - ---- +# Faces Mixin The Faces mixin in Fontsource allows you to generate a highly customizable CSS file for your font by modifying various [`@font-face`](https://developer.mozilla.org/en-US/docs/Web/CSS/@font-face) variables. This guide explains how to use the Faces mixin in your Sass/SCSS projects. -### Installation +## Installation To use the Faces mixin, you need to import the mixin file from the specific font package. Here's an example for the Open Sans font: @@ -19,11 +17,8 @@ To use the Faces mixin, you need to import the mixin file from the specific font > **Note:** Make sure to adjust the import path and the name alias (as) according to the font package you are using. - ## Usage ---- - Once you have imported the mixin, you can use it to generate a CSS file with customized font variations. Here's an example that generates a CSS file similar to `open-sans/latin-500-italic.css`: ```scss @@ -55,15 +50,15 @@ You can customize the font variations by specifying different subsets, weights, The Faces mixin accepts several properties as arguments, allowing you to customize various aspects of the font. Here are the available arguments:: -| Variable | Description | Options | Default | -| ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------- | ---------------------------------------- | -| $family | Font family name (see [font-family](https://developer.mozilla.org/en-US/docs/Web/CSS/@font-face/font-family)) | Any string | Metadata default used (e.g. "Open Sans") | -| $display | How the font is displayed when loading (see [font-display](https://developer.mozilla.org/en-US/docs/Web/CSS/@font-face/font-display)) | One of: `auto`, `block`, `swap`, `fallback`, `optional` | `swap` | -| $formats | List of included font file formats (see [src](https://developer.mozilla.org/en-US/docs/Web/CSS/@font-face/src)) | `all`, or any of: `woff`, `woff2` | `all` | -| $subsets | List of included subsets | `all`, or any of the subsets listed for the font | Metadata default used (e.g. latin) | -| $weights | List of included weights (see [font-weight](https://developer.mozilla.org/en-US/docs/Web/CSS/@font-face/font-weight)) | `all`, or any of the weights listed for the font | Metadata default used (e.g. 400) | -| $styles | List of included styles (see [font-style](https://developer.mozilla.org/en-US/docs/Web/CSS/@font-face/font-style)) | `all`, or any of the styles listed for the font (usually `normal` and `italic`) | Metadata default used (e.g. normal) | -| $axes | List of included variable font axes (see [Variable fonts guide](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Fonts/Variable_Fonts_Guide)) | `all` (which uses `full`), or any of the axes listed for the font | `full` | +| Variable | Description | Options | Default | +| -------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------- | ---------------------------------------- | +| $family | Font family name (see [font-family](https://developer.mozilla.org/en-US/docs/Web/CSS/@font-face/font-family)) | Any string | Metadata default used (e.g. "Open Sans") | +| $display | How the font is displayed when loading (see [font-display](https://developer.mozilla.org/en-US/docs/Web/CSS/@font-face/font-display)) | One of: `auto`, `block`, `swap`, `fallback`, `optional` | `swap` | +| $formats | List of included font file formats (see [src](https://developer.mozilla.org/en-US/docs/Web/CSS/@font-face/src)) | `all`, or any of: `woff`, `woff2` | `all` | +| $subsets | List of included subsets | `all`, or any of the subsets listed for the font | Metadata default used (e.g. latin) | +| $weights | List of included weights (see [font-weight](https://developer.mozilla.org/en-US/docs/Web/CSS/@font-face/font-weight)) | `all`, or any of the weights listed for the font | Metadata default used (e.g. 400) | +| $styles | List of included styles (see [font-style](https://developer.mozilla.org/en-US/docs/Web/CSS/@font-face/font-style)) | `all`, or any of the styles listed for the font (usually `normal` and `italic`) | Metadata default used (e.g. normal) | +| $axes | List of included variable font axes (see [Variable fonts guide](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Fonts/Variable_Fonts_Guide)) | `all` (which uses `full`), or any of the axes listed for the font | `full` | The following advanced properties shouldn't need to be modified as often, but are still available for use: diff --git a/website/docs/getting-started/generator-mixin.mdx b/website/docs/getting-started/generator-mixin.mdx index 3eb5b3f8c9..e077a20c6b 100644 --- a/website/docs/getting-started/generator-mixin.mdx +++ b/website/docs/getting-started/generator-mixin.mdx @@ -3,16 +3,12 @@ title: Generator Mixin section: Sass --- -## Generator Mixin - ---- +# Generator Mixin The generator mixin in Fontsource is a powerful tool that allows for advanced use cases in Sass. It provides a way to dynamically generate CSS based on the specified properties. Please note that the generator mixin is more advanced and is recommended for users who require fine-grained control over their font styles. For most use cases, the [Faces mixin](./faces-mixin) is sufficient. ## Import ---- - To use the generator mixin, you need to import the Fontsource mixin module along with the `sass:map` module to extract generator properties. Here's an example of how to import the generator mixin for the Open Sans font: ```scss @@ -22,8 +18,6 @@ To use the generator mixin, you need to import the Fontsource mixin module along ## Usage ---- - The generator mixin allows you to generate CSS based on the provided properties. It uses a loop to iterate over the properties and generate CSS from the content block. Here's an example of using the generator mixin: ```scss @@ -49,13 +43,11 @@ In this example, the `OpenSans.generator` mixin is called with the desired prope The generator mixin accepts the same arguments as the faces mixin. You can refer to the [arguments section](./faces-mixin#arguments) of the faces mixin documentation for a complete list of available arguments. -## Properties - ---- +### Properties The generator mixin provides several properties that can be accessed within the content block. These properties are passed into the content block and can be used to generate dynamic CSS. Here are the properties available: -### Mixin Arguments +#### Mixin Arguments All the arguments passed into the generator mixin are resolved to their final values and passed into the content block. These values are constant throughout each content block iteration. You can refer to the [arguments section](./faces-mixin#arguments) of the faces mixin documentation for a complete list of available arguments. @@ -83,7 +75,7 @@ All the arguments passed into the generator mixin are resolved to their final va | styles | `(normal)` | | axes | `(wght, ital)` | -### Loop Parameters +#### Loop Parameters These variables change on each iteration of the content block: @@ -96,7 +88,7 @@ These variables change on each iteration of the content block: | axis | `wght` | | style | `italic` | -### CSS Properties +#### CSS Properties These are the CSS properties that are calculated and used by default in the faces mixin: @@ -112,8 +104,6 @@ These are the CSS properties that are calculated and used by default in the face ## Example ---- - Here's an example of how the faces mixin uses the generator mixin for its implementation: ```scss diff --git a/website/docs/getting-started/install.mdx b/website/docs/getting-started/install.mdx index f151c2119b..c8844d1a30 100644 --- a/website/docs/getting-started/install.mdx +++ b/website/docs/getting-started/install.mdx @@ -3,13 +3,11 @@ title: Install section: Contents --- -## Install - ---- +# Install Fontsource provides a straightforward process for installing fonts into your web application. This guide will walk you through the installation steps. -### Prerequisites +## Prerequisites Before proceeding with the installation, ensure that you are using a bundler, such as Vite or Webpack, to handle importing CSS into your final bundle. Please refer to the [Fontsource Guides](/docs/guides) section to see detailed instructions for your preferred framework. @@ -19,8 +17,6 @@ If your chosen font supports variable fonts, Fontsource **highly recommends** us ## Setup ---- - To install a font from Fontsource, follow the steps below: ### 1. Choose a Package diff --git a/website/docs/getting-started/introduction.mdx b/website/docs/getting-started/introduction.mdx index 5e917eeb60..0dc9e3d940 100644 --- a/website/docs/getting-started/introduction.mdx +++ b/website/docs/getting-started/introduction.mdx @@ -3,16 +3,12 @@ title: Introduction section: Contents --- -## Introduction - ---- +# Introduction Fontsource is a collection of open-source fonts that are packaged into individual NPM packages for self-hosting in your web applications. This documentation outlines the benefits of using Fontsource and how to get started. ## Advantages ---- - ### 1. Performance - Self-hosting fonts can **significantly improve website performance** by eliminating the extra latency caused by additional DNS resolution and TCP connection establishment that is required when using a CDN like Google Fonts. This can help to prevent doubled visual load times for simple websites, as benchmarked [here](https://github.com/HTTPArchive/almanac.httparchive.org/pull/607) and [here](https://github.com/reactiflux/reactiflux.com/pull/21). diff --git a/website/docs/getting-started/material-icons.mdx b/website/docs/getting-started/material-icons.mdx index 45254e907b..9d816dcd42 100644 --- a/website/docs/getting-started/material-icons.mdx +++ b/website/docs/getting-started/material-icons.mdx @@ -3,16 +3,12 @@ title: Material Icons section: Icons --- -## Material Icons - ---- +# Material Icons Fontsource provides support for all variations of Material Icons. You can find more details on how to use the font variation of the project [here](https://google.github.io/material-design-icons/#icon-font-for-the-web). ## Installation ---- - To install Material Icons from Fontsource, follow the steps below: ### 1. Install Icon Set diff --git a/website/docs/getting-started/material-symbols.mdx b/website/docs/getting-started/material-symbols.mdx index 023d7ab072..f3dfccc114 100644 --- a/website/docs/getting-started/material-symbols.mdx +++ b/website/docs/getting-started/material-symbols.mdx @@ -3,16 +3,12 @@ title: Material Symbols section: Icons --- -## Material Symbols - ---- +# Material Symbols Fontsource now supports Material Symbols, a new icon set with variable font support. Material Symbols offers various icons with customizable attributes such as FILL, wght, GRAD, and opsz. This allows you to create dynamic and visually appealing icons in your web applications. ## Installation ---- - To install Material Symbols from Fontsource, follow the steps below: ### 1. Install Icon Set @@ -53,20 +49,22 @@ To ensure proper rendering of the icons, include the following CSS class in your ```css .material-symbols-outlined { - font-family: "Material Symbols Outlined"; - font-weight: normal; - font-style: normal; - font-size: 24px; /* Preferred icon size */ - display: inline-block; - line-height: 1; - text-transform: none; - letter-spacing: normal; - word-wrap: normal; - white-space: nowrap; - direction: ltr; + font-family: "Material Symbols Outlined"; + font-weight: normal; + font-style: normal; + font-size: 24px; /* Preferred icon size */ + display: inline-block; + line-height: 1; + text-transform: none; + letter-spacing: normal; + word-wrap: normal; + white-space: nowrap; + direction: ltr; } ``` By applying the `.material-symbols-outlined` class to the relevant elements, you can utilize the Material Symbols Outlined font in your application. +<br /> + You can learn more about styling Material Symbols [here](https://developers.google.com/fonts/docs/material_symbols). diff --git a/website/docs/getting-started/migrate-v5.mdx b/website/docs/getting-started/migrate-v5.mdx index 8a8609ec72..39d01ccd6b 100644 --- a/website/docs/getting-started/migrate-v5.mdx +++ b/website/docs/getting-started/migrate-v5.mdx @@ -3,16 +3,12 @@ title: Migrating to V5 section: Migration --- -## Migration Guide V5 - ---- +# Migration Guide V5 Fontsource V5 introduces several breaking changes that may require modifications to your existing codebase. This guide will help you migrate from the previous version to the latest version of Fontsource. Please review the following breaking changes and apply the necessary updates. ## Breaking Changes ---- - ### Variable Font Package Names Variable fonts are now split into separate packages to provide more flexibility and granular control. @@ -36,7 +32,7 @@ import "@fontsource-variable/roboto-flex/full-italic.css"; ``` > **Note:** Please note that if you were previously using the `full` variant, it may no longer be available. We have introduced a new `standard` axis that is generated with a smaller subset of variable axes for improved performance and compatibility. -> #### +> <br /> > For more information about the new `standard` axis and its characteristics, you can refer to the [**Variable Fonts**](/docs/getting-started/variable#understanding-variable-axes) guide. Additionally, on each font's page in the search directory, you can explore the import generator to see the available variants specific to that font. ### Variable Font Family Names @@ -47,7 +43,7 @@ A mistake made the `font-family` names for variable fonts inconsistent with the ```css body { - font-family: "Roboto FlexVariable", sans-serif; + font-family: "Roboto FlexVariable", sans-serif; } ``` @@ -55,7 +51,7 @@ body { ```css body { - font-family: "Roboto Flex Variable", sans-serif; + font-family: "Roboto Flex Variable", sans-serif; } ``` @@ -121,4 +117,3 @@ A small change to the `metadata.json` file changes the `license` property from t ... } ``` - diff --git a/website/docs/getting-started/preload.mdx b/website/docs/getting-started/preload.mdx index 2692ce2372..042334bbbd 100644 --- a/website/docs/getting-started/preload.mdx +++ b/website/docs/getting-started/preload.mdx @@ -3,9 +3,7 @@ title: Preloading Fonts section: Contents --- -## Preloading Fonts - ---- +# Preloading Fonts Preloading fonts is a technique used to load fonts before they're required, which can improve your website's performance. However, it's essential to preload only critical fonts and subsets to avoid unnecessarily increasing initial load times. diff --git a/website/docs/getting-started/sass-import.mdx b/website/docs/getting-started/sass-import.mdx index e2a913cf7b..9f7294967f 100644 --- a/website/docs/getting-started/sass-import.mdx +++ b/website/docs/getting-started/sass-import.mdx @@ -1,15 +1,13 @@ --- -title: Import +title: Sass Import section: Sass --- -## Import - ---- +# Sass Import When using Fontsource in a Sass/SCSS project, you can import the font stylesheets using the @import rule. This guide explains how to import Fontsource in your Sass/SCSS files. -### Installation +## Installation For the most basic usage of Fontsource stylesheets, you can use the `@import` rule in your Sass/SCSS file. Here's an example of importing the Open Sans font: @@ -26,7 +24,7 @@ You can also import specific font variations if needed: @import "~@fontsource/open-sans/700-italic.css"; ``` -### Usage +## Usage Once you have imported the Fontsource stylesheets, the font styles will be available for use in your project. You can apply the imported font styles to elements using the font-family property in your CSS rules. Here's an example: diff --git a/website/docs/getting-started/subsets.mdx b/website/docs/getting-started/subsets.mdx index 621e85b332..6f1eff3498 100644 --- a/website/docs/getting-started/subsets.mdx +++ b/website/docs/getting-started/subsets.mdx @@ -3,9 +3,7 @@ title: Individual Subsets section: Contents --- -## Individual Subsets - ---- +# Individual Subsets In the rare case that you need to import a specific subset of a font, you can do so by importing the subset's CSS file. For example, if you only need the `latin` subset of the `Open Sans` font, you can import the `latin.css` file: diff --git a/website/docs/getting-started/variable.mdx b/website/docs/getting-started/variable.mdx index 4c712aa914..e9e6d4a5d7 100644 --- a/website/docs/getting-started/variable.mdx +++ b/website/docs/getting-started/variable.mdx @@ -3,19 +3,17 @@ title: Variable Fonts section: Contents --- -## Variable Fonts - ---- +# Variable Fonts Variable fonts allow designers and developers to use a single font file that contains multiple variations of the same font, such as different weights, widths, and styles. This can result in **smaller file sizes** and **more flexible design options**. Here's how you can use variable fonts with Fontsource: -### 1. Install Package +## 1. Install Package To use a variable font with Fontsource, you need to install the corresponding variable font package. For example, if you want to use the Roboto Flex variable font, you would install the `@fontsource-variable/roboto-flex` package: <PackageManagerCode cmd="@fontsource-variable/roboto-flex" /> -### 2. Import the Font +## 2. Import the Font After installing the package, you can import the font into your project like this: @@ -31,7 +29,7 @@ This will import the standard weight of the font. If you want to use a specific import "@fontsource-variable/roboto-flex/wght-italic.css"; ``` -### 3. CSS +## 3. CSS Once the font is imported, you can use it in your CSS stylesheets just like any other font. The difference with variable fonts is that you can specify the specific axis values you want to use. Here's an example: @@ -45,7 +43,7 @@ body { In this example, we are setting the font weight to `500` and the width axis to `75%` of the maximum width. Note that not all axes are supported by all variable fonts, so you will need to consult the font documentation to see which axes are available. -### 4. Fallbacks +## 4. Fallbacks Optionally, if you want to use variable fonts but also support browsers that do not support them, you can use the `@supports` rule to provide a fallback. You will also need to import `@fontsource/roboto-flex` or any other font as the fallback, however, it is also fine to rely on default system fonts for this. Here's an example: @@ -68,8 +66,6 @@ This will only apply the font styles if the browser supports variable fonts (`fo ## Understanding Variable Axes ---- - Variable axes in fonts refer to the ability to adjust various visual characteristics of a font along a continuous spectrum. This allows for greater flexibility and control in fine-tuning the appearance of typography. ### Standard Axes diff --git a/website/docs/guides/angular.mdx b/website/docs/guides/angular.mdx index 469a96b8e6..fa0c49c515 100644 --- a/website/docs/guides/angular.mdx +++ b/website/docs/guides/angular.mdx @@ -3,13 +3,11 @@ title: Angular section: Frameworks --- -## Angular - ---- +# Angular To integrate Fontsource into your Angular project, follow the steps below. -### 1. Entry File +## 1. Entry File Open `app.component.ts` and modify the `@Component` decorator accordingly. @@ -27,7 +25,7 @@ export class AppComponent { } ``` -### 2. CSS Imports +## 2. CSS Imports Open `app.component.css` and import the desired font weights. @@ -35,12 +33,12 @@ Open `app.component.css` and import the desired font weights. @import "~@fontsource-variable/open-sans/wght.css"; ``` -### 3. Usage +## 3. Usage You can now use the imported fonts in your Angular project. ```css h1 { - font-family: "Open Sans Variable", sans-serif; + font-family: "Open Sans Variable", sans-serif; } ``` diff --git a/website/docs/guides/nextjs.mdx b/website/docs/guides/nextjs.mdx index 6d9dc53a99..838605d1b0 100644 --- a/website/docs/guides/nextjs.mdx +++ b/website/docs/guides/nextjs.mdx @@ -5,23 +5,27 @@ section: Frameworks # Next.js ---- - To include Fontsource into your Next.js project, it is required to use a custom App component. [Next.js Documentation](https://nextjs.org/docs/advanced-features/custom-app). ## Installation ---- - To add Fontsource to your Next.js project, you can import it globally in the custom `_app.js` or `_app.tsx` file. Alternatively, you can choose to import it into a specific page component, but the CSS will only be present within that page and not globally. ```jsx import "@fontsource-variable/open-sans/wght.css"; function MyApp({ Component, pageProps }) { - return <Component {...pageProps} />; + return <Component {...pageProps} />; } export default MyApp; ``` + +### Comparison to `next/font` + +Next.js offers a built-in way to load fonts using the `next/font` package. This package serves as a straightforward alternative to Fontsource as a simple setup. It embeds the CSS from the Google Fonts API, eliminating an additional round-trip response. It performs well for most use cases and is a good choice if you do not need to customise the font loading behaviour. + +<br /> + +We recommend using Fontsource if you need more control over versioning your dependencies and do not want an invisible abstraction over the Google Fonts API. We also offer an escape hatch to directly modify the `@font-face` rules suitable for more advanced use cases. diff --git a/website/docs/guides/qwik.mdx b/website/docs/guides/qwik.mdx index 6037a07761..40049ddd16 100644 --- a/website/docs/guides/qwik.mdx +++ b/website/docs/guides/qwik.mdx @@ -3,15 +3,11 @@ title: Qwik section: Frameworks --- -## Qwik +# Qwik ---- - -To use Fontsource with a [Qwik City](https://qwik.builder.io) project, it is suggested to use the `/routes/layout.tsx` file. +To use Fontsource with a [Qwik City](https://qwik.builder.io) project, it is suggested to use the `/routes/layout.tsx` file. -### 1. Installation - ---- +## 1. Installation Once you [install](https://fontsource.org/docs/getting-started/install) the Fontsource package of your choice, you can import the chosen font variant into `routes/layout.tsx`: @@ -34,9 +30,7 @@ export default component$(() => { > **Note:** Alternatively, you can import the font in **index.tsx** or any other component file and it should have the same effect. -### 2. Usage - ---- +## 2. Usage You can now use the imported fonts in your Qwik City project. Here's an example of the Open Sans Variable font being applied to an `h1` selector. @@ -46,9 +40,9 @@ h1 { } ``` -#### Scoped Component Fonts +### Scoped Component Fonts -To use Qwik's scoped CSS functionality, you can use the font declaration in the `useStylesScoped$()` hook from Qwik. +To use Qwik's scoped CSS functionality, you can use the font declaration in the `useStylesScoped$()` hook from Qwik. ```tsx import { component$, useStylesScoped$ } from "@builder.io/qwik"; @@ -73,7 +67,6 @@ export default component$(() => { You can opt out of this scoped behavior by using Qwik's `:global()` selector. -### 3. Extensibility +## 3. Extensibility By default, Qwik works well with Fontsource out of the box. This even includes [lazy-loadable references](https://qwik.builder.io/docs/components/styles/#usestyles) to component styles with `useStyles$()`. - diff --git a/website/docs/guides/remix.mdx b/website/docs/guides/remix.mdx index df4f8c2981..572077ca90 100644 --- a/website/docs/guides/remix.mdx +++ b/website/docs/guides/remix.mdx @@ -3,11 +3,37 @@ title: Remix section: Frameworks --- -## Remix +# Remix ---- +Remix is a full-stack JavaScript framework for building web applications. Importing fonts depends on the compiler you are using. Below are the steps to import fonts into a Remix project. + +## Vite Compiler + +To import fonts into a Remix project using the Vite compiler, you can simply import the CSS file directly into your `root.tsx` file. + +### 1. Import CSS + +Modify `root.tsx` to include the following code: + +```tsx +import "@fontsource-variable/open-sans/wght.css"; +``` + +> **Note:** You **MUST** include the `.css` extension when importing the file or you will get an error. -Remix is a full-stack JavaScript framework for building web applications. To import fonts into a Remix project, you can leverage the CSS bundler plugin built into the framework. Follow the steps below to set it up. +### 2. Usage + +You can now use the imported fonts in your Remix.js project. + +```css +h1 { + font-family: "Open Sans Variable", sans-serif; +} +``` + +## Classic Remix Compiler + +With the Classic Remix Compiler, you can leverage the CSS bundler plugin built into the framework. ### 1. Install the plugin @@ -33,8 +59,6 @@ export const links: LinksFunction = () => { }; ``` -> **Note:** You **MUST** include the `.css` extension when importing the file or you will get an error. - ### 3. Usage You can now use the imported fonts in your Remix.js project. diff --git a/website/docs/guides/svelte.mdx b/website/docs/guides/svelte.mdx index 4cca308292..e33076eeac 100644 --- a/website/docs/guides/svelte.mdx +++ b/website/docs/guides/svelte.mdx @@ -3,13 +3,11 @@ title: SvelteKit section: Frameworks --- -## SvelteKit - ---- +# SvelteKit To include Fontsource into your Svelte / SvelteKit project and apply it to your application's typography, follow the steps below. -### 1. Entry File +## 1. Entry File To apply the imported font to the typography of your Svelte / SvelteKit application, you can import the library into `+layout.svelte` file. @@ -19,7 +17,7 @@ To apply the imported font to the typography of your Svelte / SvelteKit applicat </script> ``` -### 2. Usage +## 2. Usage To apply the imported font to the typography of your Svelte / SvelteKit application, you can modify the `body` selector within the `+layout.svelte` file. diff --git a/website/docs/guides/vue.mdx b/website/docs/guides/vue.mdx index 53d433ed2c..cb48043892 100644 --- a/website/docs/guides/vue.mdx +++ b/website/docs/guides/vue.mdx @@ -5,19 +5,14 @@ section: Frameworks # Vue.js ---- - -To include Fontsource into your Vue.js project, you can import the Fontsource files into your entry point. +To include Fontsource into your Vue.js project, you can import the Fontsource files into your entry point with the appropriate bundler setup. ## Installation ---- - ```js import { createApp } from "vue"; -import "@fontsource/open-sans/400.css"; -import "@fontsource/open-sans/700.css"; +import "@fontsource-variable/open-sans/wght.css"; import App from "./App.vue"; diff --git a/website/docs/guides/webpack.mdx b/website/docs/guides/webpack.mdx index e0c24fd6d7..69e98b617c 100644 --- a/website/docs/guides/webpack.mdx +++ b/website/docs/guides/webpack.mdx @@ -3,19 +3,17 @@ title: Webpack section: Bundlers --- -## Webpack - ---- +# Webpack To use Fontsource with Webpack, you'll need to configure your Webpack project to handle font files and include Fontsource in the bundle. Follow the steps below to set it up. -### Installation +## Installation -## 1. Install the loaders +### 1. Install the loaders <PackageManagerCode cmd="css-loader file-loader" /> -## 2. Configure the loaders +### 2. Configure the loaders Modify `webpack.config.js` to include the following configuration: @@ -36,7 +34,7 @@ module.exports = { }; ``` -## 3. Import the font +### 3. Import the font Import the font in your entry file or component: diff --git a/website/package.json b/website/package.json index 618f2ed116..20f3f07c8b 100644 --- a/website/package.json +++ b/website/package.json @@ -12,6 +12,8 @@ "ci:lint": "eslint ." }, "dependencies": { + "@docsearch/css": "^3.6.0", + "@docsearch/react": "^3.6.0", "@esbuild-plugins/node-resolve": "^0.2.2", "@fal-works/esbuild-plugin-global-externals": "^2.1.2", "@fontsource-utils/generate": "0.4.0",