From cf265c051e68589af81e4dea7926e33097f9e2dd Mon Sep 17 00:00:00 2001 From: Joshua Chen Date: Sun, 9 Jan 2022 22:02:31 +0800 Subject: [PATCH] refactor: move exported type definitions to declaration file (#6300) * refactor: move exported type definitions to declaration file * fix * fix --- .../src/__tests__/collectRedirects.test.ts | 5 +- .../src/collectRedirects.ts | 5 +- .../src/index.ts | 5 +- .../src/normalizePluginOptions.ts | 6 +- .../src/plugin-client-redirects.d.ts | 21 ++- .../src/types.ts | 22 +-- .../src/__tests__/blogFrontMatter.test.ts | 6 +- .../src/__tests__/feed.test.ts | 3 +- .../src/__tests__/index.test.ts | 6 +- .../src/__tests__/translations.test.ts | 3 +- .../docusaurus-plugin-content-blog/src/authors.ts | 5 +- .../src/blogFrontMatter.ts | 47 +------ .../src/blogUtils.ts | 6 +- .../docusaurus-plugin-content-blog/src/feed.ts | 7 +- .../docusaurus-plugin-content-blog/src/index.ts | 8 +- .../src/plugin-content-blog.d.ts | 150 ++++++++++++++++++++- .../src/pluginOptionSchema.ts | 2 +- .../src/translations.ts | 3 +- .../docusaurus-plugin-content-blog/src/types.ts | 101 +------------- .../src/__tests__/cli.test.ts | 5 +- .../src/__tests__/docs.test.ts | 8 +- .../src/__tests__/options.test.ts | 2 +- .../src/__tests__/versions.test.ts | 3 +- packages/docusaurus-plugin-content-docs/src/cli.ts | 5 +- .../src/client/docsClientUtils.ts | 38 ++---- .../src/client/globalDataHooks.ts | 13 +- .../docusaurus-plugin-content-docs/src/docs.ts | 6 +- .../src/globalData.ts | 7 +- .../docusaurus-plugin-content-docs/src/index.ts | 8 +- .../src/numberPrefix.ts | 2 +- .../docusaurus-plugin-content-docs/src/options.ts | 2 +- .../src/plugin-content-docs.d.ts | 133 +++++++++++++++--- .../src/sidebars/index.ts | 3 +- .../src/sidebars/normalization.ts | 3 +- .../src/sidebars/processor.ts | 11 +- .../src/sidebars/types.ts | 5 +- .../docusaurus-plugin-content-docs/src/slug.ts | 3 +- .../docusaurus-plugin-content-docs/src/types.ts | 114 +--------------- .../docusaurus-plugin-content-docs/src/versions.ts | 14 +- .../src/__tests__/pluginOptionSchema.test.ts | 2 +- .../docusaurus-plugin-content-pages/src/index.ts | 8 +- .../src/plugin-content-pages.d.ts | 14 +- .../src/pluginOptionSchema.ts | 2 +- .../docusaurus-plugin-content-pages/src/types.ts | 12 -- packages/docusaurus-preset-classic/package.json | 1 + .../src/preset-classic.d.ts | 32 +++-- .../src/theme-classic.d.ts | 6 +- .../src/theme/NavbarItem/DocNavbarItem.tsx | 6 +- .../src/theme/NavbarItem/DocSidebarNavbarItem.tsx | 13 +- .../NavbarItem/DocsVersionDropdownNavbarItem.tsx | 4 +- .../docusaurus-theme-search-algolia/package.json | 3 +- .../src/theme-search-algolia.d.ts | 27 ++-- .../src/theme/SearchMetadata/index.tsx | 8 +- 53 files changed, 482 insertions(+), 452 deletions(-) diff --git a/packages/docusaurus-plugin-client-redirects/src/__tests__/collectRedirects.test.ts b/packages/docusaurus-plugin-client-redirects/src/__tests__/collectRedirects.test.ts index f7d4c9e9f3..e44846c524 100644 --- a/packages/docusaurus-plugin-client-redirects/src/__tests__/collectRedirects.test.ts +++ b/packages/docusaurus-plugin-client-redirects/src/__tests__/collectRedirects.test.ts @@ -5,13 +5,14 @@ * LICENSE file in the root directory of this source tree. */ -import type {PluginContext, UserPluginOptions} from '../types'; +import type {PluginContext} from '../types'; import collectRedirects from '../collectRedirects'; import normalizePluginOptions from '../normalizePluginOptions'; import {removeTrailingSlash} from '@docusaurus/utils'; +import type {Options} from '@docusaurus/plugin-client-redirects'; function createTestPluginContext( - options?: UserPluginOptions, + options?: Options, relativeRoutesPaths: string[] = [], ): PluginContext { return { diff --git a/packages/docusaurus-plugin-client-redirects/src/collectRedirects.ts b/packages/docusaurus-plugin-client-redirects/src/collectRedirects.ts index 79cb0b3237..0a5c76e85b 100644 --- a/packages/docusaurus-plugin-client-redirects/src/collectRedirects.ts +++ b/packages/docusaurus-plugin-client-redirects/src/collectRedirects.ts @@ -7,11 +7,10 @@ import {uniqBy, difference, groupBy} from 'lodash'; import type { - PluginContext, - RedirectMetadata, PluginOptions, RedirectOption, -} from './types'; +} from '@docusaurus/plugin-client-redirects'; +import type {PluginContext, RedirectMetadata} from './types'; import { createFromExtensionsRedirects, createToExtensionsRedirects, diff --git a/packages/docusaurus-plugin-client-redirects/src/index.ts b/packages/docusaurus-plugin-client-redirects/src/index.ts index 86acdec8ef..2fc739c484 100644 --- a/packages/docusaurus-plugin-client-redirects/src/index.ts +++ b/packages/docusaurus-plugin-client-redirects/src/index.ts @@ -6,7 +6,8 @@ */ import type {LoadContext, Plugin, Props} from '@docusaurus/types'; -import type {UserPluginOptions, PluginContext, RedirectMetadata} from './types'; +import type {PluginContext, RedirectMetadata} from './types'; +import type {PluginOptions} from '@docusaurus/plugin-client-redirects'; import normalizePluginOptions from './normalizePluginOptions'; import collectRedirects from './collectRedirects'; @@ -18,7 +19,7 @@ import {removePrefix, addLeadingSlash} from '@docusaurus/utils'; export default function pluginClientRedirectsPages( context: LoadContext, - opts: UserPluginOptions, + opts: PluginOptions, ): Plugin { const {trailingSlash} = context.siteConfig; diff --git a/packages/docusaurus-plugin-client-redirects/src/normalizePluginOptions.ts b/packages/docusaurus-plugin-client-redirects/src/normalizePluginOptions.ts index b91a2338a8..f3d2cfb82a 100644 --- a/packages/docusaurus-plugin-client-redirects/src/normalizePluginOptions.ts +++ b/packages/docusaurus-plugin-client-redirects/src/normalizePluginOptions.ts @@ -5,7 +5,11 @@ * LICENSE file in the root directory of this source tree. */ -import type {PluginOptions, RedirectOption, UserPluginOptions} from './types'; +import type { + PluginOptions, + Options as UserPluginOptions, + RedirectOption, +} from '@docusaurus/plugin-client-redirects'; import {Joi, PathnameSchema} from '@docusaurus/utils-validation'; import {DEFAULT_PLUGIN_ID} from '@docusaurus/utils'; diff --git a/packages/docusaurus-plugin-client-redirects/src/plugin-client-redirects.d.ts b/packages/docusaurus-plugin-client-redirects/src/plugin-client-redirects.d.ts index c0e75f2f0d..fb580bae6a 100644 --- a/packages/docusaurus-plugin-client-redirects/src/plugin-client-redirects.d.ts +++ b/packages/docusaurus-plugin-client-redirects/src/plugin-client-redirects.d.ts @@ -5,4 +5,23 @@ * LICENSE file in the root directory of this source tree. */ -export type Options = import('./types').UserPluginOptions; +export type RedirectOption = { + to: string; + from: string | string[]; +}; + +// For a given existing route path, +// return all the paths from which we should redirect from +export type CreateRedirectsFnOption = ( + path: string, +) => string[] | string | null | undefined; + +export type PluginOptions = { + id: string; + fromExtensions: string[]; + toExtensions: string[]; + redirects: RedirectOption[]; + createRedirects?: CreateRedirectsFnOption; +}; + +export type Options = Partial; diff --git a/packages/docusaurus-plugin-client-redirects/src/types.ts b/packages/docusaurus-plugin-client-redirects/src/types.ts index b2132f5693..2affd0c6c5 100644 --- a/packages/docusaurus-plugin-client-redirects/src/types.ts +++ b/packages/docusaurus-plugin-client-redirects/src/types.ts @@ -6,27 +6,7 @@ */ import type {Props} from '@docusaurus/types'; - -export type PluginOptions = { - id: string; - fromExtensions: string[]; - toExtensions: string[]; - redirects: RedirectOption[]; - createRedirects?: CreateRedirectsFnOption; -}; - -// For a given existing route path, -// return all the paths from which we should redirect from -export type CreateRedirectsFnOption = ( - path: string, -) => string[] | string | null | undefined; - -export type RedirectOption = { - to: string; - from: string | string[]; -}; - -export type UserPluginOptions = Partial; +import type {PluginOptions} from '@docusaurus/plugin-client-redirects'; // The minimal infos the plugin needs to work export type PluginContext = Pick & { diff --git a/packages/docusaurus-plugin-content-blog/src/__tests__/blogFrontMatter.test.ts b/packages/docusaurus-plugin-content-blog/src/__tests__/blogFrontMatter.test.ts index ca7372e281..d35bf0e121 100644 --- a/packages/docusaurus-plugin-content-blog/src/__tests__/blogFrontMatter.test.ts +++ b/packages/docusaurus-plugin-content-blog/src/__tests__/blogFrontMatter.test.ts @@ -5,11 +5,9 @@ * LICENSE file in the root directory of this source tree. */ -import { - type BlogPostFrontMatter, - validateBlogPostFrontMatter, -} from '../blogFrontMatter'; +import {validateBlogPostFrontMatter} from '../blogFrontMatter'; import escapeStringRegexp from 'escape-string-regexp'; +import type {BlogPostFrontMatter} from '@docusaurus/plugin-content-blog'; // TODO this abstraction reduce verbosity but it makes it harder to debug // It would be preferable to just expose helper methods diff --git a/packages/docusaurus-plugin-content-blog/src/__tests__/feed.test.ts b/packages/docusaurus-plugin-content-blog/src/__tests__/feed.test.ts index 19e71316d6..4501b476d1 100644 --- a/packages/docusaurus-plugin-content-blog/src/__tests__/feed.test.ts +++ b/packages/docusaurus-plugin-content-blog/src/__tests__/feed.test.ts @@ -8,10 +8,11 @@ import path from 'path'; import {generateBlogFeed} from '../feed'; import type {LoadContext, I18n} from '@docusaurus/types'; -import type {PluginOptions, BlogContentPaths} from '../types'; +import type {BlogContentPaths} from '../types'; import {DEFAULT_OPTIONS} from '../pluginOptionSchema'; import {generateBlogPosts} from '../blogUtils'; import type {Feed} from 'feed'; +import type {PluginOptions} from '@docusaurus/plugin-content-blog'; const DefaultI18N: I18n = { currentLocale: 'en', 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 6b14ea01a3..78fccd857d 100644 --- a/packages/docusaurus-plugin-content-blog/src/__tests__/index.test.ts +++ b/packages/docusaurus-plugin-content-blog/src/__tests__/index.test.ts @@ -10,9 +10,13 @@ import path from 'path'; import pluginContentBlog from '../index'; import type {DocusaurusConfig, LoadContext, I18n} from '@docusaurus/types'; import {PluginOptionSchema} from '../pluginOptionSchema'; -import type {PluginOptions, EditUrlFunction, BlogPost} from '../types'; +import type {BlogPost} from '../types'; import type {Joi} from '@docusaurus/utils-validation'; import {posixPath} from '@docusaurus/utils'; +import type { + PluginOptions, + EditUrlFunction, +} from '@docusaurus/plugin-content-blog'; function findByTitle( blogPosts: BlogPost[], diff --git a/packages/docusaurus-plugin-content-blog/src/__tests__/translations.test.ts b/packages/docusaurus-plugin-content-blog/src/__tests__/translations.test.ts index 6c00f03b4a..9844c4cab9 100644 --- a/packages/docusaurus-plugin-content-blog/src/__tests__/translations.test.ts +++ b/packages/docusaurus-plugin-content-blog/src/__tests__/translations.test.ts @@ -5,10 +5,11 @@ * LICENSE file in the root directory of this source tree. */ -import type {BlogPost, BlogContent, PluginOptions} from '../types'; +import type {BlogPost, BlogContent} from '../types'; import {getTranslationFiles, translateContent} from '../translations'; import {DEFAULT_OPTIONS} from '../pluginOptionSchema'; import {updateTranslationFileMessages} from '@docusaurus/utils'; +import type {PluginOptions} from '@docusaurus/plugin-content-blog'; const sampleBlogOptions: PluginOptions = { ...DEFAULT_OPTIONS, diff --git a/packages/docusaurus-plugin-content-blog/src/authors.ts b/packages/docusaurus-plugin-content-blog/src/authors.ts index 938c86ad02..cab9f5363e 100644 --- a/packages/docusaurus-plugin-content-blog/src/authors.ts +++ b/packages/docusaurus-plugin-content-blog/src/authors.ts @@ -5,14 +5,15 @@ * LICENSE file in the root directory of this source tree. */ -import type {Author, BlogContentPaths} from './types'; +import type {BlogContentPaths} from './types'; import {getDataFileData} from '@docusaurus/utils'; import {Joi, URISchema} from '@docusaurus/utils-validation'; import type { + Author, BlogPostFrontMatter, BlogPostFrontMatterAuthor, BlogPostFrontMatterAuthors, -} from './blogFrontMatter'; +} from '@docusaurus/plugin-content-blog'; export type AuthorsMap = Record; diff --git a/packages/docusaurus-plugin-content-blog/src/blogFrontMatter.ts b/packages/docusaurus-plugin-content-blog/src/blogFrontMatter.ts index 49eeaad8a8..b1eba293ee 100644 --- a/packages/docusaurus-plugin-content-blog/src/blogFrontMatter.ts +++ b/packages/docusaurus-plugin-content-blog/src/blogFrontMatter.ts @@ -12,21 +12,7 @@ import { FrontMatterTagsSchema, FrontMatterTOCHeadingLevels, } from '@docusaurus/utils-validation'; -import type {FrontMatterTag} from '@docusaurus/utils'; - -export type BlogPostFrontMatterAuthor = Record & { - key?: string; - name?: string; - imageURL?: string; - url?: string; - title?: string; -}; - -// All the possible variants that the user can use for convenience -export type BlogPostFrontMatterAuthors = - | string - | BlogPostFrontMatterAuthor - | (string | BlogPostFrontMatterAuthor)[]; +import type {BlogPostFrontMatter} from '@docusaurus/plugin-content-blog'; const BlogPostFrontMatterAuthorSchema = Joi.object({ key: Joi.string(), @@ -38,37 +24,6 @@ const BlogPostFrontMatterAuthorSchema = Joi.object({ .or('key', 'name') .rename('image_url', 'imageURL', {alias: true}); -export type BlogPostFrontMatter = { - id?: string; - title?: string; - description?: string; - tags?: FrontMatterTag[]; - slug?: string; - draft?: boolean; - date?: Date | string; // Yaml automagically convert some string patterns as Date, but not all - - authors?: BlogPostFrontMatterAuthors; - - // We may want to deprecate those older author frontmatter fields later: - author?: string; - author_title?: string; - author_url?: string; - author_image_url?: string; - - /** @deprecated */ - authorTitle?: string; - /** @deprecated */ - authorURL?: string; - /** @deprecated */ - authorImageURL?: string; - - image?: string; - keywords?: string[]; - hide_table_of_contents?: boolean; - toc_min_heading_level?: number; - toc_max_heading_level?: number; -}; - const FrontMatterAuthorErrorMessage = '{{#label}} does not look like a valid blog post author. Please use an author key or an author object (with a key and/or name).'; diff --git a/packages/docusaurus-plugin-content-blog/src/blogUtils.ts b/packages/docusaurus-plugin-content-blog/src/blogUtils.ts index b8f668006b..e1c6a47eef 100644 --- a/packages/docusaurus-plugin-content-blog/src/blogUtils.ts +++ b/packages/docusaurus-plugin-content-blog/src/blogUtils.ts @@ -10,12 +10,10 @@ import path from 'path'; import readingTime from 'reading-time'; import {keyBy, mapValues} from 'lodash'; import type { - PluginOptions, BlogPost, BlogContentPaths, BlogMarkdownLoaderOptions, BlogTags, - ReadingTimeFunction, } from './types'; import { parseMarkdownFile, @@ -34,6 +32,10 @@ import type {LoadContext} from '@docusaurus/types'; import {validateBlogPostFrontMatter} from './blogFrontMatter'; import {type AuthorsMap, getAuthorsMap, getBlogPostAuthors} from './authors'; import logger from '@docusaurus/logger'; +import type { + PluginOptions, + ReadingTimeFunction, +} from '@docusaurus/plugin-content-blog'; export function truncate(fileString: string, truncateMarker: RegExp): string { return fileString.split(truncateMarker, 1).shift()!; diff --git a/packages/docusaurus-plugin-content-blog/src/feed.ts b/packages/docusaurus-plugin-content-blog/src/feed.ts index b0a83626ee..3e45c6095e 100644 --- a/packages/docusaurus-plugin-content-blog/src/feed.ts +++ b/packages/docusaurus-plugin-content-blog/src/feed.ts @@ -6,11 +6,16 @@ */ import {Feed, type Author as FeedAuthor, type Item as FeedItem} from 'feed'; -import type {PluginOptions, Author, BlogPost, FeedType} from './types'; +import type {BlogPost} from './types'; import {normalizeUrl, mdxToHtml} from '@docusaurus/utils'; import type {DocusaurusConfig} from '@docusaurus/types'; import path from 'path'; import fs from 'fs-extra'; +import type { + FeedType, + PluginOptions, + Author, +} from '@docusaurus/plugin-content-blog'; // TODO this is temporary until we handle mdxToHtml better // It's hard to convert reliably JSX/require calls to an html feed content diff --git a/packages/docusaurus-plugin-content-blog/src/index.ts b/packages/docusaurus-plugin-content-blog/src/index.ts index c168b5175b..2d1ad57626 100644 --- a/packages/docusaurus-plugin-content-blog/src/index.ts +++ b/packages/docusaurus-plugin-content-blog/src/index.ts @@ -23,7 +23,6 @@ import { import {translateContent, getTranslationFiles} from './translations'; import type { - PluginOptions, BlogTags, BlogContent, BlogItemsToMetadata, @@ -32,7 +31,6 @@ import type { BlogContentPaths, BlogMarkdownLoaderOptions, MetaData, - Assets, } from './types'; import {PluginOptionSchema} from './pluginOptionSchema'; import type { @@ -50,8 +48,12 @@ import { getSourceToPermalink, getBlogTags, } from './blogUtils'; -import type {BlogPostFrontMatter} from './blogFrontMatter'; import {createBlogFeedFiles} from './feed'; +import type { + PluginOptions, + BlogPostFrontMatter, + Assets, +} from '@docusaurus/plugin-content-blog'; export default async function pluginContentBlog( context: LoadContext, diff --git a/packages/docusaurus-plugin-content-blog/src/plugin-content-blog.d.ts b/packages/docusaurus-plugin-content-blog/src/plugin-content-blog.d.ts index ea8ed6e0f9..e141e2dd9f 100644 --- a/packages/docusaurus-plugin-content-blog/src/plugin-content-blog.d.ts +++ b/packages/docusaurus-plugin-content-blog/src/plugin-content-blog.d.ts @@ -6,7 +6,145 @@ */ declare module '@docusaurus/plugin-content-blog' { - export type Options = Partial; + import type {RemarkAndRehypePluginOptions} from '@docusaurus/mdx-loader'; + import type {FrontMatterTag} from '@docusaurus/utils'; + import type {Overwrite} from 'utility-types'; + + export interface Assets { + image?: string; + authorsImageUrls: (string | undefined)[]; // Array of same size as the original MetaData.authors array + } + + // We allow passing custom fields to authors, e.g., twitter + export interface Author extends Record { + name?: string; + imageURL?: string; + url?: string; + title?: string; + } + + export type BlogPostFrontMatter = { + id?: string; + title?: string; + description?: string; + tags?: FrontMatterTag[]; + slug?: string; + draft?: boolean; + date?: Date | string; // Yaml automagically convert some string patterns as Date, but not all + + authors?: BlogPostFrontMatterAuthors; + + // We may want to deprecate those older author frontmatter fields later: + author?: string; + author_title?: string; + author_url?: string; + author_image_url?: string; + + /** @deprecated */ + authorTitle?: string; + /** @deprecated */ + authorURL?: string; + /** @deprecated */ + authorImageURL?: string; + + image?: string; + keywords?: string[]; + hide_table_of_contents?: boolean; + toc_min_heading_level?: number; + toc_max_heading_level?: number; + }; + + export type BlogPostFrontMatterAuthor = Record & { + key?: string; + name?: string; + imageURL?: string; + url?: string; + title?: string; + }; + + // All the possible variants that the user can use for convenience + export type BlogPostFrontMatterAuthors = + | string + | BlogPostFrontMatterAuthor + | (string | BlogPostFrontMatterAuthor)[]; + + export type EditUrlFunction = (editUrlParams: { + blogDirPath: string; + blogPath: string; + permalink: string; + locale: string; + }) => string | undefined; + + export type FeedType = 'rss' | 'atom' | 'json'; + export type FeedOptions = { + type?: FeedType[] | null; + title?: string; + description?: string; + copyright: string; + language?: string; + }; + // Feed options, as provided by user config + export type UserFeedOptions = Overwrite< + Partial, + {type?: FeedOptions['type'] | 'all'} // Handle the type: "all" shortcut + >; + + // Duplicate from ngryman/reading-time to keep stability of API + type ReadingTimeOptions = { + wordsPerMinute?: number; + wordBound?: (char: string) => boolean; + }; + + export type ReadingTimeFunction = (params: { + content: string; + frontMatter?: BlogPostFrontMatter & Record; + options?: ReadingTimeOptions; + }) => number; + + export type ReadingTimeFunctionOption = ( + params: Required[0], 'options'>> & { + defaultReadingTime: ReadingTimeFunction; + }, + ) => number | undefined; + + export type PluginOptions = RemarkAndRehypePluginOptions & { + id?: string; + path: string; + routeBasePath: string; + tagsBasePath: string; + archiveBasePath: string; + include: string[]; + exclude: string[]; + postsPerPage: number | 'ALL'; + blogListComponent: string; + blogPostComponent: string; + blogTagsListComponent: string; + blogTagsPostsComponent: string; + blogTitle: string; + blogDescription: string; + blogSidebarCount: number | 'ALL'; + blogSidebarTitle: string; + truncateMarker: RegExp; + showReadingTime: boolean; + feedOptions: { + type?: FeedType[] | null; + title?: string; + description?: string; + copyright: string; + language?: string; + }; + editUrl?: string | EditUrlFunction; + editLocalizedFiles?: boolean; + admonitions: Record; + authorsMapPath: string; + readingTime: ReadingTimeFunctionOption; + sortPosts: 'ascending' | 'descending'; + }; + // Options, as provided in the user config (before normalization) + export type Options = Overwrite< + Partial, + {feedOptions?: UserFeedOptions} + >; } declare module '@theme/BlogSidebar' { @@ -27,9 +165,13 @@ declare module '@theme/BlogSidebar' { declare module '@theme/BlogPostPage' { import type {BlogSidebar} from '@theme/BlogSidebar'; import type {TOCItem} from '@docusaurus/types'; + import type { + BlogPostFrontMatter, + Author, + Assets, + } from '@docusaurus/plugin-content-blog'; - export type FrontMatter = import('./blogFrontMatter').BlogPostFrontMatter; - export type Assets = import('./types').Assets; + export type FrontMatter = BlogPostFrontMatter; export type Metadata = { readonly title: string; @@ -42,7 +184,7 @@ declare module '@theme/BlogPostPage' { readonly truncated?: string; readonly nextItem?: {readonly title: string; readonly permalink: string}; readonly prevItem?: {readonly title: string; readonly permalink: string}; - readonly authors: import('./types').Author[]; + readonly authors: Author[]; readonly frontMatter: FrontMatter & Record; readonly tags: readonly { readonly label: string; diff --git a/packages/docusaurus-plugin-content-blog/src/pluginOptionSchema.ts b/packages/docusaurus-plugin-content-blog/src/pluginOptionSchema.ts index d21297f770..4fcf2064ba 100644 --- a/packages/docusaurus-plugin-content-blog/src/pluginOptionSchema.ts +++ b/packages/docusaurus-plugin-content-blog/src/pluginOptionSchema.ts @@ -13,7 +13,7 @@ import { URISchema, } from '@docusaurus/utils-validation'; import {GlobExcludeDefault} from '@docusaurus/utils'; -import type {PluginOptions} from './types'; +import type {PluginOptions} from '@docusaurus/plugin-content-blog'; export const DEFAULT_OPTIONS: PluginOptions = { feedOptions: {type: ['rss', 'atom'], copyright: ''}, diff --git a/packages/docusaurus-plugin-content-blog/src/translations.ts b/packages/docusaurus-plugin-content-blog/src/translations.ts index f4b084c7ab..b77331c814 100644 --- a/packages/docusaurus-plugin-content-blog/src/translations.ts +++ b/packages/docusaurus-plugin-content-blog/src/translations.ts @@ -5,8 +5,9 @@ * LICENSE file in the root directory of this source tree. */ -import type {BlogContent, PluginOptions, BlogPaginated} from './types'; +import type {BlogContent, BlogPaginated} from './types'; import type {TranslationFileContent, TranslationFiles} from '@docusaurus/types'; +import type {PluginOptions} from '@docusaurus/plugin-content-blog'; function translateListPage( blogListPaginated: BlogPaginated[], diff --git a/packages/docusaurus-plugin-content-blog/src/types.ts b/packages/docusaurus-plugin-content-blog/src/types.ts index ff2dfba3c2..ed909f2b3c 100644 --- a/packages/docusaurus-plugin-content-blog/src/types.ts +++ b/packages/docusaurus-plugin-content-blog/src/types.ts @@ -5,14 +5,15 @@ * LICENSE file in the root directory of this source tree. */ -import type {RemarkAndRehypePluginOptions} from '@docusaurus/mdx-loader'; import type {Tag} from '@docusaurus/utils'; import type { BrokenMarkdownLink, ContentPaths, } from '@docusaurus/utils/lib/markdownLinks'; -import type {Overwrite} from 'utility-types'; -import type {BlogPostFrontMatter} from './blogFrontMatter'; +import type { + BlogPostFrontMatter, + Author, +} from '@docusaurus/plugin-content-blog'; export type BlogContentPaths = ContentPaths; @@ -24,87 +25,6 @@ export interface BlogContent { blogTagsListPath: string | null; } -export type FeedType = 'rss' | 'atom' | 'json'; - -export type FeedOptions = { - type?: FeedType[] | null; - title?: string; - description?: string; - copyright: string; - language?: string; -}; - -// Feed options, as provided by user config -export type UserFeedOptions = Overwrite< - Partial, - {type?: FeedOptions['type'] | 'all'} // Handle the type: "all" shortcut ->; - -export type EditUrlFunction = (editUrlParams: { - blogDirPath: string; - blogPath: string; - permalink: string; - locale: string; -}) => string | undefined; - -// Duplicate from ngryman/reading-time to keep stability of API -type ReadingTimeOptions = { - wordsPerMinute?: number; - wordBound?: (char: string) => boolean; -}; - -export type ReadingTimeFunction = (params: { - content: string; - frontMatter?: BlogPostFrontMatter & Record; - options?: ReadingTimeOptions; -}) => number; - -export type ReadingTimeFunctionOption = ( - params: Required[0], 'options'>> & { - defaultReadingTime: ReadingTimeFunction; - }, -) => number | undefined; - -export type PluginOptions = RemarkAndRehypePluginOptions & { - id?: string; - path: string; - routeBasePath: string; - tagsBasePath: string; - archiveBasePath: string; - include: string[]; - exclude: string[]; - postsPerPage: number | 'ALL'; - blogListComponent: string; - blogPostComponent: string; - blogTagsListComponent: string; - blogTagsPostsComponent: string; - blogTitle: string; - blogDescription: string; - blogSidebarCount: number | 'ALL'; - blogSidebarTitle: string; - truncateMarker: RegExp; - showReadingTime: boolean; - feedOptions: { - type?: FeedType[] | null; - title?: string; - description?: string; - copyright: string; - language?: string; - }; - editUrl?: string | EditUrlFunction; - editLocalizedFiles?: boolean; - admonitions: Record; - authorsMapPath: string; - readingTime: ReadingTimeFunctionOption; - sortPosts: 'ascending' | 'descending'; -}; - -// Options, as provided in the user config (before normalization) -export type UserPluginOptions = Overwrite< - Partial, - {feedOptions?: UserFeedOptions} ->; - export interface BlogTags { [key: string]: BlogTag; } @@ -138,14 +58,6 @@ export interface BlogPaginated { items: string[]; } -// We allow passing custom fields to authors, e.g., twitter -export interface Author extends Record { - name?: string; - imageURL?: string; - url?: string; - title?: string; -} - export interface MetaData { permalink: string; source: string; @@ -163,11 +75,6 @@ export interface MetaData { frontMatter: BlogPostFrontMatter & Record; } -export interface Assets { - image?: string; - authorsImageUrls: (string | undefined)[]; // Array of same size as the original MetaData.authors array -} - export interface Paginator { title: string; permalink: string; diff --git a/packages/docusaurus-plugin-content-docs/src/__tests__/cli.test.ts b/packages/docusaurus-plugin-content-docs/src/__tests__/cli.test.ts index da1baf4a2f..d7287128a2 100644 --- a/packages/docusaurus-plugin-content-docs/src/__tests__/cli.test.ts +++ b/packages/docusaurus-plugin-content-docs/src/__tests__/cli.test.ts @@ -7,7 +7,10 @@ import path from 'path'; import {cliDocsVersionCommand} from '../cli'; -import type {PathOptions, SidebarOptions} from '../types'; +import type { + PathOptions, + SidebarOptions, +} from '@docusaurus/plugin-content-docs'; import fs from 'fs-extra'; import { getVersionedDocsDirPath, 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 4615dd0954..1326aad3ab 100644 --- a/packages/docusaurus-plugin-content-docs/src/__tests__/docs.test.ts +++ b/packages/docusaurus-plugin-content-docs/src/__tests__/docs.test.ts @@ -19,12 +19,14 @@ import {readVersionsMetadata} from '../versions'; import type { DocFile, DocMetadataBase, - MetadataOptions, VersionMetadata, - PluginOptions, - EditUrlFunction, DocNavLink, } from '../types'; +import type { + MetadataOptions, + PluginOptions, + EditUrlFunction, +} from '@docusaurus/plugin-content-docs'; import type {LoadContext} from '@docusaurus/types'; import {DEFAULT_OPTIONS} from '../options'; import type {Optional} from 'utility-types'; 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 383e88eeb5..a4d94d4c36 100644 --- a/packages/docusaurus-plugin-content-docs/src/__tests__/options.test.ts +++ b/packages/docusaurus-plugin-content-docs/src/__tests__/options.test.ts @@ -13,7 +13,7 @@ import { DisabledNumberPrefixParser, } from '../numberPrefix'; import {GlobExcludeDefault} from '@docusaurus/utils'; -import type {PluginOptions} from '../types'; +import type {PluginOptions} from '@docusaurus/plugin-content-docs'; // the type of remark/rehype plugins is function const markdownPluginsFunctionStub = () => {}; diff --git a/packages/docusaurus-plugin-content-docs/src/__tests__/versions.test.ts b/packages/docusaurus-plugin-content-docs/src/__tests__/versions.test.ts index 9ab0d973b0..3ac367db68 100644 --- a/packages/docusaurus-plugin-content-docs/src/__tests__/versions.test.ts +++ b/packages/docusaurus-plugin-content-docs/src/__tests__/versions.test.ts @@ -14,8 +14,9 @@ import { } from '../versions'; import {DEFAULT_OPTIONS} from '../options'; import {DEFAULT_PLUGIN_ID} from '@docusaurus/utils'; -import type {PluginOptions, VersionMetadata} from '../types'; +import type {VersionMetadata} from '../types'; import type {I18n} from '@docusaurus/types'; +import type {PluginOptions} from '@docusaurus/plugin-content-docs'; const DefaultI18N: I18n = { currentLocale: 'en', diff --git a/packages/docusaurus-plugin-content-docs/src/cli.ts b/packages/docusaurus-plugin-content-docs/src/cli.ts index 3cc109b431..76045beef0 100644 --- a/packages/docusaurus-plugin-content-docs/src/cli.ts +++ b/packages/docusaurus-plugin-content-docs/src/cli.ts @@ -12,7 +12,10 @@ import { } from './versions'; import fs from 'fs-extra'; import path from 'path'; -import type {PathOptions, SidebarOptions} from './types'; +import type { + PathOptions, + SidebarOptions, +} from '@docusaurus/plugin-content-docs'; import {loadSidebarsFile, resolveSidebarPathOption} from './sidebars'; import {DEFAULT_PLUGIN_ID} from '@docusaurus/utils'; import logger from '@docusaurus/logger'; diff --git a/packages/docusaurus-plugin-content-docs/src/client/docsClientUtils.ts b/packages/docusaurus-plugin-content-docs/src/client/docsClientUtils.ts index d3a256a5b0..3bfadef48c 100644 --- a/packages/docusaurus-plugin-content-docs/src/client/docsClientUtils.ts +++ b/packages/docusaurus-plugin-content-docs/src/client/docsClientUtils.ts @@ -7,21 +7,18 @@ import {matchPath} from '@docusaurus/router'; -import type {GlobalPluginData, GlobalVersion, GlobalDoc} from '../types'; +import type { + GlobalPluginData, + GlobalVersion, + GlobalDoc, + GetActivePluginOptions, + ActivePlugin, + ActiveDocContext, + DocVersionSuggestions, +} from '@docusaurus/plugin-content-docs/client'; // This code is not part of the api surface, not in ./theme on purpose -// Short/convenient type aliases -type Version = GlobalVersion; -type Doc = GlobalDoc; - -export type ActivePlugin = { - pluginId: string; - pluginData: GlobalPluginData; -}; - -export type GetActivePluginOptions = {failfast?: boolean}; // use fail-fast option if you know for sure one plugin instance is active - // get the data of the plugin that is currently "active" // ie the docs of that plugin are currently browsed // it is useful to support multiple docs plugin instances @@ -56,13 +53,7 @@ export function getActivePlugin( return activePlugin; } -export type ActiveDocContext = { - activeVersion?: Version; - activeDoc?: Doc; - alternateDocVersions: Record; -}; - -export const getLatestVersion = (data: GlobalPluginData): Version => +export const getLatestVersion = (data: GlobalPluginData): GlobalVersion => data.versions.find((version) => version.isLast)!; // Note: return undefined on doc-unrelated pages, @@ -70,7 +61,7 @@ export const getLatestVersion = (data: GlobalPluginData): Version => export const getActiveVersion = ( data: GlobalPluginData, pathname: string, -): Version | undefined => { +): GlobalVersion | undefined => { const lastVersion = getLatestVersion(data); // Last version is a route like /docs/*, // we need to try to match it last or it would match /docs/version-1.0/* as well @@ -127,13 +118,6 @@ export const getActiveDocContext = ( }; }; -export type DocVersionSuggestions = { - // suggest the latest version - latestVersionSuggestion: GlobalVersion; - // suggest the same doc, in latest version (if exist) - latestDocSuggestion?: GlobalDoc; -}; - export const getDocVersionSuggestions = ( data: GlobalPluginData, pathname: string, diff --git a/packages/docusaurus-plugin-content-docs/src/client/globalDataHooks.ts b/packages/docusaurus-plugin-content-docs/src/client/globalDataHooks.ts index 5a1d5b8449..96a14ce909 100644 --- a/packages/docusaurus-plugin-content-docs/src/client/globalDataHooks.ts +++ b/packages/docusaurus-plugin-content-docs/src/client/globalDataHooks.ts @@ -11,18 +11,21 @@ import useGlobalData, { usePluginData, } from '@docusaurus/useGlobalData'; -import type {GlobalPluginData, GlobalVersion} from '../types'; import { getActivePlugin, getLatestVersion, getActiveVersion, getActiveDocContext, getDocVersionSuggestions, - type ActivePlugin, - type ActiveDocContext, - type DocVersionSuggestions, - type GetActivePluginOptions, } from './docsClientUtils'; +import type { + GlobalPluginData, + GlobalVersion, + ActivePlugin, + ActiveDocContext, + DocVersionSuggestions, + GetActivePluginOptions, +} from '@docusaurus/plugin-content-docs/client'; // Important to use a constant object to avoid React useEffect executions etc..., // see https://github.com/facebook/docusaurus/issues/5089 diff --git a/packages/docusaurus-plugin-content-docs/src/docs.ts b/packages/docusaurus-plugin-content-docs/src/docs.ts index 69851ae76c..3e225167a5 100644 --- a/packages/docusaurus-plugin-content-docs/src/docs.ts +++ b/packages/docusaurus-plugin-content-docs/src/docs.ts @@ -28,8 +28,6 @@ import type { DocMetadata, DocNavLink, LastUpdateData, - MetadataOptions, - PluginOptions, VersionMetadata, LoadedVersion, } from './types'; @@ -40,6 +38,10 @@ import {stripPathNumberPrefixes} from './numberPrefix'; import {validateDocFrontMatter} from './docFrontMatter'; import type {SidebarsUtils} from './sidebars/utils'; import {toDocNavigationLink, toNavigationLink} from './sidebars/utils'; +import type { + MetadataOptions, + PluginOptions, +} from '@docusaurus/plugin-content-docs'; type LastUpdateOptions = Pick< PluginOptions, diff --git a/packages/docusaurus-plugin-content-docs/src/globalData.ts b/packages/docusaurus-plugin-content-docs/src/globalData.ts index 6d95370134..a545c73e87 100644 --- a/packages/docusaurus-plugin-content-docs/src/globalData.ts +++ b/packages/docusaurus-plugin-content-docs/src/globalData.ts @@ -9,13 +9,12 @@ import {mapValues} from 'lodash'; import {normalizeUrl} from '@docusaurus/utils'; import type {Sidebars} from './sidebars/types'; import {createSidebarsUtils} from './sidebars/utils'; +import type {DocMetadata, LoadedVersion} from './types'; import type { - DocMetadata, - GlobalDoc, - LoadedVersion, GlobalVersion, GlobalSidebar, -} from './types'; + GlobalDoc, +} from '@docusaurus/plugin-content-docs/client'; export function toGlobalDataDoc(doc: DocMetadata): GlobalDoc { return { diff --git a/packages/docusaurus-plugin-content-docs/src/index.ts b/packages/docusaurus-plugin-content-docs/src/index.ts index 65c26c13ae..f15f0ca729 100644 --- a/packages/docusaurus-plugin-content-docs/src/index.ts +++ b/packages/docusaurus-plugin-content-docs/src/index.ts @@ -30,11 +30,9 @@ import { import {getDocsDirPaths, readVersionsMetadata} from './versions'; import type { - PluginOptions, LoadedContent, SourceToPermalink, DocMetadataBase, - GlobalPluginData, VersionMetadata, LoadedVersion, DocFile, @@ -54,7 +52,11 @@ import { import logger from '@docusaurus/logger'; import {getVersionTags} from './tags'; import {createVersionRoutes} from './routes'; -import type {PropTagsListPage} from '@docusaurus/plugin-content-docs'; +import type { + PropTagsListPage, + PluginOptions, +} from '@docusaurus/plugin-content-docs'; +import type {GlobalPluginData} from '@docusaurus/plugin-content-docs/client'; import {createSidebarsUtils} from './sidebars/utils'; import {getCategoryGeneratedIndexMetadataList} from './categoryGeneratedIndex'; diff --git a/packages/docusaurus-plugin-content-docs/src/numberPrefix.ts b/packages/docusaurus-plugin-content-docs/src/numberPrefix.ts index 994464d082..85933aa94c 100644 --- a/packages/docusaurus-plugin-content-docs/src/numberPrefix.ts +++ b/packages/docusaurus-plugin-content-docs/src/numberPrefix.ts @@ -5,7 +5,7 @@ * LICENSE file in the root directory of this source tree. */ -import type {NumberPrefixParser} from './types'; +import type {NumberPrefixParser} from '@docusaurus/plugin-content-docs'; // Best-effort to avoid parsing some patterns as number prefix const IgnoredPrefixPatterns = (function () { diff --git a/packages/docusaurus-plugin-content-docs/src/options.ts b/packages/docusaurus-plugin-content-docs/src/options.ts index 7dd8f4342b..f7b2f7ed47 100644 --- a/packages/docusaurus-plugin-content-docs/src/options.ts +++ b/packages/docusaurus-plugin-content-docs/src/options.ts @@ -5,7 +5,7 @@ * LICENSE file in the root directory of this source tree. */ -import type {PluginOptions} from './types'; +import type {PluginOptions} from '@docusaurus/plugin-content-docs'; import { Joi, RemarkPluginsSchema, 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 a656d29b78..130de3b2c9 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 @@ -6,15 +6,76 @@ */ declare module '@docusaurus/plugin-content-docs' { - export type Options = Partial; - export type SidebarsConfig = import('./sidebars/types').SidebarsConfig; - export type VersionBanner = import('./types').VersionBanner; - type GlobalDataVersion = import('./types').GlobalVersion; - type GlobalDataDoc = import('./types').GlobalDoc; - type GlobalDataSidebar = import('./types').GlobalSidebar; - type VersionTag = import('./types').VersionTag; + import type {RemarkAndRehypePluginOptions} from '@docusaurus/mdx-loader'; - export type {GlobalDataVersion, GlobalDataDoc, GlobalDataSidebar}; + export type NumberPrefixParser = (filename: string) => { + filename: string; + numberPrefix?: number; + }; + + export type EditUrlFunction = (editUrlParams: { + version: string; + versionDocsDirPath: string; + docPath: string; + permalink: string; + locale: string; + }) => string | undefined; + + export type MetadataOptions = { + routeBasePath: string; + editUrl?: string | EditUrlFunction; + editCurrentVersion: boolean; + editLocalizedFiles: boolean; + showLastUpdateTime?: boolean; + showLastUpdateAuthor?: boolean; + numberPrefixParser: NumberPrefixParser; + }; + + export type PathOptions = { + path: string; + sidebarPath?: string | false | undefined; + }; + + // TODO support custom version banner? {type: "error", content: "html content"} + export type VersionBanner = 'unreleased' | 'unmaintained'; + export type VersionOptions = { + path?: string; + label?: string; + banner?: 'none' | VersionBanner; + badge?: boolean; + className?: string; + }; + export type VersionsOptions = { + lastVersion?: string; + versions: Record; + onlyIncludeVersions?: string[]; + }; + export type SidebarOptions = { + sidebarCollapsible: boolean; + sidebarCollapsed: boolean; + }; + + export type PluginOptions = MetadataOptions & + PathOptions & + VersionsOptions & + RemarkAndRehypePluginOptions & + SidebarOptions & { + id: string; + include: string[]; + exclude: string[]; + docLayoutComponent: string; + docItemComponent: string; + docTagDocListComponent: string; + docTagsListComponent: string; + docCategoryGeneratedIndexComponent: string; + admonitions: Record; + disableVersioning: boolean; + includeCurrentVersion: boolean; + sidebarItemsGenerator: import('./sidebars/types').SidebarItemsGeneratorOption; + tagsBasePath: string; + }; + export type Options = Partial; + export type SidebarsConfig = import('./sidebars/types').SidebarsConfig; export type PropNavigationLink = { readonly title: string; @@ -241,18 +302,54 @@ declare module '@theme/Seo' { export default Seo; } -// TODO can't we infer types directly from code? +// TODO until TS supports exports field... hope it's in 4.6 declare module '@docusaurus/plugin-content-docs/client' { - type GlobalPluginData = import('./types').GlobalPluginData; - type GlobalVersion = import('./types').GlobalVersion; - type ActivePlugin = import('./client/docsClientUtils').ActivePlugin; - type ActiveDocContext = import('./client/docsClientUtils').ActiveDocContext; - type DocVersionSuggestions = - import('./client/docsClientUtils').DocVersionSuggestions; - type GetActivePluginOptions = - import('./client/docsClientUtils').GetActivePluginOptions; + export type ActivePlugin = { + pluginId: string; + pluginData: GlobalPluginData; + }; + export type ActiveDocContext = { + activeVersion?: GlobalVersion; + activeDoc?: GlobalDoc; + alternateDocVersions: Record; + }; + export type GlobalDoc = { + id: string; + path: string; + sidebar: string | undefined; + }; + + export type GlobalVersion = { + name: string; + label: string; + isLast: boolean; + path: string; + mainDocId: string; // home doc (if docs homepage configured), or first doc + docs: GlobalDoc[]; + sidebars?: Record; + }; + + export type GlobalSidebarLink = { + label: string; + path: string; + }; + + export type GlobalSidebar = { + link?: GlobalSidebarLink; + // ... we may add other things here later + }; + export type GlobalPluginData = { + path: string; + versions: GlobalVersion[]; + }; + export type DocVersionSuggestions = { + // suggest the latest version + latestVersionSuggestion: GlobalVersion; + // suggest the same doc, in latest version (if exist) + latestDocSuggestion?: GlobalDoc; + }; + export type GetActivePluginOptions = {failfast?: boolean}; // use fail-fast option if you know for sure one plugin instance is active - export type {GlobalPluginData, GlobalVersion}; export const useAllDocsData: () => Record; export const useDocsData: (pluginId?: string) => GlobalPluginData; export const useActivePlugin: ( diff --git a/packages/docusaurus-plugin-content-docs/src/sidebars/index.ts b/packages/docusaurus-plugin-content-docs/src/sidebars/index.ts index c96a3daf17..eae11f1949 100644 --- a/packages/docusaurus-plugin-content-docs/src/sidebars/index.ts +++ b/packages/docusaurus-plugin-content-docs/src/sidebars/index.ts @@ -8,12 +8,13 @@ import fs from 'fs-extra'; import importFresh from 'import-fresh'; import type {SidebarsConfig, Sidebars, NormalizedSidebars} from './types'; -import type {NormalizeSidebarsParams, PluginOptions} from '../types'; +import type {NormalizeSidebarsParams} from '../types'; import {validateSidebars} from './validation'; import {normalizeSidebars} from './normalization'; import {processSidebars, type SidebarProcessorParams} from './processor'; import path from 'path'; import {createSlugger} from '@docusaurus/utils'; +import type {PluginOptions} from '@docusaurus/plugin-content-docs'; export const DefaultSidebars: SidebarsConfig = { defaultSidebar: [ diff --git a/packages/docusaurus-plugin-content-docs/src/sidebars/normalization.ts b/packages/docusaurus-plugin-content-docs/src/sidebars/normalization.ts index 07f1d976b0..48666e8987 100644 --- a/packages/docusaurus-plugin-content-docs/src/sidebars/normalization.ts +++ b/packages/docusaurus-plugin-content-docs/src/sidebars/normalization.ts @@ -5,7 +5,7 @@ * LICENSE file in the root directory of this source tree. */ -import type {NormalizeSidebarsParams, SidebarOptions} from '../types'; +import type {NormalizeSidebarsParams} from '../types'; import type { NormalizedSidebarItem, NormalizedSidebar, @@ -21,6 +21,7 @@ import type { import {isCategoriesShorthand} from './utils'; import {mapValues} from 'lodash'; import {normalizeUrl} from '@docusaurus/utils'; +import type {SidebarOptions} from '@docusaurus/plugin-content-docs'; function normalizeCategoryLink( category: SidebarItemCategoryConfig, diff --git a/packages/docusaurus-plugin-content-docs/src/sidebars/processor.ts b/packages/docusaurus-plugin-content-docs/src/sidebars/processor.ts index 5805e2bff0..e1ec68fbc2 100644 --- a/packages/docusaurus-plugin-content-docs/src/sidebars/processor.ts +++ b/packages/docusaurus-plugin-content-docs/src/sidebars/processor.ts @@ -5,12 +5,7 @@ * LICENSE file in the root directory of this source tree. */ -import type { - NumberPrefixParser, - DocMetadataBase, - VersionMetadata, - SidebarOptions, -} from '../types'; +import type {DocMetadataBase, VersionMetadata} from '../types'; import type { Sidebars, Sidebar, @@ -31,6 +26,10 @@ import {mapValues, memoize, pick} from 'lodash'; import combinePromises from 'combine-promises'; import {normalizeItem} from './normalization'; import type {Slugger} from '@docusaurus/utils'; +import type { + NumberPrefixParser, + SidebarOptions, +} from '@docusaurus/plugin-content-docs'; export type SidebarProcessorParams = { sidebarItemsGenerator: SidebarItemsGeneratorOption; diff --git a/packages/docusaurus-plugin-content-docs/src/sidebars/types.ts b/packages/docusaurus-plugin-content-docs/src/sidebars/types.ts index 1e96f0c7e1..8d6c61ecf3 100644 --- a/packages/docusaurus-plugin-content-docs/src/sidebars/types.ts +++ b/packages/docusaurus-plugin-content-docs/src/sidebars/types.ts @@ -6,12 +6,11 @@ */ import type {Optional, Required} from 'utility-types'; +import type {DocMetadataBase, VersionMetadata} from '../types'; import type { - DocMetadataBase, - VersionMetadata, NumberPrefixParser, SidebarOptions, -} from '../types'; +} from '@docusaurus/plugin-content-docs'; // Makes all properties visible when hovering over the type type Expand> = {[P in keyof T]: T[P]}; diff --git a/packages/docusaurus-plugin-content-docs/src/slug.ts b/packages/docusaurus-plugin-content-docs/src/slug.ts index 1e79b605ec..bde63eb8ae 100644 --- a/packages/docusaurus-plugin-content-docs/src/slug.ts +++ b/packages/docusaurus-plugin-content-docs/src/slug.ts @@ -15,8 +15,9 @@ import { DefaultNumberPrefixParser, stripPathNumberPrefixes, } from './numberPrefix'; -import type {DocMetadataBase, NumberPrefixParser} from './types'; +import type {DocMetadataBase} from './types'; import {isConventionalDocIndex} from './docs'; +import type {NumberPrefixParser} from '@docusaurus/plugin-content-docs'; export default function getSlug({ baseID, diff --git a/packages/docusaurus-plugin-content-docs/src/types.ts b/packages/docusaurus-plugin-content-docs/src/types.ts index e908ef503d..ffa8ae4a09 100644 --- a/packages/docusaurus-plugin-content-docs/src/types.ts +++ b/packages/docusaurus-plugin-content-docs/src/types.ts @@ -7,13 +7,16 @@ /// -import type {RemarkAndRehypePluginOptions} from '@docusaurus/mdx-loader'; +import type {Sidebars} from './sidebars/types'; import type {Tag, FrontMatterTag, Slugger} from '@docusaurus/utils'; import type { BrokenMarkdownLink as IBrokenMarkdownLink, ContentPaths, } from '@docusaurus/utils/lib/markdownLinks'; -import type {SidebarItemsGeneratorOption, Sidebars} from './sidebars/types'; +import type { + VersionBanner, + SidebarOptions, +} from '@docusaurus/plugin-content-docs'; export type DocFile = { contentPath: string; // /!\ may be localized @@ -23,10 +26,8 @@ export type DocFile = { lastUpdate: LastUpdateData; }; -export type VersionName = string; - export type VersionMetadata = ContentPaths & { - versionName: VersionName; // 1.0.0 + versionName: string; // 1.0.0 versionLabel: string; // Version 1.0.0 versionPath: string; // /baseUrl/docs/1.0.0 tagsPath: string; @@ -40,76 +41,11 @@ export type VersionMetadata = ContentPaths & { routePriority: number | undefined; // -1 for the latest docs }; -export type EditUrlFunction = (editUrlParams: { - version: string; - versionDocsDirPath: string; - docPath: string; - permalink: string; - locale: string; -}) => string | undefined; - -export type MetadataOptions = { - routeBasePath: string; - editUrl?: string | EditUrlFunction; - editCurrentVersion: boolean; - editLocalizedFiles: boolean; - showLastUpdateTime?: boolean; - showLastUpdateAuthor?: boolean; - numberPrefixParser: NumberPrefixParser; -}; - -export type PathOptions = { - path: string; - sidebarPath?: string | false | undefined; -}; - -// TODO support custom version banner? {type: "error", content: "html content"} -export type VersionBanner = 'unreleased' | 'unmaintained'; - -export type VersionOptions = { - path?: string; - label?: string; - banner?: 'none' | VersionBanner; - badge?: boolean; - className?: string; -}; - -export type VersionsOptions = { - lastVersion?: string; - versions: Record; - onlyIncludeVersions?: string[]; -}; - -export type SidebarOptions = { - sidebarCollapsible: boolean; - sidebarCollapsed: boolean; -}; - export type NormalizeSidebarsParams = SidebarOptions & { version: VersionMetadata; categoryLabelSlugger: Slugger; }; -export type PluginOptions = MetadataOptions & - PathOptions & - VersionsOptions & - RemarkAndRehypePluginOptions & - SidebarOptions & { - id: string; - include: string[]; - exclude: string[]; - docLayoutComponent: string; - docItemComponent: string; - docTagDocListComponent: string; - docTagsListComponent: string; - docCategoryGeneratedIndexComponent: string; - admonitions: Record; - disableVersioning: boolean; - includeCurrentVersion: boolean; - sidebarItemsGenerator: SidebarItemsGeneratorOption; - tagsBasePath: string; - }; - export type LastUpdateData = { lastUpdatedAt?: number; formattedLastUpdatedAt?: string; @@ -142,7 +78,7 @@ export type DocFrontMatter = { export type DocMetadataBase = LastUpdateData & { id: string; // TODO legacy versioned id => try to remove unversionedId: string; // TODO new unversioned id => try to rename to "id" - version: VersionName; + version: string; title: string; description: string; source: string; // @site aliased source => "@site/docs/folder/subFolder/subSubFolder/myDoc.md" @@ -203,37 +139,6 @@ export type LoadedContent = { loadedVersions: LoadedVersion[]; }; -export type GlobalDoc = { - id: string; - path: string; - sidebar: string | undefined; -}; - -export type GlobalVersion = { - name: VersionName; - label: string; - isLast: boolean; - path: string; - mainDocId: string; // home doc (if docs homepage configured), or first doc - docs: GlobalDoc[]; - sidebars?: Record; -}; - -export type GlobalSidebarLink = { - label: string; - path: string; -}; - -export type GlobalSidebar = { - link?: GlobalSidebarLink; - // ... we may add other things here later -}; - -export type GlobalPluginData = { - path: string; - versions: GlobalVersion[]; -}; - export type BrokenMarkdownLink = IBrokenMarkdownLink; export type DocsMarkdownOption = { @@ -242,8 +147,3 @@ export type DocsMarkdownOption = { sourceToPermalink: SourceToPermalink; onBrokenMarkdownLink: (brokenMarkdownLink: BrokenMarkdownLink) => void; }; - -export type NumberPrefixParser = (filename: string) => { - filename: string; - numberPrefix?: number; -}; diff --git a/packages/docusaurus-plugin-content-docs/src/versions.ts b/packages/docusaurus-plugin-content-docs/src/versions.ts index 0cfa344058..7934a4e0b7 100644 --- a/packages/docusaurus-plugin-content-docs/src/versions.ts +++ b/packages/docusaurus-plugin-content-docs/src/versions.ts @@ -7,19 +7,19 @@ import path from 'path'; import fs from 'fs-extra'; -import type { - PluginOptions, - VersionBanner, - VersionMetadata, - VersionOptions, - VersionsOptions, -} from './types'; +import type {VersionMetadata} from './types'; import { VERSIONS_JSON_FILE, VERSIONED_DOCS_DIR, VERSIONED_SIDEBARS_DIR, CURRENT_VERSION_NAME, } from './constants'; +import type { + PluginOptions, + VersionBanner, + VersionOptions, + VersionsOptions, +} from '@docusaurus/plugin-content-docs'; import type {LoadContext} from '@docusaurus/types'; import { diff --git a/packages/docusaurus-plugin-content-pages/src/__tests__/pluginOptionSchema.test.ts b/packages/docusaurus-plugin-content-pages/src/__tests__/pluginOptionSchema.test.ts index 37028c1c8f..e6f7716ffb 100644 --- a/packages/docusaurus-plugin-content-pages/src/__tests__/pluginOptionSchema.test.ts +++ b/packages/docusaurus-plugin-content-pages/src/__tests__/pluginOptionSchema.test.ts @@ -6,7 +6,7 @@ */ import {PluginOptionSchema, DEFAULT_OPTIONS} from '../pluginOptionSchema'; -import type {PluginOptions} from '../types'; +import type {PluginOptions} from '@docusaurus/plugin-content-pages'; export default function normalizePluginOptions( options: Partial, diff --git a/packages/docusaurus-plugin-content-pages/src/index.ts b/packages/docusaurus-plugin-content-pages/src/index.ts index 9841fd79dc..caa99d00ff 100644 --- a/packages/docusaurus-plugin-content-pages/src/index.ts +++ b/packages/docusaurus-plugin-content-pages/src/index.ts @@ -31,12 +31,8 @@ import type {Configuration} from 'webpack'; import admonitions from 'remark-admonitions'; import {PluginOptionSchema} from './pluginOptionSchema'; -import type { - PluginOptions, - LoadedContent, - Metadata, - PagesContentPaths, -} from './types'; +import type {LoadedContent, Metadata, PagesContentPaths} from './types'; +import type {PluginOptions} from '@docusaurus/plugin-content-pages'; export function getContentPathList(contentPaths: PagesContentPaths): string[] { return [contentPaths.contentPathLocalized, contentPaths.contentPath]; diff --git a/packages/docusaurus-plugin-content-pages/src/plugin-content-pages.d.ts b/packages/docusaurus-plugin-content-pages/src/plugin-content-pages.d.ts index 0c04b3f4f6..47caf52b63 100644 --- a/packages/docusaurus-plugin-content-pages/src/plugin-content-pages.d.ts +++ b/packages/docusaurus-plugin-content-pages/src/plugin-content-pages.d.ts @@ -6,7 +6,19 @@ */ declare module '@docusaurus/plugin-content-pages' { - export type Options = Partial; + import type {RemarkAndRehypePluginOptions} from '@docusaurus/mdx-loader'; + + export type PluginOptions = RemarkAndRehypePluginOptions & { + id?: string; + path: string; + routeBasePath: string; + include: string[]; + exclude: string[]; + mdxPageComponent: string; + admonitions: Record; + }; + + export type Options = Partial; } declare module '@theme/MDXPage' { diff --git a/packages/docusaurus-plugin-content-pages/src/pluginOptionSchema.ts b/packages/docusaurus-plugin-content-pages/src/pluginOptionSchema.ts index 1df3b934b7..662916af10 100644 --- a/packages/docusaurus-plugin-content-pages/src/pluginOptionSchema.ts +++ b/packages/docusaurus-plugin-content-pages/src/pluginOptionSchema.ts @@ -5,7 +5,7 @@ * LICENSE file in the root directory of this source tree. */ -import type {PluginOptions} from './types'; +import type {PluginOptions} from '@docusaurus/plugin-content-pages'; import { Joi, RemarkPluginsSchema, diff --git a/packages/docusaurus-plugin-content-pages/src/types.ts b/packages/docusaurus-plugin-content-pages/src/types.ts index 7059cb13b6..70873ac56b 100644 --- a/packages/docusaurus-plugin-content-pages/src/types.ts +++ b/packages/docusaurus-plugin-content-pages/src/types.ts @@ -5,18 +5,6 @@ * LICENSE file in the root directory of this source tree. */ -import type {RemarkAndRehypePluginOptions} from '@docusaurus/mdx-loader'; - -export type PluginOptions = RemarkAndRehypePluginOptions & { - id?: string; - path: string; - routeBasePath: string; - include: string[]; - exclude: string[]; - mdxPageComponent: string; - admonitions: Record; -}; - export type JSXPageMetadata = { type: 'jsx'; permalink: string; diff --git a/packages/docusaurus-preset-classic/package.json b/packages/docusaurus-preset-classic/package.json index e7166543dd..8f582c5627 100644 --- a/packages/docusaurus-preset-classic/package.json +++ b/packages/docusaurus-preset-classic/package.json @@ -27,6 +27,7 @@ "@docusaurus/plugin-google-gtag": "2.0.0-beta.14", "@docusaurus/plugin-sitemap": "2.0.0-beta.14", "@docusaurus/theme-classic": "2.0.0-beta.14", + "@docusaurus/theme-common": "2.0.0-beta.14", "@docusaurus/theme-search-algolia": "2.0.0-beta.14" }, "peerDependencies": { diff --git a/packages/docusaurus-preset-classic/src/preset-classic.d.ts b/packages/docusaurus-preset-classic/src/preset-classic.d.ts index 84d71226fa..57fbfdbb5d 100644 --- a/packages/docusaurus-preset-classic/src/preset-classic.d.ts +++ b/packages/docusaurus-preset-classic/src/preset-classic.d.ts @@ -5,18 +5,28 @@ * LICENSE file in the root directory of this source tree. */ +import type {Options as DocsPluginOptions} from '@docusaurus/plugin-content-docs'; +import type {Options as BlogPluginOptions} from '@docusaurus/plugin-content-blog'; +import type {Options as PagesPluginOptions} from '@docusaurus/plugin-content-pages'; +import type {Options as SitemapPluginOptions} from '@docusaurus/plugin-sitemap'; +import type {Options as GAPluginOptions} from '@docusaurus/plugin-google-analytics'; +import type {Options as GtagPluginOptions} from '@docusaurus/plugin-google-gtag'; +import type {Options as ThemeOptions} from '@docusaurus/theme-classic'; +import type {ThemeConfig as BaseThemeConfig} from '@docusaurus/types'; +import type {UserThemeConfig as ClassicThemeConfig} from '@docusaurus/theme-common'; +import type {UserThemeConfig as AlgoliaThemeConfig} from '@docusaurus/theme-search-algolia'; + export type Options = { debug?: boolean; - docs?: false | import('@docusaurus/plugin-content-docs').Options; - blog?: false | import('@docusaurus/plugin-content-blog').Options; - pages?: false | import('@docusaurus/plugin-content-pages').Options; - sitemap?: false | import('@docusaurus/plugin-sitemap').Options; - theme?: import('@docusaurus/theme-classic').Options; - googleAnalytics?: import('@docusaurus/plugin-google-analytics').Options; - gtag?: import('@docusaurus/plugin-google-gtag').Options; + docs?: false | DocsPluginOptions; + blog?: false | BlogPluginOptions; + pages?: false | PagesPluginOptions; + sitemap?: false | SitemapPluginOptions; + theme?: ThemeOptions; + googleAnalytics?: GAPluginOptions; + gtag?: GtagPluginOptions; }; -export type ThemeConfig = import('@docusaurus/types').ThemeConfig & - import('@docusaurus/theme-common').UserThemeConfig & { - algolia?: unknown; // TODO type plugin - }; +export type ThemeConfig = BaseThemeConfig & + ClassicThemeConfig & + AlgoliaThemeConfig; diff --git a/packages/docusaurus-theme-classic/src/theme-classic.d.ts b/packages/docusaurus-theme-classic/src/theme-classic.d.ts index 553c04d696..7418d30c2e 100644 --- a/packages/docusaurus-theme-classic/src/theme-classic.d.ts +++ b/packages/docusaurus-theme-classic/src/theme-classic.d.ts @@ -44,7 +44,8 @@ declare module '@theme/BlogListPaginator' { } declare module '@theme/BlogPostItem' { - import type {FrontMatter, Assets, Metadata} from '@theme/BlogPostPage'; + import type {FrontMatter, Metadata} from '@theme/BlogPostPage'; + import type {Assets} from '@docusaurus/plugin-content-blog'; export interface Props { readonly frontMatter: FrontMatter; @@ -70,7 +71,8 @@ declare module '@theme/BlogPostAuthor' { } declare module '@theme/BlogPostAuthors' { - import type {Metadata, Assets} from '@theme/BlogPostPage'; + import type {Metadata} from '@theme/BlogPostPage'; + import type {Assets} from '@docusaurus/plugin-content-blog'; export interface Props { readonly authors: Metadata['authors']; diff --git a/packages/docusaurus-theme-classic/src/theme/NavbarItem/DocNavbarItem.tsx b/packages/docusaurus-theme-classic/src/theme/NavbarItem/DocNavbarItem.tsx index ab29113f13..8c56cebf24 100644 --- a/packages/docusaurus-theme-classic/src/theme/NavbarItem/DocNavbarItem.tsx +++ b/packages/docusaurus-theme-classic/src/theme/NavbarItem/DocNavbarItem.tsx @@ -15,9 +15,9 @@ import clsx from 'clsx'; import {getInfimaActiveClassName} from '@theme/NavbarItem/utils'; import type {Props} from '@theme/NavbarItem/DocNavbarItem'; import {useDocsPreferredVersion, uniq} from '@docusaurus/theme-common'; -import type {GlobalDataVersion} from '@docusaurus/plugin-content-docs'; +import type {GlobalVersion} from '@docusaurus/plugin-content-docs/client'; -function getDocInVersions(versions: GlobalDataVersion[], docId: string) { +function getDocInVersions(versions: GlobalVersion[], docId: string) { const allDocs = versions.flatMap((version) => version.docs); const doc = allDocs.find((versionDoc) => versionDoc.id === docId); if (!doc) { @@ -46,7 +46,7 @@ export default function DocNavbarItem({ const versions = uniq( [activeVersion, preferredVersion, latestVersion].filter( Boolean, - ) as GlobalDataVersion[], + ) as GlobalVersion[], ); const doc = getDocInVersions(versions, docId); const activeDocInfimaClassName = getInfimaActiveClassName(props.mobile); diff --git a/packages/docusaurus-theme-classic/src/theme/NavbarItem/DocSidebarNavbarItem.tsx b/packages/docusaurus-theme-classic/src/theme/NavbarItem/DocSidebarNavbarItem.tsx index a9dd13fbdd..ca6ec3d866 100644 --- a/packages/docusaurus-theme-classic/src/theme/NavbarItem/DocSidebarNavbarItem.tsx +++ b/packages/docusaurus-theme-classic/src/theme/NavbarItem/DocSidebarNavbarItem.tsx @@ -17,11 +17,11 @@ import {useDocsPreferredVersion, uniq} from '@docusaurus/theme-common'; import type {Props} from '@theme/NavbarItem/DocSidebarNavbarItem'; import type { - GlobalDataVersion, - GlobalDataSidebar, -} from '@docusaurus/plugin-content-docs'; + GlobalVersion, + GlobalSidebar, +} from '@docusaurus/plugin-content-docs/client'; -function getSidebarLink(versions: GlobalDataVersion[], sidebarId: string) { +function getSidebarLink(versions: GlobalVersion[], sidebarId: string) { const allSidebars = versions .flatMap((version) => { if (version.sidebars) { @@ -30,8 +30,7 @@ function getSidebarLink(versions: GlobalDataVersion[], sidebarId: string) { return undefined; }) .filter( - (sidebarItem): sidebarItem is [string, GlobalDataSidebar] => - !!sidebarItem, + (sidebarItem): sidebarItem is [string, GlobalSidebar] => !!sidebarItem, ); const sidebarEntry = allSidebars.find((sidebar) => sidebar[0] === sidebarId); if (!sidebarEntry) { @@ -65,7 +64,7 @@ export default function DocSidebarNavbarItem({ const versions = uniq( [activeVersion, preferredVersion, latestVersion].filter( Boolean, - ) as GlobalDataVersion[], + ) as GlobalVersion[], ); const sidebarLink = getSidebarLink(versions, sidebarId); const activeDocInfimaClassName = getInfimaActiveClassName(props.mobile); diff --git a/packages/docusaurus-theme-classic/src/theme/NavbarItem/DocsVersionDropdownNavbarItem.tsx b/packages/docusaurus-theme-classic/src/theme/NavbarItem/DocsVersionDropdownNavbarItem.tsx index 6291be80ec..642d34b535 100644 --- a/packages/docusaurus-theme-classic/src/theme/NavbarItem/DocsVersionDropdownNavbarItem.tsx +++ b/packages/docusaurus-theme-classic/src/theme/NavbarItem/DocsVersionDropdownNavbarItem.tsx @@ -16,9 +16,9 @@ import { import type {Props} from '@theme/NavbarItem/DocsVersionDropdownNavbarItem'; import {useDocsPreferredVersion} from '@docusaurus/theme-common'; import {translate} from '@docusaurus/Translate'; -import type {GlobalDataVersion} from '@docusaurus/plugin-content-docs'; +import type {GlobalVersion} from '@docusaurus/plugin-content-docs/client'; -const getVersionMainDoc = (version: GlobalDataVersion) => +const getVersionMainDoc = (version: GlobalVersion) => version.docs.find((doc) => doc.id === version.mainDocId)!; export default function DocsVersionDropdownNavbarItem({ diff --git a/packages/docusaurus-theme-search-algolia/package.json b/packages/docusaurus-theme-search-algolia/package.json index 8dc4b63406..ab5bb1065e 100644 --- a/packages/docusaurus-theme-search-algolia/package.json +++ b/packages/docusaurus-theme-search-algolia/package.json @@ -36,7 +36,8 @@ "clsx": "^1.1.1", "eta": "^1.12.3", "lodash": "^4.17.20", - "tslib": "^2.3.1" + "tslib": "^2.3.1", + "utility-types": "^3.10.0" }, "devDependencies": { "@docusaurus/module-type-aliases": "2.0.0-beta.14", diff --git a/packages/docusaurus-theme-search-algolia/src/theme-search-algolia.d.ts b/packages/docusaurus-theme-search-algolia/src/theme-search-algolia.d.ts index df7e0cb45d..77ee9c74c0 100644 --- a/packages/docusaurus-theme-search-algolia/src/theme-search-algolia.d.ts +++ b/packages/docusaurus-theme-search-algolia/src/theme-search-algolia.d.ts @@ -5,6 +5,22 @@ * LICENSE file in the root directory of this source tree. */ +declare module '@docusaurus/theme-search-algolia' { + import type {DeepPartial} from 'utility-types'; + + export type ThemeConfig = { + algolia: { + contextualSearch: boolean; + externalUrlRegex?: string; + appId: string; + apiKey: string; + indexName: string; + searchParameters: Record; + }; + }; + export type UserThemeConfig = DeepPartial; +} + declare module '@docusaurus/theme-search-algolia/client' { export function useAlgoliaContextualFacetFilters(): [string, string[]]; } @@ -14,17 +30,6 @@ declare module '@theme/SearchPage' { export default SearchPage; } -declare module '@theme/SearchMetadata' { - export type SearchMetadataProps = { - readonly locale?: string; - readonly version?: string; - readonly tag?: string; - }; - - const SearchMetadata: (props: SearchMetadataProps) => JSX.Element; - export default SearchMetadata; -} - declare module '@theme/SearchBar' { const SearchBar: () => JSX.Element; export default SearchBar; diff --git a/packages/docusaurus-theme-search-algolia/src/theme/SearchMetadata/index.tsx b/packages/docusaurus-theme-search-algolia/src/theme/SearchMetadata/index.tsx index 1984d7221f..2b36b2e1b0 100644 --- a/packages/docusaurus-theme-search-algolia/src/theme/SearchMetadata/index.tsx +++ b/packages/docusaurus-theme-search-algolia/src/theme/SearchMetadata/index.tsx @@ -8,14 +8,10 @@ import React from 'react'; import Head from '@docusaurus/Head'; -import type {SearchMetadataProps} from '@theme/SearchMetadata'; +import type {Props} from '@theme/SearchMetadata'; // Override default/agnostic SearchMetas to use Algolia-specific metadata -function SearchMetadata({ - locale, - version, - tag, -}: SearchMetadataProps): JSX.Element { +function SearchMetadata({locale, version, tag}: Props): JSX.Element { // Seems safe to consider here the locale is the language, // as the existing docsearch:language filter is afaik a regular string-based filter const language = locale;