Skip to content

Commit 2bcac29

Browse files
Josh-CenaJosh-Cena
authored
refactor(content-docs): deduplicate types, JSDoc for some APIs (facebook#7027)
* refactor(content-docs): deduplicate types, JSDoc for some APIs * little refactor
1 parent b842197 commit 2bcac29

38 files changed

Lines changed: 715 additions & 521 deletions

File tree

‎packages/docusaurus-mdx-loader/src/index.ts‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -21,21 +21,21 @@ import toc from './remark/toc';
2121
import unwrapMdxCodeBlocks from './remark/unwrapMdxCodeBlocks';
2222
import transformImage from './remark/transformImage';
2323
import transformLinks from './remark/transformLinks';
24-
import type {RemarkAndRehypePluginOptions} from '@docusaurus/mdx-loader';
24+
import type {MDXOptions} from '@docusaurus/mdx-loader';
2525
import type {LoaderContext} from 'webpack';
2626

2727
const {
2828
loaders: {inlineMarkdownImageFileLoader},
2929
} = getFileLoaderUtils();
3030

31-
const DEFAULT_OPTIONS: RemarkAndRehypePluginOptions = {
31+
const DEFAULT_OPTIONS: MDXOptions = {
3232
rehypePlugins: [],
3333
remarkPlugins: [unwrapMdxCodeBlocks, emoji, headings, toc],
3434
beforeDefaultRemarkPlugins: [],
3535
beforeDefaultRehypePlugins: [],
3636
};
3737

38-
type Options = RemarkAndRehypePluginOptions & {
38+
type Options = MDXOptions & {
3939
staticDirs: string[];
4040
siteDir: string;
4141
isMDXPartial?: (filePath: string) => boolean;

‎packages/docusaurus-mdx-loader/src/mdx-loader.d.ts‎

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -7,12 +7,12 @@
77

88
import type {Plugin} from 'unified';
99

10-
export type RemarkOrRehypePlugin =
10+
export type MDXPlugin =
1111
// eslint-disable-next-line @typescript-eslint/no-explicit-any
1212
[Plugin<any[]>, any] | Plugin<any[]>;
13-
export type RemarkAndRehypePluginOptions = {
14-
remarkPlugins: RemarkOrRehypePlugin[];
15-
rehypePlugins: RemarkOrRehypePlugin[];
16-
beforeDefaultRemarkPlugins: RemarkOrRehypePlugin[];
17-
beforeDefaultRehypePlugins: RemarkOrRehypePlugin[];
13+
export type MDXOptions = {
14+
remarkPlugins: MDXPlugin[];
15+
rehypePlugins: MDXPlugin[];
16+
beforeDefaultRemarkPlugins: MDXPlugin[];
17+
beforeDefaultRehypePlugins: MDXPlugin[];
1818
};

‎packages/docusaurus-plugin-content-blog/src/plugin-content-blog.d.ts‎

Lines changed: 18 additions & 45 deletions
Original file line numberDiff line numberDiff line change
@@ -6,8 +6,8 @@
66
*/
77

88
declare module '@docusaurus/plugin-content-blog' {
9-
import type {RemarkAndRehypePluginOptions} from '@docusaurus/mdx-loader';
10-
import type {FrontMatterTag} from '@docusaurus/utils';
9+
import type {MDXOptions} from '@docusaurus/mdx-loader';
10+
import type {FrontMatterTag, Tag} from '@docusaurus/utils';
1111
import type {Overwrite} from 'utility-types';
1212

1313
export interface Assets {
@@ -81,10 +81,7 @@ declare module '@docusaurus/plugin-content-blog' {
8181
* @see {@link BlogPostMetadata.tags}
8282
*/
8383
tags?: FrontMatterTag[];
84-
/**
85-
* Custom slug appended after /<baseUrl>/<routeBasePath>/
86-
* @see {@link BlogPostMetadata.slug}
87-
*/
84+
/** Custom slug appended after `/<baseUrl>/<routeBasePath>/` */
8885
slug?: string;
8986
/**
9087
* Marks the post as draft and excludes it from the production build.
@@ -130,25 +127,18 @@ declare module '@docusaurus/plugin-content-blog' {
130127
/** @deprecated v1 legacy */
131128
authorImageURL?: string;
132129

133-
/**
134-
* @see {@link BlogPostMetadata.image}
135-
*/
130+
/** Used in the head meta. Should use `assets.image` in priority. */
136131
image?: string;
137-
/**
138-
* Used in the head meta
139-
*/
132+
/** Used in the head meta. */
140133
keywords?: string[];
141-
/**
142-
* Hide the right TOC
143-
*/
134+
/** Hide the right TOC. */
144135
hide_table_of_contents?: boolean;
145136
/**
146-
* Minimum TOC heading level
137+
* Minimum TOC heading level. Must be between 2 and 6 and lower or equal to
138+
* the max value.
147139
*/
148140
toc_min_heading_level?: number;
149-
/**
150-
* Maximum TOC heading level
151-
*/
141+
/** Maximum TOC heading level. Must be between 2 and 6. */
152142
toc_max_heading_level?: number;
153143
};
154144

@@ -175,9 +165,7 @@ declare module '@docusaurus/plugin-content-blog' {
175165
| (string | BlogPostFrontMatterAuthor)[];
176166

177167
export type BlogPostMetadata = {
178-
/**
179-
* Path to the Markdown source, with `@site` alias.
180-
*/
168+
/** Path to the Markdown source, with `@site` alias. */
181169
readonly source: string;
182170
/**
183171
* Used to generate the page h1 heading, tab title, and pagination title.
@@ -193,9 +181,7 @@ declare module '@docusaurus/plugin-content-blog' {
193181
* render the date regardless of the existence of `Intl.DateTimeFormat`.
194182
*/
195183
readonly formattedDate: string;
196-
/**
197-
* Full link including base URL.
198-
*/
184+
/** Full link including base URL. */
199185
readonly permalink: string;
200186
/**
201187
* Description used in the meta. Could be an empty string (empty content)
@@ -229,17 +215,10 @@ declare module '@docusaurus/plugin-content-blog' {
229215
* `assets.authorsImageUrls` on client side.
230216
*/
231217
readonly authors: Author[];
232-
/**
233-
* Front matter, as-is.
234-
*/
218+
/** Front matter, as-is. */
235219
readonly frontMatter: BlogPostFrontMatter & {[key: string]: unknown};
236-
/**
237-
* Tags, normalized.
238-
*/
239-
readonly tags: readonly {
240-
readonly label: string;
241-
readonly permalink: string;
242-
}[];
220+
/** Tags, normalized. */
221+
readonly tags: Tag[];
243222
};
244223
/**
245224
* @returns The edit URL that's directly plugged into metadata.
@@ -250,17 +229,11 @@ declare module '@docusaurus/plugin-content-blog' {
250229
* site path. Usually the same as `options.path` but can be localized
251230
*/
252231
blogDirPath: string;
253-
/**
254-
* Path to this post file, relative to `blogDirPath`
255-
*/
232+
/** Path to this post file, relative to `blogDirPath`. */
256233
blogPath: string;
257-
/**
258-
* @see {@link BlogPostMetadata.permalink}
259-
*/
234+
/** @see {@link BlogPostMetadata.permalink} */
260235
permalink: string;
261-
/**
262-
* Locale name.
263-
*/
236+
/** Locale name. */
264237
locale: string;
265238
}) => string | undefined;
266239

@@ -325,7 +298,7 @@ declare module '@docusaurus/plugin-content-blog' {
325298
/**
326299
* Plugin options after normalization.
327300
*/
328-
export type PluginOptions = RemarkAndRehypePluginOptions & {
301+
export type PluginOptions = MDXOptions & {
329302
/** Plugin ID. */
330303
id?: string;
331304
/**

‎packages/docusaurus-plugin-content-docs/src/__tests__/__snapshots__/translations.test.ts.snap‎

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -169,7 +169,9 @@ exports[`translateLoadedContent returns translated loaded content 1`] = `
169169
},
170170
],
171171
"isLast": true,
172+
"label": "current label (translated)",
172173
"mainDocId": "",
174+
"path": "/docs/",
173175
"routePriority": undefined,
174176
"sidebarFilePath": "any",
175177
"sidebars": {
@@ -221,9 +223,7 @@ exports[`translateLoadedContent returns translated loaded content 1`] = `
221223
},
222224
],
223225
},
224-
"versionLabel": "current label (translated)",
225226
"versionName": "current",
226-
"versionPath": "/docs/",
227227
},
228228
{
229229
"contentPath": "any",
@@ -311,7 +311,9 @@ exports[`translateLoadedContent returns translated loaded content 1`] = `
311311
},
312312
],
313313
"isLast": true,
314+
"label": "2.0.0 label (translated)",
314315
"mainDocId": "",
316+
"path": "/docs/",
315317
"routePriority": undefined,
316318
"sidebarFilePath": "any",
317319
"sidebars": {
@@ -363,9 +365,7 @@ exports[`translateLoadedContent returns translated loaded content 1`] = `
363365
},
364366
],
365367
},
366-
"versionLabel": "2.0.0 label (translated)",
367368
"versionName": "2.0.0",
368-
"versionPath": "/docs/",
369369
},
370370
{
371371
"contentPath": "any",
@@ -453,7 +453,9 @@ exports[`translateLoadedContent returns translated loaded content 1`] = `
453453
},
454454
],
455455
"isLast": true,
456+
"label": "1.0.0 label (translated)",
456457
"mainDocId": "",
458+
"path": "/docs/",
457459
"routePriority": undefined,
458460
"sidebarFilePath": "any",
459461
"sidebars": {
@@ -505,9 +507,7 @@ exports[`translateLoadedContent returns translated loaded content 1`] = `
505507
},
506508
],
507509
},
508-
"versionLabel": "1.0.0 label (translated)",
509510
"versionName": "1.0.0",
510-
"versionPath": "/docs/",
511511
},
512512
],
513513
}

‎packages/docusaurus-plugin-content-docs/src/__tests__/docs.test.ts‎

Lines changed: 9 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -18,16 +18,14 @@ import {
1818
import {loadSidebars} from '../sidebars';
1919
import type {Sidebars} from '../sidebars/types';
2020
import {readVersionsMetadata} from '../versions';
21-
import type {
22-
DocFile,
23-
DocMetadataBase,
24-
VersionMetadata,
25-
DocNavLink,
26-
} from '../types';
21+
import type {DocFile} from '../types';
2722
import type {
2823
MetadataOptions,
2924
PluginOptions,
3025
EditUrlFunction,
26+
DocMetadataBase,
27+
VersionMetadata,
28+
PropNavigationLink,
3129
} from '@docusaurus/plugin-content-docs';
3230
import type {LoadContext} from '@docusaurus/types';
3331
import {DEFAULT_OPTIONS} from '../options';
@@ -123,7 +121,11 @@ function createTestUtils({
123121
}
124122

125123
async function generateNavigation(docFiles: DocFile[]): Promise<{
126-
pagination: {prev?: DocNavLink; next?: DocNavLink; id: string}[];
124+
pagination: {
125+
prev?: PropNavigationLink;
126+
next?: PropNavigationLink;
127+
id: string;
128+
}[];
127129
sidebars: Sidebars;
128130
}> {
129131
const rawDocs = docFiles.map((docFile) =>

‎packages/docusaurus-plugin-content-docs/src/__tests__/frontMatter.test.ts‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,7 @@
66
*/
77

88
import {validateDocFrontMatter} from '../frontMatter';
9-
import type {DocFrontMatter} from '../types';
9+
import type {DocFrontMatter} from '@docusaurus/plugin-content-docs';
1010
import escapeStringRegexp from 'escape-string-regexp';
1111

1212
function testField(params: {

‎packages/docusaurus-plugin-content-docs/src/__tests__/globalData.test.ts‎

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -12,9 +12,9 @@ describe('toGlobalDataVersion', () => {
1212
expect(
1313
toGlobalDataVersion({
1414
versionName: 'current',
15-
versionLabel: 'Label',
15+
label: 'Label',
1616
isLast: true,
17-
versionPath: '/current',
17+
path: '/current',
1818
mainDocId: 'main',
1919
docs: [
2020
{
@@ -86,9 +86,9 @@ describe('toGlobalDataVersion', () => {
8686
sidebar: 'tutorial',
8787
},
8888
],
89-
versionBanner: 'unreleased',
90-
versionBadge: true,
91-
versionClassName: 'current-cls',
89+
banner: 'unreleased',
90+
badge: true,
91+
className: 'current-cls',
9292
tagsPath: '/current/tags',
9393
contentPath: '',
9494
contentPathLocalized: '',

‎packages/docusaurus-plugin-content-docs/src/__tests__/props.test.ts‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -16,7 +16,7 @@ describe('toTagDocListProp', () => {
1616

1717
it('works', () => {
1818
const tag: Tag = {
19-
name: 'tag1',
19+
label: 'tag1',
2020
permalink: '/tag1',
2121
docIds: ['id1', 'id3'],
2222
};
@@ -54,7 +54,7 @@ describe('toTagDocListProp', () => {
5454

5555
expect(result).toEqual({
5656
allTagsPath,
57-
name: tag.name,
57+
name: tag.label,
5858
permalink: tag.permalink,
5959
docs: [doc3, doc1], // docs sorted by title, ignore "id5" absence
6060
});

‎packages/docusaurus-plugin-content-docs/src/__tests__/translations.test.ts‎

Lines changed: 9 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -5,12 +5,13 @@
55
* LICENSE file in the root directory of this source tree.
66
*/
77

8-
import type {LoadedContent, DocMetadata, LoadedVersion} from '../types';
8+
import type {LoadedContent, LoadedVersion} from '../types';
99
import {CURRENT_VERSION_NAME} from '../constants';
1010
import {
1111
getLoadedContentTranslationFiles,
1212
translateLoadedContent,
1313
} from '../translations';
14+
import type {DocMetadata} from '@docusaurus/plugin-content-docs';
1415
import {updateTranslationFileMessages} from '@docusaurus/utils';
1516

1617
function createSampleDoc(doc: Pick<DocMetadata, 'id'>): DocMetadata {
@@ -36,30 +37,20 @@ function createSampleVersion(
3637
version: Pick<LoadedVersion, 'versionName'>,
3738
): LoadedVersion {
3839
return {
39-
versionLabel: `${version.versionName} label`,
40-
versionPath: '/docs/',
40+
label: `${version.versionName} label`,
41+
path: '/docs/',
4142
mainDocId: '',
4243
routePriority: undefined,
4344
sidebarFilePath: 'any',
4445
isLast: true,
4546
contentPath: 'any',
4647
contentPathLocalized: 'any',
4748
docs: [
48-
createSampleDoc({
49-
id: 'doc1',
50-
}),
51-
createSampleDoc({
52-
id: 'doc2',
53-
}),
54-
createSampleDoc({
55-
id: 'doc3',
56-
}),
57-
createSampleDoc({
58-
id: 'doc4',
59-
}),
60-
createSampleDoc({
61-
id: 'doc5',
62-
}),
49+
createSampleDoc({id: 'doc1'}),
50+
createSampleDoc({id: 'doc2'}),
51+
createSampleDoc({id: 'doc3'}),
52+
createSampleDoc({id: 'doc4'}),
53+
createSampleDoc({id: 'doc5'}),
6354
],
6455
sidebars: {
6556
docs: [

0 commit comments

Comments
 (0)