From fa1ce230eacdba34b235c19d992aebcb80bf4f57 Mon Sep 17 00:00:00 2001 From: Joshua Chen Date: Sun, 17 Apr 2022 16:39:11 +0800 Subject: [PATCH] refactor: capitalize comments (#7188) * refactor: capitalize comments * revert... --- .../functionUtils/playgroundUtils.ts | 9 ++- admin/scripts/generateExamples.mjs | 24 ++++---- jest/snapshotPathNormalizer.ts | 7 +-- .../src/remark/toc/index.ts | 2 +- .../src/remark/transformImage/index.ts | 4 +- .../src/remark/transformLinks/index.ts | 6 +- packages/docusaurus-migrate/src/index.ts | 2 +- .../src/index.d.ts | 4 +- .../src/collectRedirects.ts | 4 +- .../src/__tests__/index.test.ts | 3 +- .../src/__tests__/options.test.ts | 2 +- .../src/index.ts | 2 +- .../src/options.ts | 2 +- .../src/__tests__/docs.test.ts | 1 - .../src/__tests__/index.test.ts | 4 +- .../src/__tests__/numberPrefix.test.ts | 6 +- .../src/__tests__/options.test.ts | 2 +- .../src/__tests__/props.test.ts | 2 +- .../client/__tests__/docsClientUtils.test.ts | 6 +- .../src/docs.ts | 10 ++-- .../src/frontMatter.ts | 6 +- .../src/plugin-content-docs.d.ts | 6 +- .../src/routes.ts | 4 +- .../src/sidebars/generator.ts | 4 +- .../src/sidebars/postProcessor.ts | 2 +- .../src/sidebars/types.ts | 3 +- .../src/translations.ts | 54 +----------------- .../src/types.ts | 2 +- .../src/theme/DebugContent/index.tsx | 4 +- .../src/theme/DebugJsonView/index.tsx | 2 +- .../src/index.ts | 3 +- .../src/theme/IdealImage/index.tsx | 2 +- packages/docusaurus-plugin-pwa/src/index.ts | 7 ++- .../docusaurus-plugin-pwa/src/plugin-pwa.d.ts | 2 + .../docusaurus-plugin-pwa/src/registerSw.js | 4 +- packages/docusaurus-plugin-pwa/src/sw.js | 5 +- .../src/__tests__/index.test.ts | 2 +- .../src/__tests__/translations.test.ts | 2 +- .../src/getSwizzleConfig.ts | 4 +- .../src/theme-classic.d.ts | 4 +- .../src/theme/DocSidebarItem/Category.tsx | 4 +- .../src/theme/DocSidebarItems/index.tsx | 7 +-- .../src/theme/DocVersionBanner/index.tsx | 4 +- .../src/theme/Heading/index.tsx | 22 ++------ .../src/theme/Layout/index.tsx | 2 +- .../src/theme/SiteMetadata/index.tsx | 16 +++--- .../src/validateThemeConfig.ts | 3 +- .../src/components/Collapsible/index.tsx | 4 +- .../src/components/Details/index.tsx | 3 +- .../src/contexts/announcementBar.tsx | 2 +- .../src/contexts/navbarMobileSidebar.tsx | 4 +- .../src/hooks/useTOCHighlight.ts | 6 +- .../src/utils/codeBlockUtils.ts | 11 ++-- .../src/utils/docsUtils.tsx | 9 +-- .../src/utils/tocUtils.ts | 6 +- .../useAlgoliaContextualFacetFilters.ts | 2 +- .../src/theme/SearchBar/index.tsx | 2 +- .../src/validateThemeConfig.ts | 2 +- .../src/index.ts | 13 +++-- packages/docusaurus-types/src/index.d.ts | 4 +- .../src/__tests__/i18nUtils.test.ts | 2 - .../src/__tests__/markdownUtils.test.ts | 6 +- packages/docusaurus-utils/src/gitUtils.ts | 2 +- packages/docusaurus-utils/src/i18nUtils.ts | 2 +- packages/docusaurus-utils/src/pathUtils.ts | 6 +- packages/docusaurus-utils/src/tags.ts | 2 +- packages/docusaurus-utils/src/urlUtils.ts | 1 - packages/docusaurus-utils/src/webpackUtils.ts | 3 +- packages/docusaurus/bin/beforeCli.mjs | 3 +- packages/docusaurus/src/client/.eslintrc.js | 5 +- .../src/client/BaseUrlIssueBanner/index.tsx | 3 +- .../docusaurus/src/client/LinksCollector.tsx | 3 +- .../docusaurus/src/client/exports/Link.tsx | 2 +- .../src/client/exports/useBaseUrl.ts | 14 +---- .../docusaurus/src/client/routeContext.tsx | 2 +- packages/docusaurus/src/commands/deploy.ts | 5 +- packages/docusaurus/src/commands/start.ts | 2 +- .../swizzle/__tests__/actions.test.ts | 2 +- .../src/commands/swizzle/actions.ts | 2 +- .../src/server/__tests__/brokenLinks.test.ts | 12 ++-- .../server/__tests__/configValidation.test.ts | 17 +++--- packages/docusaurus/src/server/brokenLinks.ts | 1 - packages/docusaurus/src/server/choosePort.ts | 56 ++++++------------- packages/docusaurus/src/server/index.ts | 4 +- .../docusaurus/src/server/plugins/index.ts | 2 +- .../docusaurus/src/server/plugins/init.ts | 5 +- .../src/server/translations/translations.ts | 6 +- .../src/webpack/__tests__/utils.test.ts | 2 +- packages/docusaurus/src/webpack/base.ts | 12 ++-- packages/docusaurus/src/webpack/client.ts | 2 +- packages/docusaurus/src/webpack/utils.ts | 6 +- packages/lqip-loader/src/lqip.ts | 4 +- project-words.txt | 1 + website/_dogfooding/docs-tests-sidebars.js | 2 +- website/_dogfooding/dogfooding.config.js | 6 +- .../_dogfooding/testSwizzleThemeClassic.mjs | 12 ++-- website/docusaurus.config.js | 20 ++++--- website/testCSSOrder.mjs | 2 +- website/waitForCrowdin.mjs | 2 +- 99 files changed, 241 insertions(+), 350 deletions(-) diff --git a/admin/new.docusaurus.io/functionUtils/playgroundUtils.ts b/admin/new.docusaurus.io/functionUtils/playgroundUtils.ts index 85bd7ef4bd81..c5fdbdf2d7c0 100644 --- a/admin/new.docusaurus.io/functionUtils/playgroundUtils.ts +++ b/admin/new.docusaurus.io/functionUtils/playgroundUtils.ts @@ -16,9 +16,12 @@ const PlaygroundConfigs = { codesandbox: 'https://codesandbox.io/s/github/facebook/docusaurus/tree/main/examples/classic', - // stackblitz: 'https://stackblitz.com/fork/docusaurus', // not updated - // stackblitz: 'https://stackblitz.com/github/facebook/docusaurus/tree/main/examples/classic', // slow to load - stackblitz: 'https://stackblitz.com/github/facebook/docusaurus/tree/starter', // dedicated branch: faster load + // Not updated + // stackblitz: 'https://stackblitz.com/fork/docusaurus', + // Slow to load + // stackblitz: 'https://stackblitz.com/github/facebook/docusaurus/tree/main/examples/classic', + // Dedicated branch: faster load + stackblitz: 'https://stackblitz.com/github/facebook/docusaurus/tree/starter', }; const PlaygroundDocumentationUrl = 'https://docusaurus.io/docs/playground'; diff --git a/admin/scripts/generateExamples.mjs b/admin/scripts/generateExamples.mjs index edf56f4b423f..0c29c39bba31 100644 --- a/admin/scripts/generateExamples.mjs +++ b/admin/scripts/generateExamples.mjs @@ -24,27 +24,26 @@ async function generateTemplateExample(template) { `generating ${template} template for codesandbox in the examples folder...`, ); - // run the docusaurus script to create the template in the examples folder + // Run the docusaurus script to create the template in the examples folder const command = template.endsWith('-typescript') ? template.replace('-typescript', ' -- --typescript') : template; shell.exec( - // /!\ we use the published init script on purpose, - // because using the local init script is too early and could generate - // upcoming/unavailable config options. Remember CodeSandbox templates - // will use the published version, not the repo version + // We use the published init script on purpose, because the local init is + // too new and could generate upcoming/unavailable config options. + // Remember CodeSandbox templates will use the published version, + // not the repo version. `npm init docusaurus@latest examples/${template} ${command}`, ); - // read the content of the package.json const templatePackageJson = await fs.readJSON( `examples/${template}/package.json`, ); - // attach the dev script which would be used in code sandbox by default + // Attach the dev script which would be used in code sandbox by default templatePackageJson.scripts.dev = 'docusaurus start'; - // these example projects are not meant to be published to npm + // These example projects are not meant to be published to npm templatePackageJson.private = true; // Make sure package.json name is not "examples-classic". The package.json @@ -58,13 +57,12 @@ async function generateTemplateExample(template) { ? 'Docusaurus example project' : `Docusaurus example project (${template} template)`; - // rewrite the package.json file with the new edit await fs.writeFile( `./examples/${template}/package.json`, `${JSON.stringify(templatePackageJson, null, 2)}\n`, ); - // create sandbox.config.json file at the root of template + // Create sandbox/stackblitz config file at the root of template const codeSandboxConfig = { infiniteLoopProtection: true, hardReloadOnChange: true, @@ -162,7 +160,7 @@ console.log(` # Generate examples start! `); -// delete the examples directories if they exists +// Delete the examples directories if they exist console.log(`------- ## Removing example folders... `); @@ -170,7 +168,7 @@ await fs.rm('./examples/classic', {recursive: true, force: true}); await fs.rm('./examples/classic-typescript', {recursive: true, force: true}); await fs.rm('./examples/facebook', {recursive: true, force: true}); -// get the list of all available templates +// Get the list of all available templates console.log(` ------- ## Generate example folders... @@ -187,7 +185,7 @@ console.log('Committing changes'); shell.exec('git add examples'); shell.exec("git commit -am 'update examples' --allow-empty"); -// update starters +// Update starters console.log(` ------- # Updating starter repos and branches ... diff --git a/jest/snapshotPathNormalizer.ts b/jest/snapshotPathNormalizer.ts index 084abc14a6cc..485c70b4b1b2 100644 --- a/jest/snapshotPathNormalizer.ts +++ b/jest/snapshotPathNormalizer.ts @@ -90,7 +90,7 @@ function normalizePaths(value: T): T { (val) => val.split(homeDirReal).join(''), (val) => val.split(homeDir).join(''), - // handle HOME_DIR nested inside TEMP_DIR + // Handle HOME_DIR nested inside TEMP_DIR (val) => val .split(`${path.sep + homeRelativeToTemp}`) @@ -98,7 +98,7 @@ function normalizePaths(value: T): T { (val) => val .split(`${path.sep + homeRelativeToTempReal}`) - .join(''), // untested + .join(''), (val) => val .split(`${path.sep + homeRealRelativeToTempReal}`) @@ -106,7 +106,7 @@ function normalizePaths(value: T): T { (val) => val .split(`${path.sep + homeRealRelativeToTemp}`) - .join(''), // untested + .join(''), // Replace the Docusaurus version with a stub (val) => val.split(version).join(''), @@ -134,7 +134,6 @@ function normalizePaths(value: T): T { } function shouldUpdate(value: unknown) { - // return true if value is different from normalized value return typeof value === 'string' && normalizePaths(value) !== value; } diff --git a/packages/docusaurus-mdx-loader/src/remark/toc/index.ts b/packages/docusaurus-mdx-loader/src/remark/toc/index.ts index e10dbe70a3f3..8f5626de5abb 100644 --- a/packages/docusaurus-mdx-loader/src/remark/toc/index.ts +++ b/packages/docusaurus-mdx-loader/src/remark/toc/index.ts @@ -79,7 +79,7 @@ export default function plugin(options: PluginOptions = {}): Transformer { visit(root, 'heading', (child: Heading, index, parent) => { const value = toString(child); - // depth:1 headings are titles and not included in the TOC + // depth: 1 headings are titles and not included in the TOC if (parent !== root || !value || child.depth < 2) { return; } diff --git a/packages/docusaurus-mdx-loader/src/remark/transformImage/index.ts b/packages/docusaurus-mdx-loader/src/remark/transformImage/index.ts index 8dc6bbca3e50..691c42703922 100644 --- a/packages/docusaurus-mdx-loader/src/remark/transformImage/index.ts +++ b/packages/docusaurus-mdx-loader/src/remark/transformImage/index.ts @@ -103,7 +103,7 @@ async function getImageAbsolutePath( await ensureImageFileExist(imageFilePath, filePath); return imageFilePath; } else if (path.isAbsolute(imagePath)) { - // absolute paths are expected to exist in the static folder + // Absolute paths are expected to exist in the static folder. const possiblePaths = staticDirs.map((dir) => path.join(dir, imagePath)); const imageFilePath = await findAsyncSequential( possiblePaths, @@ -120,7 +120,7 @@ async function getImageAbsolutePath( } return imageFilePath; } - // relative paths are resolved against the source file's folder + // Relative paths are resolved against the source file's folder. const imageFilePath = path.join( path.dirname(filePath), decodeURIComponent(imagePath), diff --git a/packages/docusaurus-mdx-loader/src/remark/transformLinks/index.ts b/packages/docusaurus-mdx-loader/src/remark/transformLinks/index.ts index b1e7d1467ed9..24a04805a89b 100644 --- a/packages/docusaurus-mdx-loader/src/remark/transformLinks/index.ts +++ b/packages/docusaurus-mdx-loader/src/remark/transformLinks/index.ts @@ -34,7 +34,9 @@ type Context = PluginOptions & { filePath: string; }; -// transform the link node to a jsx link with a require() call +/** + * Transforms the link node to a JSX `` element with a `require()` call. + */ function toAssetRequireNode(node: Link, assetPath: string, filePath: string) { const jsxNode = node as Literal & Partial; let relativeAssetPath = posixPath( @@ -106,7 +108,7 @@ async function getAssetAbsolutePath( async function processLinkNode(node: Link, context: Context) { if (!node.url) { - // try to improve error feedback + // Try to improve error feedback // see https://github.com/facebook/docusaurus/issues/3309#issuecomment-690371675 const title = node.title || (node.children[0] as Literal)?.value || '?'; const line = node?.position?.start?.line || '?'; diff --git a/packages/docusaurus-migrate/src/index.ts b/packages/docusaurus-migrate/src/index.ts index b4798285a60a..e1e0bcf4d665 100644 --- a/packages/docusaurus-migrate/src/index.ts +++ b/packages/docusaurus-migrate/src/index.ts @@ -207,7 +207,7 @@ export function createConfigFile({ >): VersionTwoConfig { const siteConfig = v1Config; const customConfigFields: {[key: string]: unknown} = {}; - // add fields that are unknown to v2 to customConfigFields + // Add fields that are unknown to v2 to customConfigFields Object.keys(siteConfig).forEach((key) => { const knownFields = [ 'title', diff --git a/packages/docusaurus-module-type-aliases/src/index.d.ts b/packages/docusaurus-module-type-aliases/src/index.d.ts index dc196b86f210..b4a243ee96fb 100644 --- a/packages/docusaurus-module-type-aliases/src/index.d.ts +++ b/packages/docusaurus-module-type-aliases/src/index.d.ts @@ -152,9 +152,7 @@ declare module '@docusaurus/Link' { readonly href?: string; readonly autoAddBaseUrl?: boolean; - /** - * escape hatch in case broken links check is annoying for a specific link - */ + /** Escape hatch in case broken links check doesn't make sense. */ readonly 'data-noBrokenLinkCheck'?: boolean; }; export default function Link(props: Props): JSX.Element; diff --git a/packages/docusaurus-plugin-client-redirects/src/collectRedirects.ts b/packages/docusaurus-plugin-client-redirects/src/collectRedirects.ts index 1ffb8e568eca..9fb14e85a239 100644 --- a/packages/docusaurus-plugin-client-redirects/src/collectRedirects.ts +++ b/packages/docusaurus-plugin-client-redirects/src/collectRedirects.ts @@ -96,8 +96,8 @@ function filterUnwantedRedirects( redirects: RedirectMetadata[], pluginContext: PluginContext, ): RedirectMetadata[] { - // we don't want to create twice the same redirect - // that would lead to writing twice the same html redirection file + // We don't want to create the same redirect twice, since that would lead to + // writing the same html redirection file twice. Object.entries(_.groupBy(redirects, (redirect) => redirect.from)).forEach( ([from, groupedFromRedirects]) => { if (groupedFromRedirects.length > 1) { diff --git a/packages/docusaurus-plugin-content-blog/src/__tests__/index.test.ts b/packages/docusaurus-plugin-content-blog/src/__tests__/index.test.ts index 79ec1bb2b010..7d47e0027ab6 100644 --- a/packages/docusaurus-plugin-content-blog/src/__tests__/index.test.ts +++ b/packages/docusaurus-plugin-content-blog/src/__tests__/index.test.ts @@ -158,7 +158,6 @@ describe('blog plugin', () => { readingTime: 0.015, source: path.posix.join( '@site', - // pluginPath, path.posix.join('i18n', 'en', 'docusaurus-plugin-content-blog'), '2018-12-14-Happy-First-Birthday-Slash.md', ), @@ -421,7 +420,7 @@ describe('blog plugin', () => { const blogPosts = await getBlogPosts(siteDir); const noDateSource = path.posix.join('@site', PluginPath, 'no date.md'); const noDateSourceFile = path.posix.join(siteDir, PluginPath, 'no date.md'); - // we know the file exist and we know we have git + // We know the file exists and we know we have git const result = getFileCommitDate(noDateSourceFile, {age: 'oldest'}); const noDateSourceTime = result.date; const formattedDate = Intl.DateTimeFormat('en', { diff --git a/packages/docusaurus-plugin-content-blog/src/__tests__/options.test.ts b/packages/docusaurus-plugin-content-blog/src/__tests__/options.test.ts index 2b375f7cee52..8c8cbf92172c 100644 --- a/packages/docusaurus-plugin-content-blog/src/__tests__/options.test.ts +++ b/packages/docusaurus-plugin-content-blog/src/__tests__/options.test.ts @@ -13,7 +13,7 @@ function testValidate(options: Options) { return validateOptions({validate: normalizePluginOptions, options}); } -// the type of remark/rehype plugins can be either function, object or array +// The type of remark/rehype plugins can be either function, object or array const markdownPluginsFunctionStub = () => {}; const markdownPluginsObjectStub = {}; diff --git a/packages/docusaurus-plugin-content-blog/src/index.ts b/packages/docusaurus-plugin-content-blog/src/index.ts index c5538be08235..1bcfb028261b 100644 --- a/packages/docusaurus-plugin-content-blog/src/index.ts +++ b/packages/docusaurus-plugin-content-blog/src/index.ts @@ -218,7 +218,7 @@ export default async function pluginContentBlog( routeBasePath, archiveBasePath, ]); - // creates a blog archive route + // Create a blog archive route const archiveProp = await createData( `${docuHash(archiveUrl)}.json`, JSON.stringify({blogPosts}, null, 2), diff --git a/packages/docusaurus-plugin-content-blog/src/options.ts b/packages/docusaurus-plugin-content-blog/src/options.ts index c4c344116324..baf927b8c671 100644 --- a/packages/docusaurus-plugin-content-blog/src/options.ts +++ b/packages/docusaurus-plugin-content-blog/src/options.ts @@ -111,7 +111,7 @@ const PluginOptionSchema = Joi.object({ .default(DEFAULT_OPTIONS.feedOptions.type), title: Joi.string().allow(''), description: Joi.string().allow(''), - // only add default value when user actually wants a feed (type is not null) + // Only add default value when user actually wants a feed (type is not null) copyright: Joi.when('type', { is: Joi.any().valid(null), then: Joi.string().optional(), diff --git a/packages/docusaurus-plugin-content-docs/src/__tests__/docs.test.ts b/packages/docusaurus-plugin-content-docs/src/__tests__/docs.test.ts index 5eee85412c4d..bceca516cbfc 100644 --- a/packages/docusaurus-plugin-content-docs/src/__tests__/docs.test.ts +++ b/packages/docusaurus-plugin-content-docs/src/__tests__/docs.test.ts @@ -849,7 +849,6 @@ describe('versioned site', () => { const {siteDir, context, options, version100} = await loadSite({ options: { editUrl: 'https://github.com/facebook/docusaurus/edit/main/website', - // editCurrentVersion: true, }, }); diff --git a/packages/docusaurus-plugin-content-docs/src/__tests__/index.test.ts b/packages/docusaurus-plugin-content-docs/src/__tests__/index.test.ts index 46d87d936ef9..0a0627c735a2 100644 --- a/packages/docusaurus-plugin-content-docs/src/__tests__/index.test.ts +++ b/packages/docusaurus-plugin-content-docs/src/__tests__/index.test.ts @@ -68,8 +68,8 @@ const createFakeActions = (contentDir: string) => { }, }; - // query by prefix, because files have a hash at the end - // so it's not convenient to query by full filename + // Query by prefix, because files have a hash at the end so it's not + // convenient to query by full filename const getCreatedDataByPrefix = (prefix: string) => { const entry = Object.entries(dataContainer).find(([key]) => key.startsWith(prefix), diff --git a/packages/docusaurus-plugin-content-docs/src/__tests__/numberPrefix.test.ts b/packages/docusaurus-plugin-content-docs/src/__tests__/numberPrefix.test.ts index e1b7afd4c8a5..cf8b7e0ca7bb 100644 --- a/packages/docusaurus-plugin-content-docs/src/__tests__/numberPrefix.test.ts +++ b/packages/docusaurus-plugin-content-docs/src/__tests__/numberPrefix.test.ts @@ -23,7 +23,7 @@ const IgnoredNumberPrefixPatterns = [ '00abc01-My Doc', 'My 001- Doc', 'My -001 Doc', - // ignore common date-like patterns: https://github.com/facebook/docusaurus/issues/4640 + // Ignore common date-like patterns: https://github.com/facebook/docusaurus/issues/4640 '2021-01-31 - Doc', '31-01-2021 - Doc', '2021_01_31 - Doc', @@ -36,7 +36,7 @@ const IgnoredNumberPrefixPatterns = [ '01-2021 - Doc', '01_2021 - Doc', '01.2021 - Doc', - // date patterns without suffix + // Date patterns without suffix '2021-01-31', '2021-01', '21-01-31', @@ -49,7 +49,7 @@ const IgnoredNumberPrefixPatterns = [ '01', '2021', '01', - // ignore common versioning patterns: https://github.com/facebook/docusaurus/issues/4653 + // Ignore common versioning patterns: https://github.com/facebook/docusaurus/issues/4653 '8.0', '8.0.0', '14.2.16', diff --git a/packages/docusaurus-plugin-content-docs/src/__tests__/options.test.ts b/packages/docusaurus-plugin-content-docs/src/__tests__/options.test.ts index eec906acb515..5d5e330c50c8 100644 --- a/packages/docusaurus-plugin-content-docs/src/__tests__/options.test.ts +++ b/packages/docusaurus-plugin-content-docs/src/__tests__/options.test.ts @@ -15,7 +15,7 @@ import { import {GlobExcludeDefault} from '@docusaurus/utils'; import type {Options} from '@docusaurus/plugin-content-docs'; -// the type of remark/rehype plugins is function +// The type of remark/rehype plugins can be function/object const markdownPluginsFunctionStub = () => {}; const markdownPluginsObjectStub = {}; diff --git a/packages/docusaurus-plugin-content-docs/src/__tests__/props.test.ts b/packages/docusaurus-plugin-content-docs/src/__tests__/props.test.ts index db2648c5e5d7..9db11b7cdddb 100644 --- a/packages/docusaurus-plugin-content-docs/src/__tests__/props.test.ts +++ b/packages/docusaurus-plugin-content-docs/src/__tests__/props.test.ts @@ -57,7 +57,7 @@ describe('toTagDocListProp', () => { count: 2, label: tag.label, permalink: tag.permalink, - items: [doc3, doc1], // docs sorted by title, ignore "id5" absence + items: [doc3, doc1], // Docs sorted by title, ignore "id5" absence }); }); }); diff --git a/packages/docusaurus-plugin-content-docs/src/client/__tests__/docsClientUtils.test.ts b/packages/docusaurus-plugin-content-docs/src/client/__tests__/docsClientUtils.test.ts index 5ca427b76621..e663dbd43349 100644 --- a/packages/docusaurus-plugin-content-docs/src/client/__tests__/docsClientUtils.test.ts +++ b/packages/docusaurus-plugin-content-docs/src/client/__tests__/docsClientUtils.test.ts @@ -226,7 +226,7 @@ describe('docsClientUtils', () => { ], }; - // shuffle, because order shouldn't matter + // Shuffle, because order shouldn't matter const versions: GlobalVersion[] = _.shuffle([ versionNext, version2, @@ -355,7 +355,7 @@ describe('docsClientUtils', () => { ], }; - // shuffle, because order shouldn't matter + // Shuffle, because order shouldn't matter const versions: GlobalVersion[] = _.shuffle([ versionNext, version2, @@ -395,7 +395,7 @@ describe('docsClientUtils', () => { latestVersionSuggestion: version2, }); expect(getDocVersionSuggestions(data, '/docs/version1/doc2')).toEqual({ - latestDocSuggestion: undefined, // because /docs/version1/doc2 does not exist + latestDocSuggestion: undefined, // Because /docs/version1/doc2 does not exist latestVersionSuggestion: version2, }); }); diff --git a/packages/docusaurus-plugin-content-docs/src/docs.ts b/packages/docusaurus-plugin-content-docs/src/docs.ts index d7eae5bd74d9..1c04edc05efe 100644 --- a/packages/docusaurus-plugin-content-docs/src/docs.ts +++ b/packages/docusaurus-plugin-content-docs/src/docs.ts @@ -156,15 +156,13 @@ function doProcessDocMetadata({ parse_number_prefixes: parseNumberPrefixes = true, } = frontMatter; - // ex: api/plugins/myDoc -> myDoc - // ex: myDoc -> myDoc + // E.g. api/plugins/myDoc -> myDoc; myDoc -> myDoc const sourceFileNameWithoutExtension = path.basename( source, path.extname(source), ); - // ex: api/plugins/myDoc -> api/plugins - // ex: myDoc -> . + // E.g. api/plugins/myDoc -> api/plugins; myDoc -> . const sourceDirName = path.dirname(source); const {filename: unprefixedFileName, numberPrefix} = parseNumberPrefixes @@ -347,7 +345,7 @@ export function addDocNavigation( } const docsWithNavigation = docsBase.map(addNavData); - // sort to ensure consistent output for tests + // Sort to ensure consistent output for tests docsWithNavigation.sort((a, b) => a.id.localeCompare(b.id)); return docsWithNavigation; } @@ -434,7 +432,7 @@ export function getDocIds(doc: DocMetadataBase): [string, string] { return [doc.unversionedId, doc.id]; } -// docs are indexed by both versioned and unversioned ids at the same time +// Docs are indexed by both versioned and unversioned ids at the same time // TODO legacy retro-compatibility due to old versioned sidebars using // versioned doc ids ("id" should be removed & "versionedId" should be renamed // to "id") diff --git a/packages/docusaurus-plugin-content-docs/src/frontMatter.ts b/packages/docusaurus-plugin-content-docs/src/frontMatter.ts index 5c7d3bc97dba..de944a6b1716 100644 --- a/packages/docusaurus-plugin-content-docs/src/frontMatter.ts +++ b/packages/docusaurus-plugin-content-docs/src/frontMatter.ts @@ -20,12 +20,14 @@ import type {DocFrontMatter} from '@docusaurus/plugin-content-docs'; // We use default values in code instead const DocFrontMatterSchema = Joi.object({ id: Joi.string(), - title: Joi.string().allow(''), // see https://github.com/facebook/docusaurus/issues/4591#issuecomment-822372398 + // See https://github.com/facebook/docusaurus/issues/4591#issuecomment-822372398 + title: Joi.string().allow(''), hide_title: Joi.boolean(), hide_table_of_contents: Joi.boolean(), keywords: Joi.array().items(Joi.string().required()), image: URISchema, - description: Joi.string().allow(''), // see https://github.com/facebook/docusaurus/issues/4591#issuecomment-822372398 + // See https://github.com/facebook/docusaurus/issues/4591#issuecomment-822372398 + description: Joi.string().allow(''), slug: Joi.string(), sidebar_label: Joi.string(), sidebar_position: Joi.number(), diff --git a/packages/docusaurus-plugin-content-docs/src/plugin-content-docs.d.ts b/packages/docusaurus-plugin-content-docs/src/plugin-content-docs.d.ts index 2d23b7d51a90..97e8c46b0ea7 100644 --- a/packages/docusaurus-plugin-content-docs/src/plugin-content-docs.d.ts +++ b/packages/docusaurus-plugin-content-docs/src/plugin-content-docs.d.ts @@ -19,7 +19,7 @@ declare module '@docusaurus/plugin-content-docs' { * Custom callback for parsing number prefixes from file/folder names. */ export type NumberPrefixParser = (filename: string) => { - /** file name without number prefix, without any other modification. */ + /** File name without number prefix, without any other modification. */ filename: string; /** The number prefix. Can be float, integer, negative, or anything. */ numberPrefix?: number; @@ -621,9 +621,9 @@ declare module '@docusaurus/plugin-content-docs/client' { breadcrumbs: boolean; }; export type DocVersionSuggestions = { - /** suggest the latest version */ + /** Suggest the latest version */ latestVersionSuggestion: GlobalVersion; - /** suggest the same doc, in latest version (if exist) */ + /** Suggest the same doc, in latest version (if one exists) */ latestDocSuggestion?: GlobalDoc; }; diff --git a/packages/docusaurus-plugin-content-docs/src/routes.ts b/packages/docusaurus-plugin-content-docs/src/routes.ts index 3ef6e60ba146..739003737f32 100644 --- a/packages/docusaurus-plugin-content-docs/src/routes.ts +++ b/packages/docusaurus-plugin-content-docs/src/routes.ts @@ -139,11 +139,9 @@ export async function createVersionRoutes({ actions.addRoute({ path: version.path, - // allow matching /docs/* as well + // Allow matching /docs/* since this is the wrapping route exact: false, - // main docs component (DocPage) component: docLayoutComponent, - // sub-routes for each doc routes: await createVersionSubRoutes(), modules: { versionMetadata: aliasedSource(versionMetadataPropPath), diff --git a/packages/docusaurus-plugin-content-docs/src/sidebars/generator.ts b/packages/docusaurus-plugin-content-docs/src/sidebars/generator.ts index 4642897f3df4..67320e7888d5 100644 --- a/packages/docusaurus-plugin-content-docs/src/sidebars/generator.ts +++ b/packages/docusaurus-plugin-content-docs/src/sidebars/generator.ts @@ -76,9 +76,9 @@ Available doc IDs: return ( // Doc at the root of the autogenerated sidebar dir doc.sourceDirName === autogenDir || - // autogen dir is . and doc is in subfolder + // Autogen dir is . and doc is in subfolder autogenDir === '.' || - // autogen dir is not . and doc is in subfolder + // Autogen dir is not . and doc is in subfolder // "api/myDoc" startsWith "api/" (note "api2/myDoc" is not included) doc.sourceDirName.startsWith(addTrailingSlash(autogenDir)) ); diff --git a/packages/docusaurus-plugin-content-docs/src/sidebars/postProcessor.ts b/packages/docusaurus-plugin-content-docs/src/sidebars/postProcessor.ts index 363c731696b9..ac662291d343 100644 --- a/packages/docusaurus-plugin-content-docs/src/sidebars/postProcessor.ts +++ b/packages/docusaurus-plugin-content-docs/src/sidebars/postProcessor.ts @@ -22,7 +22,7 @@ function normalizeCategoryLink( params: SidebarProcessorParams, ): SidebarItemCategoryLink | undefined { if (category.link?.type === 'generated-index') { - // default slug logic can be improved + // Default slug logic can be improved const getDefaultSlug = () => `/category/${params.categoryLabelSlugger.slug(category.label)}`; const slug = category.link.slug ?? getDefaultSlug(); diff --git a/packages/docusaurus-plugin-content-docs/src/sidebars/types.ts b/packages/docusaurus-plugin-content-docs/src/sidebars/types.ts index 17d94b8ca3b7..8284f09048ee 100644 --- a/packages/docusaurus-plugin-content-docs/src/sidebars/types.ts +++ b/packages/docusaurus-plugin-content-docs/src/sidebars/types.ts @@ -180,7 +180,6 @@ export type PropSidebarItemCategory = Expand< } >; -// we may want to use a union type in props instead of this generic link? export type PropSidebarItemLink = SidebarItemLink & { docId?: string; }; @@ -245,7 +244,7 @@ export type SidebarItemsGeneratorArgs = { /** The default category index matcher which you can override. */ isCategoryIndex: CategoryIndexMatcher; /** - * key is the path relative to the doc content directory, value is the + * Key is the path relative to the doc content directory, value is the * category metadata file's content. */ categoriesMetadata: {[filePath: string]: CategoryMetadataFile}; diff --git a/packages/docusaurus-plugin-content-docs/src/translations.ts b/packages/docusaurus-plugin-content-docs/src/translations.ts index 4289f3579adf..10b058defa57 100644 --- a/packages/docusaurus-plugin-content-docs/src/translations.ts +++ b/packages/docusaurus-plugin-content-docs/src/translations.ts @@ -53,50 +53,6 @@ function getNormalizedSidebarName({ return rest.join('/'); } -/* -// Do we need to translate doc metadata? -// It seems translating front matter labels is good enough -function getDocTranslations(doc: DocMetadata): TranslationFileContent { - return { - [`${doc.unversionedId}.title`]: { - message: doc.title, - description: `The title for doc with id=${doc.unversionedId}`, - }, - ...(doc.sidebar_label - ? { - [`${doc.unversionedId}.sidebar_label`]: { - message: doc.sidebar_label, - description: - `The sidebar label for doc with id=${doc.unversionedId}`, - }, - } - : undefined), - }; -} -function translateDoc( - doc: DocMetadata, - docsTranslations: TranslationFileContent, -): DocMetadata { - return { - ...doc, - title: docsTranslations[`${doc.unversionedId}.title`]?.message ?? doc.title, - sidebar_label: - docsTranslations[`${doc.unversionedId}.sidebar_label`]?.message ?? - doc.sidebar_label, - }; -} - -function getDocsTranslations(version: LoadedVersion): TranslationFileContent { - return mergeTranslations(version.docs.map(getDocTranslations)); -} -function translateDocs( - docs: DocMetadata[], - docsTranslations: TranslationFileContent, -): DocMetadata[] { - return docs.map((doc) => translateDoc(doc, docsTranslations)); -} - */ - function getSidebarTranslationFileContent( sidebar: Sidebar, sidebarName: string, @@ -252,17 +208,10 @@ function getVersionTranslationFiles(version: LoadedVersion): TranslationFile[] { const sidebarsTranslations: TranslationFileContent = getSidebarsTranslations(version); - // const docsTranslations: TranslationFileContent = - // getDocsTranslations(version); - return [ { path: getVersionFileName(version.versionName), - content: mergeTranslations([ - versionTranslations, - sidebarsTranslations, - // docsTranslations, - ]), + content: mergeTranslations([versionTranslations, sidebarsTranslations]), }, ]; } @@ -276,7 +225,6 @@ function translateVersion( ...version, label: versionTranslations['version.label']?.message ?? version.label, sidebars: translateSidebars(version, versionTranslations), - // docs: translateDocs(version.docs, versionTranslations), }; } diff --git a/packages/docusaurus-plugin-content-docs/src/types.ts b/packages/docusaurus-plugin-content-docs/src/types.ts index 49156b2514ac..713b8a9a35c7 100644 --- a/packages/docusaurus-plugin-content-docs/src/types.ts +++ b/packages/docusaurus-plugin-content-docs/src/types.ts @@ -30,7 +30,7 @@ export type SourceToPermalink = { }; export type VersionTag = Tag & { - /** all doc ids having this tag. */ + /** All doc ids having this tag. */ docIds: string[]; }; export type VersionTags = { diff --git a/packages/docusaurus-plugin-debug/src/theme/DebugContent/index.tsx b/packages/docusaurus-plugin-debug/src/theme/DebugContent/index.tsx index ceac7dea5d19..185c453d7cba 100644 --- a/packages/docusaurus-plugin-debug/src/theme/DebugContent/index.tsx +++ b/packages/docusaurus-plugin-debug/src/theme/DebugContent/index.tsx @@ -38,7 +38,7 @@ function PluginContent({

{pluginName}

{Object.entries(pluginContent) - // filter plugin instances with no content + // Filter plugin instances with no content .filter(([, pluginInstanceContent]) => !!pluginInstanceContent) .map(([pluginId, pluginInstanceContent]) => ( Plugin content
{Object.entries(allContent) - // filter plugins with no content + // Filter plugins with no content .filter(([, pluginContent]) => Object.values(pluginContent).some( (instanceContent) => !!instanceContent, diff --git a/packages/docusaurus-plugin-debug/src/theme/DebugJsonView/index.tsx b/packages/docusaurus-plugin-debug/src/theme/DebugJsonView/index.tsx index 783928cb7afc..5724365b5f2b 100644 --- a/packages/docusaurus-plugin-debug/src/theme/DebugJsonView/index.tsx +++ b/packages/docusaurus-plugin-debug/src/theme/DebugJsonView/index.tsx @@ -10,7 +10,7 @@ import BrowserOnly from '@docusaurus/BrowserOnly'; import type {Props} from '@theme/DebugJsonView'; import type {ReactJsonViewProps} from 'react-json-view'; -// avoids "react-json-view" to display "root" +// Avoids "react-json-view" to display "root" const RootName = null; // Seems ReactJson does not work with SSR diff --git a/packages/docusaurus-plugin-ideal-image/src/index.ts b/packages/docusaurus-plugin-ideal-image/src/index.ts index 4ea9fa4675c7..727eb1adc51c 100644 --- a/packages/docusaurus-plugin-ideal-image/src/index.ts +++ b/packages/docusaurus-plugin-ideal-image/src/index.ts @@ -59,7 +59,8 @@ export default function pluginIdealImage( { loader: require.resolve('@docusaurus/responsive-loader'), options: { - emitFile: !isServer, // don't emit for server-side rendering + // Don't emit for server-side rendering + emitFile: !isServer, // eslint-disable-next-line global-require adapter: require('@docusaurus/responsive-loader/sharp'), name: 'assets/ideal-img/[name].[hash:hex:7].[width].[ext]', diff --git a/packages/docusaurus-plugin-ideal-image/src/theme/IdealImage/index.tsx b/packages/docusaurus-plugin-ideal-image/src/theme/IdealImage/index.tsx index 6bc259b2b1ba..ff8ea85f6f2b 100644 --- a/packages/docusaurus-plugin-ideal-image/src/theme/IdealImage/index.tsx +++ b/packages/docusaurus-plugin-ideal-image/src/theme/IdealImage/index.tsx @@ -40,7 +40,7 @@ function getMessage(icon: IconKey, state: State) { description: 'When the full-scale image is loading', }); case 'load': { - // we can show `alt` here + // We can show `alt` here const {pickedSrc} = state; const {size} = pickedSrc; const sizeMessage = size ? ` (${bytesToSize(size)})` : ''; diff --git a/packages/docusaurus-plugin-pwa/src/index.ts b/packages/docusaurus-plugin-pwa/src/index.ts index 044f05c5492d..7150eae5f609 100644 --- a/packages/docusaurus-plugin-pwa/src/index.ts +++ b/packages/docusaurus-plugin-pwa/src/index.ts @@ -150,7 +150,7 @@ export default function pluginPWA( optimization: { splitChunks: false, minimize: !debug, - // see https://developers.google.com/web/tools/workbox/guides/using-bundlers#webpack + // See https://developers.google.com/web/tools/workbox/guides/using-bundlers#webpack minimizer: debug ? [] : [ @@ -161,7 +161,8 @@ export default function pluginPWA( }, plugins: [ new webpack.EnvironmentPlugin({ - PWA_SW_CUSTOM: swCustom || '', // fallback value required with Webpack 5 + // Fallback value required with Webpack 5 + PWA_SW_CUSTOM: swCustom || '', }), new LogPlugin({ name: 'Service Worker', @@ -192,7 +193,7 @@ export default function pluginPWA( // @ts-expect-error: internal API? ...(injectManifest.globPatterns ?? []), ], - // those attributes are not overrideable + // Those attributes are not overrideable swDest, swSrc: swDest, globDirectory: props.outDir, diff --git a/packages/docusaurus-plugin-pwa/src/plugin-pwa.d.ts b/packages/docusaurus-plugin-pwa/src/plugin-pwa.d.ts index 1e0128331039..51cdf63f2c7a 100644 --- a/packages/docusaurus-plugin-pwa/src/plugin-pwa.d.ts +++ b/packages/docusaurus-plugin-pwa/src/plugin-pwa.d.ts @@ -81,6 +81,8 @@ declare module '@docusaurus/plugin-pwa' { */ swRegister: string | false; }; + + export type Options = Partial; } declare module '@theme/PwaReloadPopup' { diff --git a/packages/docusaurus-plugin-pwa/src/registerSw.js b/packages/docusaurus-plugin-pwa/src/registerSw.js index 36fc55c5a857..9226d9a6f054 100644 --- a/packages/docusaurus-plugin-pwa/src/registerSw.js +++ b/packages/docusaurus-plugin-pwa/src/registerSw.js @@ -16,7 +16,7 @@ const PWA_OFFLINE_MODE_ACTIVATION_STRATEGIES = const PWA_DEBUG = process.env.PWA_DEBUG; /* eslint-enable prefer-destructuring */ -const debug = PWA_DEBUG; // shortcut +const debug = PWA_DEBUG; // Shortcut const MAX_MOBILE_WIDTH = 940; @@ -101,7 +101,7 @@ async function getActiveStrategies() { return isActive ? strategyName : undefined; }), ); - return activeStrategies.filter(Boolean); // remove undefined values + return activeStrategies.filter(Boolean); } async function isOfflineModeEnabled() { diff --git a/packages/docusaurus-plugin-pwa/src/sw.js b/packages/docusaurus-plugin-pwa/src/sw.js index 6c30f239616f..de5d83e6317d 100644 --- a/packages/docusaurus-plugin-pwa/src/sw.js +++ b/packages/docusaurus-plugin-pwa/src/sw.js @@ -18,7 +18,7 @@ function parseSwParams() { return params; } -// doc advises against dynamic imports in SW +// Doc advises against dynamic imports in SW // https://developers.google.com/web/tools/workbox/guides/using-bundlers#code_splitting_and_dynamic_imports // https://twitter.com/sebastienlorber/status/1280155204575518720 // but looks it's working fine as it's inlined by webpack, need to double check @@ -73,7 +73,8 @@ function getPossibleURLs(url) { // eslint-disable-next-line no-underscore-dangle const precacheManifest = self.__WB_MANIFEST; const controller = new PrecacheController({ - fallbackToNetwork: true, // safer to turn this true? + // Safer to turn this true? + fallbackToNetwork: true, }); if (params.offlineMode) { diff --git a/packages/docusaurus-remark-plugin-npm2yarn/src/__tests__/index.test.ts b/packages/docusaurus-remark-plugin-npm2yarn/src/__tests__/index.test.ts index 4887b0ac9d23..6b6ff1ada900 100644 --- a/packages/docusaurus-remark-plugin-npm2yarn/src/__tests__/index.test.ts +++ b/packages/docusaurus-remark-plugin-npm2yarn/src/__tests__/index.test.ts @@ -6,7 +6,7 @@ */ import remark from 'remark'; -// import from the transpiled lib because Babel can't transpile `export =` +// Import from the transpiled lib because Babel can't transpile `export =` // TODO change to `../index` after migrating to ESM import npm2yarn from '../../lib/index'; import vfile from 'to-vfile'; diff --git a/packages/docusaurus-theme-classic/src/__tests__/translations.test.ts b/packages/docusaurus-theme-classic/src/__tests__/translations.test.ts index 66d738519e1e..ebb3040de540 100644 --- a/packages/docusaurus-theme-classic/src/__tests__/translations.test.ts +++ b/packages/docusaurus-theme-classic/src/__tests__/translations.test.ts @@ -125,7 +125,7 @@ describe('getTranslationFiles and translateThemeConfig isomorphism', () => { verifyIsomorphism(ThemeConfigSampleSimpleFooter); }); - // undefined footer should not make the translation code crash + // Undefined footer should not make the translation code crash // See https://github.com/facebook/docusaurus/issues/3936 it('is verified for sample without footer', () => { verifyIsomorphism({...ThemeConfigSample, footer: undefined}); diff --git a/packages/docusaurus-theme-classic/src/getSwizzleConfig.ts b/packages/docusaurus-theme-classic/src/getSwizzleConfig.ts index 13b9fde846f9..9e73ef9a17e4 100644 --- a/packages/docusaurus-theme-classic/src/getSwizzleConfig.ts +++ b/packages/docusaurus-theme-classic/src/getSwizzleConfig.ts @@ -30,7 +30,7 @@ export default function getSwizzleConfig(): SwizzleConfig { }, DocSidebar: { actions: { - eject: 'unsafe', // too much technical code in sidebar, not very safe atm + eject: 'unsafe', // Too much technical code in sidebar, not very safe atm wrap: 'safe', }, description: 'The sidebar component on docs pages', @@ -234,7 +234,7 @@ export default function getSwizzleConfig(): SwizzleConfig { 'prism-include-languages': { actions: { eject: 'safe', - wrap: 'forbidden', // not a component! + wrap: 'forbidden', // Not a component! }, description: 'The Prism languages to include for code block syntax highlighting. Meant to be ejected.', diff --git a/packages/docusaurus-theme-classic/src/theme-classic.d.ts b/packages/docusaurus-theme-classic/src/theme-classic.d.ts index d9462dfee076..4e9f0d995551 100644 --- a/packages/docusaurus-theme-classic/src/theme-classic.d.ts +++ b/packages/docusaurus-theme-classic/src/theme-classic.d.ts @@ -1022,8 +1022,8 @@ declare module '@theme/TOCItems' { declare module '@theme/TOC' { import type {TOCItem} from '@docusaurus/types'; - // minHeadingLevel only exists as a per-doc option, and won't have a default - // set by Joi. See TOC, TOCInline, TOCCollapsible for examples + // `minHeadingLevel` only comes from doc/post front matter, and won't have a + // default set by Joi. See TOC, TOCInline, TOCCollapsible for examples. export interface Props { readonly toc: readonly TOCItem[]; readonly minHeadingLevel?: number; diff --git a/packages/docusaurus-theme-classic/src/theme/DocSidebarItem/Category.tsx b/packages/docusaurus-theme-classic/src/theme/DocSidebarItem/Category.tsx index 202a9dae09c3..c3d5ed9fc41c 100644 --- a/packages/docusaurus-theme-classic/src/theme/DocSidebarItem/Category.tsx +++ b/packages/docusaurus-theme-classic/src/theme/DocSidebarItem/Category.tsx @@ -111,8 +111,8 @@ export default function DocSidebarItemCategory({ const isCurrentPage = isSamePath(href, activePath); const {collapsed, setCollapsed} = useCollapsible({ - // active categories are always initialized as expanded - // the default (item.collapsed) is only used for non-active categories + // Active categories are always initialized as expanded. The default + // (`item.collapsed`) is only used for non-active categories. initialState: () => { if (!collapsible) { return false; diff --git a/packages/docusaurus-theme-classic/src/theme/DocSidebarItems/index.tsx b/packages/docusaurus-theme-classic/src/theme/DocSidebarItems/index.tsx index 9d611912642c..fbced08e1416 100644 --- a/packages/docusaurus-theme-classic/src/theme/DocSidebarItems/index.tsx +++ b/packages/docusaurus-theme-classic/src/theme/DocSidebarItems/index.tsx @@ -17,12 +17,7 @@ function DocSidebarItems({items, ...props}: Props): JSX.Element { return ( {items.map((item, index) => ( - + ))} ); diff --git a/packages/docusaurus-theme-classic/src/theme/DocVersionBanner/index.tsx b/packages/docusaurus-theme-classic/src/theme/DocVersionBanner/index.tsx index daadce8000be..dd87a4d3673b 100644 --- a/packages/docusaurus-theme-classic/src/theme/DocVersionBanner/index.tsx +++ b/packages/docusaurus-theme-classic/src/theme/DocVersionBanner/index.tsx @@ -136,8 +136,8 @@ function DocVersionBannerEnabled({ const {latestDocSuggestion, latestVersionSuggestion} = useDocVersionSuggestions(pluginId); - // try to link to same doc in latest version (not always possible) - // fallback to main doc of latest version + // Try to link to same doc in latest version (not always possible), falling + // back to main doc of latest version const latestVersionSuggestedDoc = latestDocSuggestion ?? getVersionMainDoc(latestVersionSuggestion); diff --git a/packages/docusaurus-theme-classic/src/theme/Heading/index.tsx b/packages/docusaurus-theme-classic/src/theme/Heading/index.tsx index 51e1ee7d9377..7f8f80876475 100644 --- a/packages/docusaurus-theme-classic/src/theme/Heading/index.tsx +++ b/packages/docusaurus-theme-classic/src/theme/Heading/index.tsx @@ -13,13 +13,13 @@ import {useThemeConfig} from '@docusaurus/theme-common'; import styles from './styles.module.css'; -function AnchorHeading({as: As, id, ...props}: Props) { +export default function Heading({as: As, id, ...props}: Props): JSX.Element { const { navbar: {hideOnScroll}, } = useThemeConfig(); - - if (!id) { - return ; + // H1 headings do not need an id because they don't appear in the TOC. + if (As === 'h1' || !id) { + return ; } return ( @@ -46,17 +46,3 @@ function AnchorHeading({as: As, id, ...props}: Props) { ); } - -export default function Heading({as, ...props}: Props): JSX.Element { - if (as === 'h1') { - return ( -

- {props.children} -

- ); - } - return ; -} diff --git a/packages/docusaurus-theme-classic/src/theme/Layout/index.tsx b/packages/docusaurus-theme-classic/src/theme/Layout/index.tsx index 35592ef869f7..47ed451b55d9 100644 --- a/packages/docusaurus-theme-classic/src/theme/Layout/index.tsx +++ b/packages/docusaurus-theme-classic/src/theme/Layout/index.tsx @@ -27,7 +27,7 @@ export default function Layout(props: Props): JSX.Element { children, noFooter, wrapperClassName, - // not really layout-related, but kept for convenience/retro-compatibility + // Not really layout-related, but kept for convenience/retro-compatibility title, description, } = props; diff --git a/packages/docusaurus-theme-classic/src/theme/SiteMetadata/index.tsx b/packages/docusaurus-theme-classic/src/theme/SiteMetadata/index.tsx index e21668aa90f2..ce53ddf1d9e5 100644 --- a/packages/docusaurus-theme-classic/src/theme/SiteMetadata/index.tsx +++ b/packages/docusaurus-theme-classic/src/theme/SiteMetadata/index.tsx @@ -109,16 +109,16 @@ export default function SiteMetadata(): JSX.Element { - element here, - // as it allows react-helmet to override values set in previous - // ie we can override default metadata such as "twitter:card" - // In same Head, the same meta would appear twice instead of overriding - // See react-helmet doc - > + {/* + It's important to have an additional element here, as it allows + react-helmet to override default metadata values set in previous + like "twitter:card". In same Head, the same meta would appear twice + instead of overriding. + */} + {/* Yes, "metadatum" is the grammatically correct term */} {metadata.map((metadatum, i) => ( - + ))} diff --git a/packages/docusaurus-theme-classic/src/validateThemeConfig.ts b/packages/docusaurus-theme-classic/src/validateThemeConfig.ts index 6708539c2730..9a5cd826cc43 100644 --- a/packages/docusaurus-theme-classic/src/validateThemeConfig.ts +++ b/packages/docusaurus-theme-classic/src/validateThemeConfig.ts @@ -100,7 +100,7 @@ const HtmlNavbarItemSchema = Joi.object({ }); const itemWithType = (type: string | undefined) => { - // because equal(undefined) is not supported :/ + // Because equal(undefined) is not supported :/ const typeSchema = type ? Joi.string().required().equal(type) : Joi.string().forbidden(); @@ -241,7 +241,6 @@ const ColorModeSchema = Joi.object({ }), }).default(DEFAULT_COLOR_MODE_CONFIG); -// schema can probably be improved const HtmlMetadataSchema = Joi.object({ id: Joi.string(), name: Joi.string(), diff --git a/packages/docusaurus-theme-common/src/components/Collapsible/index.tsx b/packages/docusaurus-theme-common/src/components/Collapsible/index.tsx index 9185ac91c16f..48ff620fbab7 100644 --- a/packages/docusaurus-theme-common/src/components/Collapsible/index.tsx +++ b/packages/docusaurus-theme-common/src/components/Collapsible/index.tsx @@ -224,6 +224,8 @@ function CollapsibleBase({ function CollapsibleLazy({collapsed, ...props}: CollapsibleBaseProps) { const [mounted, setMounted] = useState(!collapsed); + // Updated in effect so that first expansion transition can work + const [lazyCollapsed, setLazyCollapsed] = useState(collapsed); useLayoutEffect(() => { if (!collapsed) { @@ -231,8 +233,6 @@ function CollapsibleLazy({collapsed, ...props}: CollapsibleBaseProps) { } }, [collapsed]); - // lazyCollapsed updated in effect so that first expansion transition can work - const [lazyCollapsed, setLazyCollapsed] = useState(collapsed); useLayoutEffect(() => { if (mounted) { setLazyCollapsed(collapsed); diff --git a/packages/docusaurus-theme-common/src/components/Details/index.tsx b/packages/docusaurus-theme-common/src/components/Details/index.tsx index ccf7e10b7fb4..1f330edec9a7 100644 --- a/packages/docusaurus-theme-common/src/components/Details/index.tsx +++ b/packages/docusaurus-theme-common/src/components/Details/index.tsx @@ -87,7 +87,8 @@ export function Details({ setOpen(true); } else { setCollapsed(true); - // setOpen(false); // Don't do this, it breaks close animation! + // Don't do this, it breaks close animation! + // setOpen(false); } }}> {summary} diff --git a/packages/docusaurus-theme-common/src/contexts/announcementBar.tsx b/packages/docusaurus-theme-common/src/contexts/announcementBar.tsx index f244be2bee2e..1adf70b3f279 100644 --- a/packages/docusaurus-theme-common/src/contexts/announcementBar.tsx +++ b/packages/docusaurus-theme-common/src/contexts/announcementBar.tsx @@ -72,7 +72,7 @@ function useContextValue(): ContextValue { let viewedId = IdStorage.get(); - // retrocompatibility due to spelling mistake of default id + // Retrocompatibility due to spelling mistake of default id // see https://github.com/facebook/docusaurus/issues/3338 // cSpell:ignore annoucement if (viewedId === 'annoucement-bar') { diff --git a/packages/docusaurus-theme-common/src/contexts/navbarMobileSidebar.tsx b/packages/docusaurus-theme-common/src/contexts/navbarMobileSidebar.tsx index c798605edb6c..d6e717564986 100644 --- a/packages/docusaurus-theme-common/src/contexts/navbarMobileSidebar.tsx +++ b/packages/docusaurus-theme-common/src/contexts/navbarMobileSidebar.tsx @@ -58,9 +58,9 @@ function useContextValue(): ContextValue { useHistoryPopHandler(() => { if (shown) { setShown(false); - // Should we prevent the navigation here? + // Prevent pop navigation; seems desirable enough // See https://github.com/facebook/docusaurus/pull/5462#issuecomment-911699846 - return false; // prevent pop navigation + return false; } return undefined; }); diff --git a/packages/docusaurus-theme-common/src/hooks/useTOCHighlight.ts b/packages/docusaurus-theme-common/src/hooks/useTOCHighlight.ts index afd6a12b173f..fca0174fe644 100644 --- a/packages/docusaurus-theme-common/src/hooks/useTOCHighlight.ts +++ b/packages/docusaurus-theme-common/src/hooks/useTOCHighlight.ts @@ -81,8 +81,8 @@ function getActiveAnchor( // https://github.com/facebook/docusaurus/issues/5318 return anchors[anchors.indexOf(nextVisibleAnchor) - 1] ?? null; } - // no anchor under viewport top? (ie we are at the bottom of the page) - // => highlight the last anchor found + // No anchor under viewport top (i.e. we are at the bottom of the page), + // highlight the last anchor found return anchors[anchors.length - 1] ?? null; } @@ -140,7 +140,7 @@ export function useTOCHighlight(config: TOCHighlightConfig | undefined): void { useEffect(() => { if (!config) { - // no-op, highlighting is disabled + // No-op, highlighting is disabled return () => {}; } diff --git a/packages/docusaurus-theme-common/src/utils/codeBlockUtils.ts b/packages/docusaurus-theme-common/src/utils/codeBlockUtils.ts index 8dd5108d93f1..f542f1386555 100644 --- a/packages/docusaurus-theme-common/src/utils/codeBlockUtils.ts +++ b/packages/docusaurus-theme-common/src/utils/codeBlockUtils.ts @@ -30,14 +30,14 @@ const magicCommentDirectives = [ ]; function getCommentPattern(languages: CommentType[]) { - // to be more reliable, the opening and closing comment must match + // To be more reliable, the opening and closing comment must match const commentPattern = languages .map((lang) => { const {start, end} = commentPatterns[lang]; return `(?:${start}\\s*(${magicCommentDirectives.join('|')})\\s*${end})`; }) .join('|'); - // white space is allowed, but otherwise it should be on it's own line + // White space is allowed, but otherwise it should be on it's own line return new RegExp(`^\\s*(?:${commentPattern})\\s*$`); } @@ -70,7 +70,7 @@ function getAllMagicCommentDirectiveStyles(lang: string) { return getCommentPattern(['html', 'jsx', 'bash']); default: - // all comment types + // All comment types return getCommentPattern(Object.keys(commentPatterns) as CommentType[]); } } @@ -139,16 +139,15 @@ export function parseLines( return {highlightLines: [], code}; } const directiveRegex = getAllMagicCommentDirectiveStyles(language); - // go through line by line + // Go through line by line const lines = code.split('\n'); let highlightBlockStart: number; let highlightRange = ''; - // loop through lines for (let lineNumber = 0; lineNumber < lines.length; ) { const line = lines[lineNumber]!; const match = line.match(directiveRegex); if (!match) { - // lines without directives are unchanged + // Lines without directives are unchanged lineNumber += 1; continue; } diff --git a/packages/docusaurus-theme-common/src/utils/docsUtils.tsx b/packages/docusaurus-theme-common/src/utils/docsUtils.tsx index c3d169c3e836..8ee82d5eb2e4 100644 --- a/packages/docusaurus-theme-common/src/utils/docsUtils.tsx +++ b/packages/docusaurus-theme-common/src/utils/docsUtils.tsx @@ -92,13 +92,8 @@ export function findFirstCategoryLink( if (categoryLink) { return categoryLink; } - } else if (subItem.type === 'html') { - // skip - } else { - throw new Error( - `Unexpected category item type for ${JSON.stringify(subItem)}`, - ); } + // Could be "html" items } return undefined; } @@ -271,7 +266,7 @@ export function useLayoutDoc( const isDraft = versions .flatMap((version) => version.draftIds) .includes(docId); - // drafts should be silently filtered instead of throwing + // Drafts should be silently filtered instead of throwing if (isDraft) { return null; } diff --git a/packages/docusaurus-theme-common/src/utils/tocUtils.ts b/packages/docusaurus-theme-common/src/utils/tocUtils.ts index 2b83f1a2f920..0d1ee35df1f9 100644 --- a/packages/docusaurus-theme-common/src/utils/tocUtils.ts +++ b/packages/docusaurus-theme-common/src/utils/tocUtils.ts @@ -30,11 +30,11 @@ function treeifyTOC(flatTOC: readonly TOCItem[]): TOCTreeNode[] { const prevIndexForLevel = Array(7).fill(-1); headings.forEach((curr, currIndex) => { - // take the last seen index for each ancestor level. the highest - // index will be the direct ancestor of the current heading. + // Take the last seen index for each ancestor level. the highest index will + // be the direct ancestor of the current heading. const ancestorLevelIndexes = prevIndexForLevel.slice(2, curr.level); curr.parentIndex = Math.max(...ancestorLevelIndexes); - // mark that curr.level was last seen at the current index + // Mark that curr.level was last seen at the current index. prevIndexForLevel[curr.level] = currIndex; }); diff --git a/packages/docusaurus-theme-search-algolia/src/client/useAlgoliaContextualFacetFilters.ts b/packages/docusaurus-theme-search-algolia/src/client/useAlgoliaContextualFacetFilters.ts index 343f613145c1..212c03b4321b 100644 --- a/packages/docusaurus-theme-search-algolia/src/client/useAlgoliaContextualFacetFilters.ts +++ b/packages/docusaurus-theme-search-algolia/src/client/useAlgoliaContextualFacetFilters.ts @@ -11,7 +11,7 @@ import {useContextualSearchFilters} from '@docusaurus/theme-common'; export function useAlgoliaContextualFacetFilters(): [string, string[]] { const {locale, tags} = useContextualSearchFilters(); - // seems safe to convert locale->language, see AlgoliaSearchMetadata comment + // Seems safe to convert locale->language, see AlgoliaSearchMetadata comment const languageFilter = `language:${locale}`; const tagsFilter = tags.map((tag) => `docusaurus_tag:${tag}`); diff --git a/packages/docusaurus-theme-search-algolia/src/theme/SearchBar/index.tsx b/packages/docusaurus-theme-search-algolia/src/theme/SearchBar/index.tsx index 864bac42add3..6217dbf50b41 100644 --- a/packages/docusaurus-theme-search-algolia/src/theme/SearchBar/index.tsx +++ b/packages/docusaurus-theme-search-algolia/src/theme/SearchBar/index.tsx @@ -99,7 +99,7 @@ function DocSearch({ : // ... or use config facetFilters configFacetFilters; - // we let user override default searchParameters if he wants to + // We let user override default searchParameters if she wants to const searchParameters: DocSearchProps['searchParameters'] = { ...props.searchParameters, facetFilters, diff --git a/packages/docusaurus-theme-search-algolia/src/validateThemeConfig.ts b/packages/docusaurus-theme-search-algolia/src/validateThemeConfig.ts index 95ff9e9f7cb4..68bd60d163a1 100644 --- a/packages/docusaurus-theme-search-algolia/src/validateThemeConfig.ts +++ b/packages/docusaurus-theme-search-algolia/src/validateThemeConfig.ts @@ -12,7 +12,7 @@ import type { } from '@docusaurus/types'; export const DEFAULT_CONFIG = { - // enabled by default, as it makes sense in most cases + // Enabled by default, as it makes sense in most cases // see also https://github.com/facebook/docusaurus/issues/5880 contextualSearch: true, diff --git a/packages/docusaurus-theme-translations/src/index.ts b/packages/docusaurus-theme-translations/src/index.ts index 068e5be46418..f6b7e7303e19 100644 --- a/packages/docusaurus-theme-translations/src/index.ts +++ b/packages/docusaurus-theme-translations/src/index.ts @@ -16,18 +16,19 @@ function getDefaultLocalesDirPath(): string { // Return an ordered list of locales we should try export function codeTranslationLocalesToTry(locale: string): string[] { const intlLocale = new Intl.Locale(locale); - // if locale is just a simple language like "pt", we want to fallback to pt-BR - // (not pt-PT!) See https://github.com/facebook/docusaurus/pull/4536#issuecomment-810088783 - const maximizedLocale = intlLocale.maximize(); // pt-Latn-BR + // If locale is just a simple language like "pt", we want to fallback to + // "pt-BR" (not "pt-PT"!) + // See https://github.com/facebook/docusaurus/pull/4536#issuecomment-810088783 + const maximizedLocale = intlLocale.maximize(); // "pt-Latn-BR" return [ // May be "zh", "zh-CN", "zh-Hans", "zh-cn", or anything: very likely to be // unresolved except for simply locales locale, - // zh-CN / pt-BR + // "zh-CN" / "pt-BR" `${maximizedLocale.language}-${maximizedLocale.region}`, - // zh-Hans / pt-Latn + // "zh-Hans" / "pt-Latn" `${maximizedLocale.language}-${maximizedLocale.script}`, - // zh / pt + // "zh" / "pt" maximizedLocale.language!, ]; } diff --git a/packages/docusaurus-types/src/index.d.ts b/packages/docusaurus-types/src/index.d.ts index 189c5ef3ebeb..a3663572b9e0 100644 --- a/packages/docusaurus-types/src/index.d.ts +++ b/packages/docusaurus-types/src/index.d.ts @@ -313,9 +313,9 @@ export type Plugin = { name: string; loadContent?: () => Promise | Content; contentLoaded?: (args: { - /** the content loaded by this plugin instance */ + /** The content loaded by this plugin instance */ content: Content; // - /** content loaded by ALL the plugins */ + /** Content loaded by ALL the plugins */ allContent: AllContent; actions: PluginContentLoadedActions; }) => Promise | void; diff --git a/packages/docusaurus-utils/src/__tests__/i18nUtils.test.ts b/packages/docusaurus-utils/src/__tests__/i18nUtils.test.ts index 6e66d7e4a056..c0a458d3a8ec 100644 --- a/packages/docusaurus-utils/src/__tests__/i18nUtils.test.ts +++ b/packages/docusaurus-utils/src/__tests__/i18nUtils.test.ts @@ -156,7 +156,6 @@ describe('localizePath', () => { currentLocale: 'en', localeConfigs: {}, }, - // options: {localizePath: true}, }), ).toBe('/baseUrl/'); }); @@ -172,7 +171,6 @@ describe('localizePath', () => { currentLocale: 'en', localeConfigs: {}, }, - // options: {localizePath: true}, }), ).toBe('/baseUrl/'); }); diff --git a/packages/docusaurus-utils/src/__tests__/markdownUtils.test.ts b/packages/docusaurus-utils/src/__tests__/markdownUtils.test.ts index 5d32b07f1702..09488bc4a6c0 100644 --- a/packages/docusaurus-utils/src/__tests__/markdownUtils.test.ts +++ b/packages/docusaurus-utils/src/__tests__/markdownUtils.test.ts @@ -38,7 +38,7 @@ describe('createExcerpt', () => { Nunc porttitor libero nec vulputate venenatis. Nam nec rhoncus mauris. Morbi tempus est et nibh maximus, tempus venenatis arcu lobortis. `), ).toBe( - // h1 title is skipped on purpose, because we don't want the page to have + // H1 title is skipped on purpose, because we don't want the page to have // SEO metadata title === description 'Lorem ipsum dolor sit amet, consectetur adipiscing elit. Vestibulum ex urna, molestie et sagittis ut, varius ac justo.', ); @@ -56,7 +56,7 @@ describe('createExcerpt', () => { Nunc porttitor libero nec vulputate venenatis. Nam nec rhoncus mauris. Morbi tempus est et nibh maximus, tempus venenatis arcu lobortis. `), ).toBe( - // h1 title is skipped on purpose, because we don't want the page to have + // H1 title is skipped on purpose, because we don't want the page to have // SEO metadata title === description 'Lorem ipsum dolor sit amet, consectetur adipiscing elit. Vestibulum ex urna, molestie et sagittis ut, varius ac justo.', ); @@ -377,7 +377,7 @@ Lorem Ipsum `; - // remove the useless line breaks? Does not matter too much + // Remove the useless line breaks? Does not matter too much expect(parseMarkdownContentTitle(markdown)).toEqual({ content: markdown, contentTitle: 'Markdown Title', diff --git a/packages/docusaurus-utils/src/gitUtils.ts b/packages/docusaurus-utils/src/gitUtils.ts index e2f155bb3e05..2c7d73768d82 100644 --- a/packages/docusaurus-utils/src/gitUtils.ts +++ b/packages/docusaurus-utils/src/gitUtils.ts @@ -112,7 +112,7 @@ export function getFileCommitDate( const result = shell.exec( `git log ${extraArgs} ${formatArg} -- "${path.basename(file)}"`, { - // cwd is important, see: https://github.com/facebook/docusaurus/pull/5048 + // Setting cwd is important, see: https://github.com/facebook/docusaurus/pull/5048 cwd: path.dirname(file), silent: true, }, diff --git a/packages/docusaurus-utils/src/i18nUtils.ts b/packages/docusaurus-utils/src/i18nUtils.ts index 950f3719a7b0..e7e29815beb2 100644 --- a/packages/docusaurus-utils/src/i18nUtils.ts +++ b/packages/docusaurus-utils/src/i18nUtils.ts @@ -61,7 +61,7 @@ export function getPluginI18nPath({ return path.join( siteDir, I18N_DIR_NAME, - // namespace first by locale: convenient to work in a single folder for a + // Namespace first by locale: convenient to work in a single folder for a // translator locale, // Make it convenient to use for single-instance diff --git a/packages/docusaurus-utils/src/pathUtils.ts b/packages/docusaurus-utils/src/pathUtils.ts index 30db78bd7bfb..a9fbb0bd98f7 100644 --- a/packages/docusaurus-utils/src/pathUtils.ts +++ b/packages/docusaurus-utils/src/pathUtils.ts @@ -21,8 +21,10 @@ const isWindows = () => process.platform === 'win32'; export const isNameTooLong = (str: string): boolean => // Not entirely correct: we can't assume FS from OS. But good enough? isMacOs() || isWindows() - ? str.length + SPACE_FOR_APPENDING > MAX_PATH_SEGMENT_CHARS // macOS (APFS) and Windows (NTFS) filename length limit (255 chars) - : Buffer.from(str).length + SPACE_FOR_APPENDING > MAX_PATH_SEGMENT_BYTES; // Other (255 bytes) + ? // Windows (NTFS) and macOS (APFS) filename length limit (255 chars) + str.length + SPACE_FOR_APPENDING > MAX_PATH_SEGMENT_CHARS + : // Other (255 bytes) + Buffer.from(str).length + SPACE_FOR_APPENDING > MAX_PATH_SEGMENT_BYTES; export function shortName(str: string): string { if (isMacOs() || isWindows()) { diff --git a/packages/docusaurus-utils/src/tags.ts b/packages/docusaurus-utils/src/tags.ts index e3eb2933e6f0..88408ef110a4 100644 --- a/packages/docusaurus-utils/src/tags.ts +++ b/packages/docusaurus-utils/src/tags.ts @@ -24,7 +24,7 @@ function normalizeFrontMatterTag( // TODO maybe make ensure the permalink is valid url path? function normalizeTagPermalink(permalink: string): string { - // note: we always apply tagsPath on purpose. For versioned docs, v1/doc.md + // Note: we always apply tagsPath on purpose. For versioned docs, v1/doc.md // and v2/doc.md tags with custom permalinks don't lead to the same created // page. tagsPath is different for each doc version return normalizeUrl([tagsPath, permalink]); diff --git a/packages/docusaurus-utils/src/urlUtils.ts b/packages/docusaurus-utils/src/urlUtils.ts index 1c6f6f5c8591..c6ad13d2d88e 100644 --- a/packages/docusaurus-utils/src/urlUtils.ts +++ b/packages/docusaurus-utils/src/urlUtils.ts @@ -158,7 +158,6 @@ export function isValidPathname(str: string): boolean { return false; } try { - // weird, but is there a better way? const parsedPathname = new URL(str, 'https://domain.com').pathname; return parsedPathname === str || parsedPathname === encodeURI(str); } catch { diff --git a/packages/docusaurus-utils/src/webpackUtils.ts b/packages/docusaurus-utils/src/webpackUtils.ts index 608e384d50d0..4116867c9dff 100644 --- a/packages/docusaurus-utils/src/webpackUtils.ts +++ b/packages/docusaurus-utils/src/webpackUtils.ts @@ -37,11 +37,10 @@ type FileLoaderUtils = { * Inspired by https://github.com/gatsbyjs/gatsby/blob/8e6e021014da310b9cc7d02e58c9b3efe938c665/packages/gatsby/src/utils/webpack-utils.ts#L447 */ export function getFileLoaderUtils(): FileLoaderUtils { - // files/images < urlLoaderLimit will be inlined as base64 strings directly in + // Files/images < urlLoaderLimit will be inlined as base64 strings directly in // the html const urlLoaderLimit = WEBPACK_URL_LOADER_LIMIT; - // defines the path/pattern of the assets handled by webpack const fileLoaderFileName = (folder: AssetFolder) => path.posix.join( OUTPUT_STATIC_ASSETS_DIR_NAME, diff --git a/packages/docusaurus/bin/beforeCli.mjs b/packages/docusaurus/bin/beforeCli.mjs index 53c5ee9e84d3..522867ec1b55 100644 --- a/packages/docusaurus/bin/beforeCli.mjs +++ b/packages/docusaurus/bin/beforeCli.mjs @@ -45,7 +45,6 @@ export default async function beforeCli() { // Check is in background so it's fine to use a small value like 1h // Use 0 for debugging updateCheckInterval: 1000 * 60 * 60, - // updateCheckInterval: 0 }); // Hacky way to ensure we check for updates on first run @@ -124,7 +123,7 @@ export default async function beforeCli() { console.log(docusaurusUpdateMessage); } - // notify user if node version needs to be updated + // Notify user if node version needs to be updated if (!semver.satisfies(process.version, requiredVersion)) { logger.error('Minimum Node.js version not met :('); logger.info`You are using Node.js number=${process.version}, Requirement: Node.js number=${requiredVersion}.`; diff --git a/packages/docusaurus/src/client/.eslintrc.js b/packages/docusaurus/src/client/.eslintrc.js index 5dce52424e15..cbef5af73663 100644 --- a/packages/docusaurus/src/client/.eslintrc.js +++ b/packages/docusaurus/src/client/.eslintrc.js @@ -11,12 +11,11 @@ module.exports = { 'error', { patterns: [ - // prevent importing lodash in client bundle - // prefer shipping vanilla JS + // Prevent importing lodash in client bundle for bundle size 'lodash', 'lodash.**', 'lodash/**', - // prevent importing server code in client bundle + // Prevent importing server code in client bundle '**/../babel/**', '**/../server/**', '**/../commands/**', diff --git a/packages/docusaurus/src/client/BaseUrlIssueBanner/index.tsx b/packages/docusaurus/src/client/BaseUrlIssueBanner/index.tsx index 3ddfaa5ed9d7..3b0621cfc029 100644 --- a/packages/docusaurus/src/client/BaseUrlIssueBanner/index.tsx +++ b/packages/docusaurus/src/client/BaseUrlIssueBanner/index.tsx @@ -41,7 +41,7 @@ function createInlineHtmlBanner(baseUrl: string) { `; } -// fn needs to work for older browsers! +// Needs to work for older browsers! function createInlineScript(baseUrl: string) { return ` window['${InsertBannerWindowAttribute}'] = true; @@ -119,7 +119,6 @@ export default function MaybeBaseUrlIssueBanner(): JSX.Element | null { siteConfig: {baseUrl, baseUrlIssueBanner}, } = useDocusaurusContext(); const {pathname} = useLocation(); - // returns true for the homepage during SSR const isHomePage = pathname === baseUrl; const enabled = baseUrlIssueBanner && isHomePage; return enabled ? : null; diff --git a/packages/docusaurus/src/client/LinksCollector.tsx b/packages/docusaurus/src/client/LinksCollector.tsx index 2df9a8618a2a..d0fb33b9ec03 100644 --- a/packages/docusaurus/src/client/LinksCollector.tsx +++ b/packages/docusaurus/src/client/LinksCollector.tsx @@ -28,8 +28,7 @@ export const createStatefulLinksCollector = (): StatefulLinksCollector => { const Context = React.createContext({ collectLink: () => { - // noop by default for client - // we only use the broken links checker server-side + // No-op for client. We only use the broken links checker server-side. }, }); diff --git a/packages/docusaurus/src/client/exports/Link.tsx b/packages/docusaurus/src/client/exports/Link.tsx index 53da88a7913d..a6760e7fdfce 100644 --- a/packages/docusaurus/src/client/exports/Link.tsx +++ b/packages/docusaurus/src/client/exports/Link.tsx @@ -174,7 +174,7 @@ function Link( onMouseEnter={onMouseEnter} innerRef={handleRef} to={targetLink} - // avoid "React does not recognize the `activeClassName` prop on a DOM + // Avoid "React does not recognize the `activeClassName` prop on a DOM // element" {...(isNavLink && {isActive, activeClassName})} /> diff --git a/packages/docusaurus/src/client/exports/useBaseUrl.ts b/packages/docusaurus/src/client/exports/useBaseUrl.ts index 5ae4640a150c..174ea539c1b7 100644 --- a/packages/docusaurus/src/client/exports/useBaseUrl.ts +++ b/packages/docusaurus/src/client/exports/useBaseUrl.ts @@ -15,17 +15,9 @@ function addBaseUrl( url: string, {forcePrependBaseUrl = false, absolute = false}: BaseUrlOptions = {}, ): string { - if (!url) { - return url; - } - - // it never makes sense to add a base url to a local anchor url - if (url.startsWith('#')) { - return url; - } - - // it never makes sense to add a base url to an url with a protocol - if (hasProtocol(url)) { + // It never makes sense to add base url to a local anchor url, or one with a + // protocol + if (!url || url.startsWith('#') || hasProtocol(url)) { return url; } diff --git a/packages/docusaurus/src/client/routeContext.tsx b/packages/docusaurus/src/client/routeContext.tsx index 1b285859b841..2738eba7c502 100644 --- a/packages/docusaurus/src/client/routeContext.tsx +++ b/packages/docusaurus/src/client/routeContext.tsx @@ -32,7 +32,7 @@ function mergeContexts({ const data = {...parent.data, ...value?.data}; return { - // nested routes are not supposed to override plugin attribute + // Nested routes are not supposed to override plugin attribute plugin: parent.plugin, data, }; diff --git a/packages/docusaurus/src/commands/deploy.ts b/packages/docusaurus/src/commands/deploy.ts index 2de40addb16e..a632fe245be8 100644 --- a/packages/docusaurus/src/commands/deploy.ts +++ b/packages/docusaurus/src/commands/deploy.ts @@ -113,8 +113,9 @@ This behavior can have SEO impacts and create relative link issues. shell.exit(0); } - // github.io indicates organization repos that deploy via default branch. - // All others use gh-pages. Organization deploys looks like: + // github.io indicates organization repos that deploy via default branch. All + // others use gh-pages (either case can be configured actually, but we can + // make educated guesses). Organization deploys look like: // - Git repo: https://github.com//.github.io // - Site url: https://.github.io const isGitHubPagesOrganizationDeploy = projectName.includes('.github.io'); diff --git a/packages/docusaurus/src/commands/start.ts b/packages/docusaurus/src/commands/start.ts index 39da01713433..0b9b8f2e179f 100644 --- a/packages/docusaurus/src/commands/start.ts +++ b/packages/docusaurus/src/commands/start.ts @@ -41,7 +41,7 @@ export async function start( siteDir, customConfigFilePath: cliOptions.config, locale: cliOptions.locale, - localizePath: undefined, // should this be configurable? + localizePath: undefined, // Should this be configurable? }); } diff --git a/packages/docusaurus/src/commands/swizzle/__tests__/actions.test.ts b/packages/docusaurus/src/commands/swizzle/__tests__/actions.test.ts index 90ef17ba783e..159318f62395 100644 --- a/packages/docusaurus/src/commands/swizzle/__tests__/actions.test.ts +++ b/packages/docusaurus/src/commands/swizzle/__tests__/actions.test.ts @@ -13,7 +13,7 @@ import tree from 'tree-node-cli'; import {eject, wrap} from '../actions'; import {posixPath} from '@docusaurus/utils'; -// use relative paths and sort files for tests +// Use relative paths and sort files for tests function stableCreatedFiles( siteThemePath: string, createdFiles: string[], diff --git a/packages/docusaurus/src/commands/swizzle/actions.ts b/packages/docusaurus/src/commands/swizzle/actions.ts index 5e4592ff544f..8bff8fc92873 100644 --- a/packages/docusaurus/src/commands/swizzle/actions.ts +++ b/packages/docusaurus/src/commands/swizzle/actions.ts @@ -53,7 +53,7 @@ export async function eject({ const fromPath = path.join(themePath, componentName); const isDirectory = await isDir(fromPath); const globPattern = isDirectory - ? // do we really want to copy all components? + ? // Do we really want to copy all components? path.join(fromPath, '*') : `${fromPath}.*`; diff --git a/packages/docusaurus/src/server/__tests__/brokenLinks.test.ts b/packages/docusaurus/src/server/__tests__/brokenLinks.test.ts index d1e29b619faf..1226142f972a 100644 --- a/packages/docusaurus/src/server/__tests__/brokenLinks.test.ts +++ b/packages/docusaurus/src/server/__tests__/brokenLinks.test.ts @@ -51,13 +51,13 @@ describe('handleBrokenLinks', () => { const linkToEmptyFolder2 = '/emptyFolder/'; const allCollectedLinks = { '/docs/good doc with space': [ - // good - valid file with spaces in name + // Good - valid file with spaces in name './another%20good%20doc%20with%20space', - // good - valid file with percent-20 in its name + // Good - valid file with percent-20 in its name './weird%20but%20good', - // bad - non-existent file with spaces in name + // Bad - non-existent file with spaces in name './some%20other%20non-existent%20doc1', - // evil - trying to use ../../ but '/' won't get decoded + // Evil - trying to use ../../ but '/' won't get decoded // cSpell:ignore Fout './break%2F..%2F..%2Fout2', ], @@ -91,11 +91,11 @@ describe('handleBrokenLinks', () => { linkToHtmlFile2, linkToJavadoc3, linkToJavadoc4, - linkToEmptyFolder1, // not filtered! + linkToEmptyFolder1, // Not filtered! ], '/page2': [ link2, - linkToEmptyFolder2, // not filtered! + linkToEmptyFolder2, // Not filtered! linkToJavadoc2, link3, linkToJavadoc3, diff --git a/packages/docusaurus/src/server/__tests__/configValidation.test.ts b/packages/docusaurus/src/server/__tests__/configValidation.test.ts index 3a564f9ce3f3..008f71c71588 100644 --- a/packages/docusaurus/src/server/__tests__/configValidation.test.ts +++ b/packages/docusaurus/src/server/__tests__/configValidation.test.ts @@ -287,15 +287,14 @@ describe('normalizeConfig', () => { }); it('throws error for required fields', () => { - expect( - () => - validateConfig({ - invalidField: true, - presets: {}, - stylesheets: {}, - themes: {}, - scripts: {}, - } as unknown as DocusaurusConfig), // to fields not in the type + expect(() => + validateConfig({ + invalidField: true, + presets: {}, + stylesheets: {}, + themes: {}, + scripts: {}, + }), ).toThrowErrorMatchingSnapshot(); }); }); diff --git a/packages/docusaurus/src/server/brokenLinks.ts b/packages/docusaurus/src/server/brokenLinks.ts index c8806fa842af..4ce32b2deaf5 100644 --- a/packages/docusaurus/src/server/brokenLinks.ts +++ b/packages/docusaurus/src/server/brokenLinks.ts @@ -84,7 +84,6 @@ function getAllBrokenLinks({ getPageBrokenLinks({pageLinks, pagePath, routes: filteredRoutes}), ); - // remove pages without any broken link return _.pickBy(allBrokenLinks, (brokenLinks) => brokenLinks.length > 0); } diff --git a/packages/docusaurus/src/server/choosePort.ts b/packages/docusaurus/src/server/choosePort.ts index 11f06ea0c9e2..53a5b5c3cf84 100644 --- a/packages/docusaurus/src/server/choosePort.ts +++ b/packages/docusaurus/src/server/choosePort.ts @@ -5,58 +5,38 @@ * LICENSE file in the root directory of this source tree. */ -import {execSync} from 'child_process'; +import {execSync, type ExecSyncOptionsWithStringEncoding} from 'child_process'; import detect from 'detect-port'; import logger from '@docusaurus/logger'; import prompts from 'prompts'; -const execOptions = { - encoding: 'utf8' as const, - stdio: [ - 'pipe' as const, // stdin (default) - 'pipe' as const, // stdout (default) - 'ignore' as const, // stderr - ], +const execOptions: ExecSyncOptionsWithStringEncoding = { + encoding: 'utf8', + stdio: [/* stdin */ 'pipe', /* stdout */ 'pipe', /* stderr */ 'ignore'], }; -// Clears console function clearConsole(): void { process.stdout.write( process.platform === 'win32' ? '\x1B[2J\x1B[0f' : '\x1B[2J\x1B[3J\x1B[H', ); } -// Gets process id of what is on port -function getProcessIdOnPort(port: number): string { - return execSync(`lsof -i:${port} -P -t -sTCP:LISTEN`, execOptions) - .split('\n')[0]! - .trim(); -} - -// Gets process command -function getProcessCommand(processId: string): string { - const command = execSync( - `ps -o command -p ${processId} | sed -n 2p`, - execOptions, - ); - - return command.replace(/\n$/, ''); -} - -// Gets directory of a process from its process id -function getDirectoryOfProcessById(processId: string): string { - return execSync( - `lsof -p ${processId} | awk '$4=="cwd" {for (i=9; i<=NF; i++) printf "%s ", $i}'`, - execOptions, - ).trim(); -} - -// Gets process on port function getProcessForPort(port: number): string | null { try { - const processId = getProcessIdOnPort(port); - const directory = getDirectoryOfProcessById(processId); - const command = getProcessCommand(processId); + const processId = execSync( + `lsof -i:${port} -P -t -sTCP:LISTEN`, + execOptions, + ) + .split('\n')[0]! + .trim(); + const directory = execSync( + `lsof -p ${processId} | awk '$4=="cwd" {for (i=9; i<=NF; i++) printf "%s ", $i}'`, + execOptions, + ).trim(); + const command = execSync( + `ps -o command -p ${processId} | sed -n 2p`, + execOptions, + ).replace(/\n$/, ''); return logger.interpolate`code=${command} subdue=${`(pid ${processId})`} in path=${directory}`; } catch { return null; diff --git a/packages/docusaurus/src/server/index.ts b/packages/docusaurus/src/server/index.ts index e971d1326313..0ada575f811f 100644 --- a/packages/docusaurus/src/server/index.ts +++ b/packages/docusaurus/src/server/index.ts @@ -166,8 +166,8 @@ export default ${JSON.stringify(siteConfig, null, 2)}; 'client-modules.js', `export default [ ${clientModules - // import() is async so we use require() because client modules can have - // CSS and the order matters for loading CSS. + // Use `require()` because `import()` is async but client modules can have CSS + // and the order matters for loading CSS. .map((clientModule) => ` require('${escapePath(clientModule)}'),`) .join('\n')} ]; diff --git a/packages/docusaurus/src/server/plugins/index.ts b/packages/docusaurus/src/server/plugins/index.ts index c87c99dc9ef0..82c3a53c89fe 100644 --- a/packages/docusaurus/src/server/plugins/index.ts +++ b/packages/docusaurus/src/server/plugins/index.ts @@ -98,7 +98,7 @@ export async function loadPlugins(context: LoadContext): Promise<{ return; } const pluginId = plugin.options.id; - // plugins data files are namespaced by pluginName/pluginId + // Plugins data files are namespaced by pluginName/pluginId const dataDir = path.join( context.generatedFilesDir, plugin.name, diff --git a/packages/docusaurus/src/server/plugins/init.ts b/packages/docusaurus/src/server/plugins/init.ts index 14c01f2ace20..46a010324c2f 100644 --- a/packages/docusaurus/src/server/plugins/init.ts +++ b/packages/docusaurus/src/server/plugins/init.ts @@ -28,7 +28,7 @@ function getOptionValidationFunction( normalizedPluginConfig: NormalizedPluginConfig, ): PluginModule['validateOptions'] { if (normalizedPluginConfig.pluginModule) { - // support both commonjs and ES modules + // Support both CommonJS and ES modules return ( normalizedPluginConfig.pluginModule.module?.default?.validateOptions ?? normalizedPluginConfig.pluginModule.module?.validateOptions @@ -41,7 +41,7 @@ function getThemeValidationFunction( normalizedPluginConfig: NormalizedPluginConfig, ): PluginModule['validateThemeConfig'] { if (normalizedPluginConfig.pluginModule) { - // support both commonjs and ES modules + // Support both CommonJS and ES modules return ( normalizedPluginConfig.pluginModule.module.default?.validateThemeConfig ?? normalizedPluginConfig.pluginModule.module.validateThemeConfig @@ -65,7 +65,6 @@ export async function initPlugins( async function doGetPluginVersion( normalizedPluginConfig: NormalizedPluginConfig, ): Promise { - // get plugin version if (normalizedPluginConfig.pluginModule?.path) { const pluginPath = pluginRequire.resolve( normalizedPluginConfig.pluginModule?.path, diff --git a/packages/docusaurus/src/server/translations/translations.ts b/packages/docusaurus/src/server/translations/translations.ts index 160e9a6bd06b..3e768b8a9041 100644 --- a/packages/docusaurus/src/server/translations/translations.ts +++ b/packages/docusaurus/src/server/translations/translations.ts @@ -94,7 +94,7 @@ function mergeTranslationFileContent({ message: options.override ? message : existingContent[key]?.message ?? message, - description, // description + description, }; }, ); @@ -143,7 +143,7 @@ Maybe you should remove them? ${unknownKeys}`; } } -// should we make this configurable? +// Should we make this configurable? export function getTranslationsLocaleDirPath( context: TranslationContext, ): string { @@ -248,7 +248,7 @@ export async function localizePluginTranslationFile({ const localizedContent = await readTranslationFileContent(filePath); if (localizedContent) { - // localized messages "override" default unlocalized messages + // Localized messages "override" default unlocalized messages return { path: translationFile.path, content: { diff --git a/packages/docusaurus/src/webpack/__tests__/utils.test.ts b/packages/docusaurus/src/webpack/__tests__/utils.test.ts index afcc1477f782..410824ec6584 100644 --- a/packages/docusaurus/src/webpack/__tests__/utils.test.ts +++ b/packages/docusaurus/src/webpack/__tests__/utils.test.ts @@ -52,7 +52,7 @@ describe('customize JS loader', () => { describe('extending generated webpack config', () => { it('direct mutation on generated webpack config object', async () => { - // fake generated webpack config + // Fake generated webpack config let config: Configuration = { output: { path: __dirname, diff --git a/packages/docusaurus/src/webpack/base.ts b/packages/docusaurus/src/webpack/base.ts index 2c59b7d6a873..45a81c1031a4 100644 --- a/packages/docusaurus/src/webpack/base.ts +++ b/packages/docusaurus/src/webpack/base.ts @@ -24,7 +24,7 @@ const CSS_MODULE_REGEX = /\.module\.css$/i; export const clientDir = path.join(__dirname, '..', 'client'); const LibrariesToTranspile = [ - 'copy-text-to-clipboard', // contains optional catch binding, incompatible with recent versions of Edge + 'copy-text-to-clipboard', // Contains optional catch binding, incompatible with recent versions of Edge ]; const LibrariesToTranspileRegex = new RegExp( @@ -32,7 +32,7 @@ const LibrariesToTranspileRegex = new RegExp( ); export function excludeJS(modulePath: string): boolean { - // always transpile client dir + // Always transpile client dir if (modulePath.startsWith(clientDir)) { return false; } @@ -118,9 +118,9 @@ export async function createBaseConfig( }, devtool: isProd ? undefined : 'eval-cheap-module-source-map', resolve: { - unsafeCache: false, // not enabled, does not seem to improve perf much + unsafeCache: false, // Not enabled, does not seem to improve perf much extensions: ['.wasm', '.mjs', '.js', '.jsx', '.ts', '.tsx', '.json'], - symlinks: true, // see https://github.com/facebook/docusaurus/issues/3272 + symlinks: true, // See https://github.com/facebook/docusaurus/issues/3272 roots: [ // Allow resolution of url("/fonts/xyz.ttf") by webpack // See https://webpack.js.org/configuration/resolve/#resolveroots @@ -167,7 +167,7 @@ export async function createBaseConfig( // include [name] in the filenames name: false, cacheGroups: { - // disable the built-in cacheGroups + // Disable the built-in cacheGroups default: false, common: { name: 'common', @@ -238,7 +238,7 @@ export async function createBaseConfig( chunkFilename: isProd ? 'assets/css/[name].[contenthash:8].css' : '[name].css', - // remove css order warnings if css imports are not sorted + // Remove css order warnings if css imports are not sorted // alphabetically. See https://github.com/webpack-contrib/mini-css-extract-plugin/pull/422 // for more reasoning ignoreOrder: true, diff --git a/packages/docusaurus/src/webpack/client.ts b/packages/docusaurus/src/webpack/client.ts index ffe0a704eb95..f7ca7de770b2 100644 --- a/packages/docusaurus/src/webpack/client.ts +++ b/packages/docusaurus/src/webpack/client.ts @@ -23,7 +23,7 @@ export default async function createClientConfig( const config = await createBaseConfig(props, false, minify); const clientConfig = merge(config, { - // useless, disabled on purpose (errors on existing sites with no + // Useless, disabled on purpose (errors on existing sites with no // browserslist config) // target: 'browserslist', entry: path.resolve(__dirname, '../client/clientEntry.js'), diff --git a/packages/docusaurus/src/webpack/utils.ts b/packages/docusaurus/src/webpack/utils.ts index 85345c201b0a..1e823c6943fb 100644 --- a/packages/docusaurus/src/webpack/utils.ts +++ b/packages/docusaurus/src/webpack/utils.ts @@ -204,7 +204,7 @@ export function applyConfigurePostCss( options: {postcssOptions: PostCssOptions}; }; - // not ideal heuristic but good enough for our use-case? + // Not ideal heuristic but good enough for our use-case? function isPostCssLoader(loader: unknown): loader is LocalPostCSSLoader { return !!(loader as LocalPostCSSLoader)?.options?.postcssOptions; } @@ -249,7 +249,7 @@ export function compile(config: Configuration[]): Promise { } reject(err); } - // let plugins consume all the stats + // Let plugins consume all the stats const errorsWarnings = stats?.toJson('errors-warnings'); if (stats?.hasErrors()) { reject(new Error('Failed to compile with errors.')); @@ -363,7 +363,7 @@ export function getMinimizer( parallel: getTerserParallel(), terserOptions: { parse: { - // we want uglify-js to parse ecma 8 code. However, we don't want it + // We want uglify-js to parse ecma 8 code. However, we don't want it // to apply any minification steps that turns valid ecma 5 code // into invalid ecma 5 code. This is why the 'compress' and 'output' // sections only apply transformations that are ecma 5 safe diff --git a/packages/lqip-loader/src/lqip.ts b/packages/lqip-loader/src/lqip.ts index f6ab095a1868..b6286872b44d 100644 --- a/packages/lqip-loader/src/lqip.ts +++ b/packages/lqip-loader/src/lqip.ts @@ -21,8 +21,8 @@ const SUPPORTED_MIMES: {[ext: string]: string} = { }; /** - * it returns a Base64 image string with required formatting - * to work on the web ( or in CSS url('..')) + * It returns a Base64 image string with required formatting to work on the web + * ( or in CSS url('..')) */ const toBase64 = (extMimeType: string, data: Buffer): string => `data:${extMimeType};base64,${data.toString('base64')}`; diff --git a/project-words.txt b/project-words.txt index 1c730dc2c574..5bd78cccc06e 100644 --- a/project-words.txt +++ b/project-words.txt @@ -21,6 +21,7 @@ backticks bartosz beforeinstallprompt bhatt +blocklist blockquotes browserslist browserstack diff --git a/website/_dogfooding/docs-tests-sidebars.js b/website/_dogfooding/docs-tests-sidebars.js index 0143596f80a1..6b8b8f9c4365 100644 --- a/website/_dogfooding/docs-tests-sidebars.js +++ b/website/_dogfooding/docs-tests-sidebars.js @@ -87,7 +87,7 @@ const sidebars = { collapsed: false, collapsible: false, items: [ - // title + // Title { type: 'html', value: 'Some Text', diff --git a/website/_dogfooding/dogfooding.config.js b/website/_dogfooding/dogfooding.config.js index 5d7cea7670ee..95c1d5161843 100644 --- a/website/_dogfooding/dogfooding.config.js +++ b/website/_dogfooding/dogfooding.config.js @@ -22,7 +22,7 @@ exports.dogfoodingThemeInstances = dogfoodingThemeInstances; /** @type {import('@docusaurus/types').PluginConfig[]} */ const dogfoodingPluginInstances = [ [ - 'content-docs', // dogfood shorthand + 'content-docs', // Shorthand /** @type {import('@docusaurus/plugin-content-docs').Options} */ ({ id: 'docs-tests', @@ -52,7 +52,7 @@ const dogfoodingPluginInstances = [ ], [ - '@docusaurus/plugin-content-blog', // dogfood longhand + '@docusaurus/plugin-content-blog', // Longhand /** @type {import('@docusaurus/plugin-content-blog').Options} */ ({ id: 'blog-tests', @@ -75,7 +75,7 @@ const dogfoodingPluginInstances = [ ], [ - require.resolve('@docusaurus/plugin-content-pages'), // dogfood longhand resolve + require.resolve('@docusaurus/plugin-content-pages'), // Full path /** @type {import('@docusaurus/plugin-content-pages').Options} */ ({ id: 'pages-tests', diff --git a/website/_dogfooding/testSwizzleThemeClassic.mjs b/website/_dogfooding/testSwizzleThemeClassic.mjs index 61f1162b9848..b8b4a4cb1a76 100644 --- a/website/_dogfooding/testSwizzleThemeClassic.mjs +++ b/website/_dogfooding/testSwizzleThemeClassic.mjs @@ -68,16 +68,16 @@ Please double-check or clean up these components from the config: // TODO temp workaround: non-comps should be forbidden to wrap if (action === 'wrap') { - const WrapBlacklist = [ - 'Layout', // due to theme-fallback? + const WrapBlocklist = [ + 'Layout', // Due to theme-fallback? ]; componentNames = componentNames.filter((componentName) => { - const blacklisted = WrapBlacklist.includes(componentName); - if (!WrapBlacklist) { - logger.warn(`${componentName} is blacklisted and will not be wrapped`); + const blocked = WrapBlocklist.includes(componentName); + if (blocked) { + logger.warn(`${componentName} is blocked and will not be wrapped`); } - return !blacklisted; + return !blocked; }); } diff --git a/website/docusaurus.config.js b/website/docusaurus.config.js index 8e396e641b41..df57e09ac88c 100644 --- a/website/docusaurus.config.js +++ b/website/docusaurus.config.js @@ -170,8 +170,8 @@ const config = { ({ fromExtensions: ['html'], createRedirects(routePath) { - // redirect to /docs from /docs/introduction, - // as introduction has been made the home doc + // Redirect to /docs from /docs/introduction, as introduction has been + // made the home doc if (allDocHomesPaths.includes(routePath)) { return [`${routePath}/introduction`]; } @@ -195,13 +195,15 @@ const config = { ], [ 'ideal-image', - { + /** @type {import('@docusaurus/plugin-ideal-image').PluginOptions} */ + ({ quality: 70, - max: 1030, // max resized image's size. - min: 640, // min resized image's size. if original is lower, use that size. - steps: 2, // the max number of images generated between min and max (inclusive) - // disableInDev: false, - }, + max: 1030, + min: 640, + steps: 2, + // Use false to debug, but it incurs huge perf costs + disableInDev: true, + }), ], [ 'pwa', @@ -413,7 +415,7 @@ const config = { label: 'Tests', docsPluginId: 'docs-tests', }, - // right + // Right { type: 'docsVersionDropdown', position: 'right', diff --git a/website/testCSSOrder.mjs b/website/testCSSOrder.mjs index e177eef75d93..0b1aaa7129a7 100644 --- a/website/testCSSOrder.mjs +++ b/website/testCSSOrder.mjs @@ -47,7 +47,7 @@ const EXPECTED_CSS_MARKERS = [ '.test-marker-theme-layout', '.test-marker-site-index-page', - // lazy loaded lib + // Lazy-loaded lib '.DocSearch-Modal', ]; diff --git a/website/waitForCrowdin.mjs b/website/waitForCrowdin.mjs index 577abf38cc3a..d8e2823b5008 100644 --- a/website/waitForCrowdin.mjs +++ b/website/waitForCrowdin.mjs @@ -24,7 +24,7 @@ const pollInterval = 5000; const timeout = 5 * 60 * 1000; const projectId = 428890; -const token = process.env.CROWDIN_PERSONAL_TOKEN; // set on Netlify +const token = process.env.CROWDIN_PERSONAL_TOKEN; // Set on Netlify const translations = new Translations({token});