From 1591128cdd0e1741e6f3b1b559859137a51c24cb Mon Sep 17 00:00:00 2001 From: Endi Date: Mon, 7 Oct 2019 18:28:33 +0700 Subject: [PATCH] refactor(v2): add typing for docs plugin (#1811) * refactor(v2): add typing for docs plugin * nits --- .eslintignore | 1 + .gitignore | 1 + .prettierignore | 1 + jest.config.js | 1 + package.json | 1 + .../package.json | 10 +- ...ars.test.js.snap => sidebars.test.ts.snap} | 0 .../{index.test.js => index.test.ts} | 19 ++-- .../{metadata.test.js => metadata.test.ts} | 0 .../{order.test.js => order.test.ts} | 0 .../{sidebars.test.js => sidebars.test.ts} | 0 .../src/{index.js => index.ts} | 67 ++++++----- .../src/markdown/{index.js => index.ts} | 17 +-- .../src/{metadata.js => metadata.ts} | 28 ++--- .../src/{order.js => order.ts} | 40 +++++-- .../src/{sidebars.js => sidebars.ts} | 94 ++++++++-------- .../src/types.ts | 105 ++++++++++++++++++ .../tsconfig.json | 9 ++ packages/docusaurus-types/src/index.d.ts | 8 +- packages/docusaurus/package.json | 2 +- packages/docusaurus/src/commands/swizzle.ts | 2 +- packages/docusaurus/src/server/config.ts | 7 +- .../docusaurus/src/server/plugins/index.ts | 2 +- .../docusaurus/src/server/presets/index.ts | 4 +- yarn.lock | 16 ++- 25 files changed, 304 insertions(+), 131 deletions(-) rename packages/docusaurus-plugin-content-docs-legacy/src/__tests__/__snapshots__/{sidebars.test.js.snap => sidebars.test.ts.snap} (100%) rename packages/docusaurus-plugin-content-docs-legacy/src/__tests__/{index.test.js => index.test.ts} (85%) rename packages/docusaurus-plugin-content-docs-legacy/src/__tests__/{metadata.test.js => metadata.test.ts} (100%) rename packages/docusaurus-plugin-content-docs-legacy/src/__tests__/{order.test.js => order.test.ts} (100%) rename packages/docusaurus-plugin-content-docs-legacy/src/__tests__/{sidebars.test.js => sidebars.test.ts} (100%) rename packages/docusaurus-plugin-content-docs-legacy/src/{index.js => index.ts} (78%) rename packages/docusaurus-plugin-content-docs-legacy/src/markdown/{index.js => index.ts} (85%) rename packages/docusaurus-plugin-content-docs-legacy/src/{metadata.js => metadata.ts} (81%) rename packages/docusaurus-plugin-content-docs-legacy/src/{order.js => order.ts} (62%) rename packages/docusaurus-plugin-content-docs-legacy/src/{sidebars.js => sidebars.ts} (52%) create mode 100644 packages/docusaurus-plugin-content-docs-legacy/src/types.ts create mode 100644 packages/docusaurus-plugin-content-docs-legacy/tsconfig.json diff --git a/.eslintignore b/.eslintignore index a39dad65d3..a865cb8a8d 100644 --- a/.eslintignore +++ b/.eslintignore @@ -14,3 +14,4 @@ packages/docusaurus-utils/lib/ packages/docusaurus/lib/ packages/docusaurus-init/lib/ packages/docusaurus-plugin-content-blog/lib/ +packages/docusaurus-plugin-content-docs-legacy/lib/ diff --git a/.gitignore b/.gitignore index 150e586567..a73afd9dbd 100644 --- a/.gitignore +++ b/.gitignore @@ -16,3 +16,4 @@ packages/docusaurus-utils/lib/ packages/docusaurus/lib/ packages/docusaurus-init/lib/ packages/docusaurus-plugin-content-blog/lib/ +packages/docusaurus-plugin-content-docs-legacy/lib/ diff --git a/.prettierignore b/.prettierignore index 1277f781cf..6955bdf14d 100644 --- a/.prettierignore +++ b/.prettierignore @@ -6,3 +6,4 @@ packages/docusaurus-utils/lib/ packages/docusaurus/lib/ packages/docusaurus-init/lib/ packages/docusaurus-plugin-content-blog/lib/ +packages/docusaurus-plugin-content-docs-legacy/lib/ diff --git a/jest.config.js b/jest.config.js index e6a11db381..39d87d3eef 100644 --- a/jest.config.js +++ b/jest.config.js @@ -18,6 +18,7 @@ module.exports = { '/packages/docusaurus/lib', '/packages/docusaurus-utils/lib', '/packages/docusaurus-plugin-content-blog/lib', + '/packages/docusaurus-plugin-content-docs-legacy/lib', ], transform: { '^.+\\.[jt]sx?$': 'babel-jest', diff --git a/package.json b/package.json index 48ceec36d3..e7353261f0 100644 --- a/package.json +++ b/package.json @@ -28,6 +28,7 @@ "@types/fs-extra": "8.0.0", "@types/inquirer": "^6.0.3", "@types/jest": "^24.0.15", + "@types/loader-utils": "^1.1.3", "@types/lodash": "^4.14.136", "@types/lodash.kebabcase": "^4.1.6", "@types/node": "^12.0.2", diff --git a/packages/docusaurus-plugin-content-docs-legacy/package.json b/packages/docusaurus-plugin-content-docs-legacy/package.json index c4d483ba15..a83ead3970 100644 --- a/packages/docusaurus-plugin-content-docs-legacy/package.json +++ b/packages/docusaurus-plugin-content-docs-legacy/package.json @@ -2,17 +2,23 @@ "name": "@docusaurus/plugin-content-docs-legacy", "version": "2.0.0-alpha.25", "description": "Documentation plugin for legacy v1 Docusaurus docs", - "main": "src/index.js", + "main": "lib/index.js", + "scripts": { + "tsc": "tsc" + }, "publishConfig": { "access": "public" }, "license": "MIT", + "devDependencies": { + "@docusaurus/types": "^2.0.0-alpha.25" + }, "dependencies": { "@docusaurus/mdx-loader": "^2.0.0-alpha.25", "@docusaurus/utils": "^2.0.0-alpha.25", "fs-extra": "^8.1.0", "globby": "^10.0.1", - "import-fresh": "^3.0.0", + "import-fresh": "^3.1.0", "loader-utils": "^1.2.3" }, "peerDependencies": { diff --git a/packages/docusaurus-plugin-content-docs-legacy/src/__tests__/__snapshots__/sidebars.test.js.snap b/packages/docusaurus-plugin-content-docs-legacy/src/__tests__/__snapshots__/sidebars.test.ts.snap similarity index 100% rename from packages/docusaurus-plugin-content-docs-legacy/src/__tests__/__snapshots__/sidebars.test.js.snap rename to packages/docusaurus-plugin-content-docs-legacy/src/__tests__/__snapshots__/sidebars.test.ts.snap diff --git a/packages/docusaurus-plugin-content-docs-legacy/src/__tests__/index.test.js b/packages/docusaurus-plugin-content-docs-legacy/src/__tests__/index.test.ts similarity index 85% rename from packages/docusaurus-plugin-content-docs-legacy/src/__tests__/index.test.js rename to packages/docusaurus-plugin-content-docs-legacy/src/__tests__/index.test.ts index cb434acd25..b6ab9419ca 100644 --- a/packages/docusaurus-plugin-content-docs-legacy/src/__tests__/index.test.js +++ b/packages/docusaurus-plugin-content-docs-legacy/src/__tests__/index.test.ts @@ -7,6 +7,7 @@ import path from 'path'; import pluginContentDocs from '../index'; +import {LoadContext} from '@docusaurus/types'; describe('loadDocs', () => { test('simple website', async () => { @@ -16,18 +17,16 @@ describe('loadDocs', () => { baseUrl: '/', url: 'https://docusaurus.io', }; + const context = { + siteDir, + siteConfig, + } as LoadContext; const sidebarPath = path.join(siteDir, 'sidebars.json'); const pluginPath = 'docs'; - const plugin = pluginContentDocs( - { - siteDir, - siteConfig, - }, - { - path: 'docs', - sidebarPath, - }, - ); + const plugin = pluginContentDocs(context, { + path: 'docs', + sidebarPath, + }); const {docs: docsMetadata} = await plugin.loadContent(); expect(docsMetadata.hello).toEqual({ diff --git a/packages/docusaurus-plugin-content-docs-legacy/src/__tests__/metadata.test.js b/packages/docusaurus-plugin-content-docs-legacy/src/__tests__/metadata.test.ts similarity index 100% rename from packages/docusaurus-plugin-content-docs-legacy/src/__tests__/metadata.test.js rename to packages/docusaurus-plugin-content-docs-legacy/src/__tests__/metadata.test.ts diff --git a/packages/docusaurus-plugin-content-docs-legacy/src/__tests__/order.test.js b/packages/docusaurus-plugin-content-docs-legacy/src/__tests__/order.test.ts similarity index 100% rename from packages/docusaurus-plugin-content-docs-legacy/src/__tests__/order.test.js rename to packages/docusaurus-plugin-content-docs-legacy/src/__tests__/order.test.ts diff --git a/packages/docusaurus-plugin-content-docs-legacy/src/__tests__/sidebars.test.js b/packages/docusaurus-plugin-content-docs-legacy/src/__tests__/sidebars.test.ts similarity index 100% rename from packages/docusaurus-plugin-content-docs-legacy/src/__tests__/sidebars.test.js rename to packages/docusaurus-plugin-content-docs-legacy/src/__tests__/sidebars.test.ts diff --git a/packages/docusaurus-plugin-content-docs-legacy/src/index.js b/packages/docusaurus-plugin-content-docs-legacy/src/index.ts similarity index 78% rename from packages/docusaurus-plugin-content-docs-legacy/src/index.js rename to packages/docusaurus-plugin-content-docs-legacy/src/index.ts index 7298e9df4f..d42b436d7d 100644 --- a/packages/docusaurus-plugin-content-docs-legacy/src/index.js +++ b/packages/docusaurus-plugin-content-docs-legacy/src/index.ts @@ -5,38 +5,49 @@ * LICENSE file in the root directory of this source tree. */ -const globby = require('globby'); -const fs = require('fs'); -const path = require('path'); -const {idx, normalizeUrl, docuHash} = require('@docusaurus/utils'); +import globby from 'globby'; +import fs from 'fs-extra'; +import path from 'path'; +import {idx, normalizeUrl, docuHash} from '@docusaurus/utils'; -const createOrder = require('./order'); -const loadSidebars = require('./sidebars'); -const processMetadata = require('./metadata'); +import createOrder from './order'; +import loadSidebars from './sidebars'; +import processMetadata from './metadata'; +import {LoadContext, Plugin, DocusaurusConfig} from '@docusaurus/types'; +import { + PluginOptions, + Sidebar, + Order, + Metadata, + DocsMetadata, + LoadedContent, + SourceToPermalink, + PermalinkToId, +} from './types'; +import {Configuration} from 'webpack'; -const DEFAULT_OPTIONS = { +const DEFAULT_OPTIONS: PluginOptions = { path: 'docs', // Path to data on filesystem, relative to site dir. routeBasePath: 'docs', // URL Route. include: ['**/*.md', '**/*.mdx'], // Extensions to include. - // TODO: Change format to array. sidebarPath: '', // Path to sidebar configuration for showing a list of markdown pages. - // TODO: Settle themeing. docLayoutComponent: '@theme/DocLegacyPage', docItemComponent: '@theme/DocLegacyItem', remarkPlugins: [], rehypePlugins: [], }; -module.exports = function(context, opts) { +export default function pluginContentDocs( + context: LoadContext, + opts: Partial, +): Plugin { const options = {...DEFAULT_OPTIONS, ...opts}; const contentPath = path.resolve(context.siteDir, options.path); - let globalContents = {}; + let sourceToPermalink: SourceToPermalink = {}; return { name: 'docusaurus-plugin-content-docs', - contentPath, - getPathsToWatch() { const {include = []} = options; const globPattern = include.map(pattern => `${contentPath}/${pattern}`); @@ -53,13 +64,13 @@ module.exports = function(context, opts) { return null; } - const docsSidebars = loadSidebars(sidebarPath); + const docsSidebars: Sidebar = loadSidebars(sidebarPath); // Build the docs ordering such as next, previous, category and sidebar - const order = createOrder(docsSidebars); + const order: Order = createOrder(docsSidebars); // Prepare metadata container. - const docs = {}; + const docs: DocsMetadata = {}; // Metadata for default docs files. const docsFiles = await globby(include, { @@ -67,7 +78,7 @@ module.exports = function(context, opts) { }); await Promise.all( docsFiles.map(async source => { - const metadata = await processMetadata( + const metadata: Metadata = await processMetadata( source, docsDir, order, @@ -93,22 +104,19 @@ module.exports = function(context, opts) { } }); - const sourceToPermalink = {}; - const permalinkToId = {}; + const permalinkToId: PermalinkToId = {}; Object.values(docs).forEach(({id, source, permalink}) => { sourceToPermalink[source] = permalink; permalinkToId[permalink] = id; }); - globalContents = { + return { docs, docsDir, docsSidebars, sourceToPermalink, permalinkToId, }; - - return globalContents; }, async contentLoaded({content, actions}) { @@ -138,7 +146,7 @@ module.exports = function(context, opts) { ); const docsBaseRoute = normalizeUrl([ - context.siteConfig.baseUrl, + (context.siteConfig as DocusaurusConfig).baseUrl, routeBasePath, ]); const docsMetadataPath = await createData( @@ -156,7 +164,8 @@ module.exports = function(context, opts) { }); }, - configureWebpack(config, isServer, {getBabelLoader, getCacheLoader}) { + configureWebpack(_, isServer, utils) { + const {getBabelLoader, getCacheLoader} = utils; const {rehypePlugins, remarkPlugins} = options; return { module: { @@ -179,15 +188,15 @@ module.exports = function(context, opts) { options: { siteConfig: context.siteConfig, siteDir: context.siteDir, - docsDir: globalContents.docsDir, - sourceToPermalink: globalContents.sourceToPermalink, + docsDir: contentPath, + sourceToPermalink: sourceToPermalink, }, }, ].filter(Boolean), }, ], }, - }; + } as Configuration; }, }; -}; +} diff --git a/packages/docusaurus-plugin-content-docs-legacy/src/markdown/index.js b/packages/docusaurus-plugin-content-docs-legacy/src/markdown/index.ts similarity index 85% rename from packages/docusaurus-plugin-content-docs-legacy/src/markdown/index.js rename to packages/docusaurus-plugin-content-docs-legacy/src/markdown/index.ts index 33e6920843..e577937ea6 100644 --- a/packages/docusaurus-plugin-content-docs-legacy/src/markdown/index.js +++ b/packages/docusaurus-plugin-content-docs-legacy/src/markdown/index.ts @@ -5,11 +5,12 @@ * LICENSE file in the root directory of this source tree. */ -const path = require('path'); -const {getOptions} = require('loader-utils'); -const {resolve} = require('url'); +import path from 'path'; +import {getOptions} from 'loader-utils'; +import {resolve} from 'url'; +import {loader} from 'webpack'; -module.exports = async function(fileString) { +export = function(fileString: string) { const callback = this.async(); const options = Object.assign({}, getOptions(this), { filepath: this.resourcePath, @@ -17,7 +18,7 @@ module.exports = async function(fileString) { const {docsDir, siteDir, sourceToPermalink} = options; // Determine the source dir. e.g: /docs, /website/versioned_docs/version-1.0.0 - let sourceDir; + let sourceDir: string | undefined; const thisSource = this.resourcePath; if (thisSource.startsWith(docsDir)) { sourceDir = docsDir; @@ -44,7 +45,7 @@ module.exports = async function(fileString) { // Replace it to correct html link. const mdLink = mdMatch[1]; const targetSource = `${sourceDir}/${mdLink}`; - const aliasedSource = source => + const aliasedSource = (source: string) => `@site/${path.relative(siteDir, source)}`; const permalink = sourceToPermalink[aliasedSource(resolve(thisSource, mdLink))] || @@ -59,5 +60,5 @@ module.exports = async function(fileString) { content = lines.join('\n'); } - return callback(null, content); -}; + return callback && callback(null, content); +} as loader.Loader; diff --git a/packages/docusaurus-plugin-content-docs-legacy/src/metadata.js b/packages/docusaurus-plugin-content-docs-legacy/src/metadata.ts similarity index 81% rename from packages/docusaurus-plugin-content-docs-legacy/src/metadata.js rename to packages/docusaurus-plugin-content-docs-legacy/src/metadata.ts index 4949bad9fe..8b9d8889f0 100644 --- a/packages/docusaurus-plugin-content-docs-legacy/src/metadata.js +++ b/packages/docusaurus-plugin-content-docs-legacy/src/metadata.ts @@ -5,18 +5,20 @@ * LICENSE file in the root directory of this source tree. */ -const fs = require('fs-extra'); -const path = require('path'); -const {parse, normalizeUrl} = require('@docusaurus/utils'); +import fs from 'fs-extra'; +import path from 'path'; +import {parse, normalizeUrl} from '@docusaurus/utils'; +import {Order, MetadataRaw} from './types'; +import {DocusaurusConfig} from '@docusaurus/types'; -module.exports = async function processMetadata( - source, - docsDir, - order, - siteConfig, - docsBasePath, - siteDir, -) { +export default async function processMetadata( + source: string, + docsDir: string, + order: Order, + siteConfig: Partial, + docsBasePath: string, + siteDir: string, +): Promise { const filepath = path.join(docsDir, source); const fileString = await fs.readFile(filepath, 'utf-8'); @@ -82,5 +84,5 @@ module.exports = async function processMetadata( } } - return metadata; -}; + return metadata as MetadataRaw; +} diff --git a/packages/docusaurus-plugin-content-docs-legacy/src/order.js b/packages/docusaurus-plugin-content-docs-legacy/src/order.ts similarity index 62% rename from packages/docusaurus-plugin-content-docs-legacy/src/order.js rename to packages/docusaurus-plugin-content-docs-legacy/src/order.ts index 83827954e8..a7ddfebb4e 100644 --- a/packages/docusaurus-plugin-content-docs-legacy/src/order.js +++ b/packages/docusaurus-plugin-content-docs-legacy/src/order.ts @@ -5,24 +5,42 @@ * LICENSE file in the root directory of this source tree. */ +import { + Sidebar, + SidebarItem, + SidebarItemDoc, + SidebarItemCategory, + Order, +} from './types'; + // Build the docs meta such as next, previous, category and sidebar. -module.exports = function createOrder(allSidebars = {}) { - const order = {}; +export default function createOrder(allSidebars: Sidebar = {}): Order { + const order: Order = {}; Object.keys(allSidebars).forEach(sidebarId => { const sidebar = allSidebars[sidebarId]; - const ids = []; - const categoryOrder = []; - const subCategoryOrder = []; - const indexItems = ({items, categoryLabel, subCategoryLabel}) => { + const ids: string[] = []; + const categoryOrder: (string | undefined)[] = []; + const subCategoryOrder: (string | undefined)[] = []; + const indexItems = ({ + items, + categoryLabel, + subCategoryLabel, + }: { + items: SidebarItem[]; + categoryLabel?: string; + subCategoryLabel?: string; + }) => { items.forEach(item => { switch (item.type) { case 'category': indexItems({ - items: item.items, - categoryLabel: categoryLabel || item.label, - subCategoryLabel: categoryLabel && item.label, + items: (item as SidebarItemCategory).items, + categoryLabel: + categoryLabel || (item as SidebarItemCategory).label, + subCategoryLabel: + categoryLabel && (item as SidebarItemCategory).label, }); break; case 'ref': @@ -30,7 +48,7 @@ module.exports = function createOrder(allSidebars = {}) { // Refs and links should not be shown in navigation. break; case 'doc': - ids.push(item.id); + ids.push((item as SidebarItemDoc).id); categoryOrder.push(categoryLabel); subCategoryOrder.push(subCategoryLabel); break; @@ -69,4 +87,4 @@ module.exports = function createOrder(allSidebars = {}) { }); return order; -}; +} diff --git a/packages/docusaurus-plugin-content-docs-legacy/src/sidebars.js b/packages/docusaurus-plugin-content-docs-legacy/src/sidebars.ts similarity index 52% rename from packages/docusaurus-plugin-content-docs-legacy/src/sidebars.js rename to packages/docusaurus-plugin-content-docs-legacy/src/sidebars.ts index 5e878b012c..507ff3acf2 100644 --- a/packages/docusaurus-plugin-content-docs-legacy/src/sidebars.js +++ b/packages/docusaurus-plugin-content-docs-legacy/src/sidebars.ts @@ -5,16 +5,20 @@ * LICENSE file in the root directory of this source tree. */ -const fs = require('fs'); -const importFresh = require('import-fresh'); +import fs from 'fs'; +import importFresh from 'import-fresh'; +import { + SidebarItemCategory, + Sidebar, + SidebarRaw, + SidebarItem, + SidebarItemCategoryRaw, +} from './types'; /** * Check that item contains only allowed keys - * - * @param {Object} item - * @param {Array} keys */ -function assertItem(item, keys) { +function assertItem(item: Object, keys: string[]): void { const unknownKeys = Object.keys(item).filter( key => !keys.includes(key) && key !== 'type', ); @@ -31,13 +35,11 @@ function assertItem(item, keys) { /** * Normalizes recursively category and all its children. Ensures, that at the end * each item will be an object with the corresponding type - * - * @param {Array} category - * @param {number} [level=0] - * - * @return {Array} */ -function normalizeCategory(category, level = 0) { +function normalizeCategory( + category: SidebarItemCategoryRaw, + level = 0, +): SidebarItemCategory { if (level === 2) { throw new Error( `Can not process ${ @@ -54,33 +56,32 @@ function normalizeCategory(category, level = 0) { ); } - const items = category.items.map(item => { + const items: SidebarItem[] = category.items.map(item => { + if (typeof item === 'string') { + return { + type: 'doc', + id: item, + }; + } switch (item.type) { case 'category': - return normalizeCategory(item, level + 1); + return normalizeCategory(item as SidebarItemCategoryRaw, level + 1); case 'link': assertItem(item, ['href', 'label']); break; case 'ref': - assertItem(item, ['id', 'label']); + assertItem(item, ['id']); break; default: - if (typeof item === 'string') { - return { - type: 'doc', - id: item, - }; - } - if (item.type !== 'doc') { throw new Error(`Unknown sidebar item type: ${item.type}`); } - assertItem(item, ['id', 'label']); + assertItem(item, ['id']); break; } - return item; + return item as SidebarItem; }); return {...category, items}; @@ -88,35 +89,36 @@ function normalizeCategory(category, level = 0) { /** * Converts sidebars object to mapping to arrays of sidebar item objects - * - * @param {{[key: string]: Object}} sidebars - * - * @return {{[key: string]: Array}} */ -function normalizeSidebar(sidebars) { - return Object.entries(sidebars).reduce((acc, [sidebarId, sidebar]) => { - let normalizedSidebar = sidebar; +function normalizeSidebar(sidebars: SidebarRaw): Sidebar { + return Object.entries(sidebars).reduce( + (acc: Sidebar, [sidebarId, sidebar]) => { + let normalizedSidebar: SidebarItemCategoryRaw[]; - if (!Array.isArray(sidebar)) { - // convert sidebar to a more generic structure - normalizedSidebar = Object.entries(sidebar).map(([label, items]) => ({ - type: 'category', - label, - items, - })); - } + if (!Array.isArray(sidebar)) { + // convert sidebar to a more generic structure + normalizedSidebar = Object.entries(sidebar).map(([label, items]) => ({ + type: 'category', + label, + items, + })); + } else { + normalizedSidebar = sidebar; + } - acc[sidebarId] = normalizedSidebar.map(item => normalizeCategory(item)); + acc[sidebarId] = normalizedSidebar.map(item => normalizeCategory(item)); - return acc; - }, {}); + return acc; + }, + {}, + ); } -module.exports = function loadSidebars(sidebarPath) { +export default function loadSidebars(sidebarPath: string): Sidebar { // We don't want sidebars to be cached because of hotreloading. - let allSidebars = {}; + let allSidebars: SidebarRaw = {}; if (sidebarPath && fs.existsSync(sidebarPath)) { - allSidebars = importFresh(sidebarPath); + allSidebars = importFresh(sidebarPath) as SidebarRaw; } return normalizeSidebar(allSidebars); -}; +} diff --git a/packages/docusaurus-plugin-content-docs-legacy/src/types.ts b/packages/docusaurus-plugin-content-docs-legacy/src/types.ts new file mode 100644 index 0000000000..8b8c77b7fa --- /dev/null +++ b/packages/docusaurus-plugin-content-docs-legacy/src/types.ts @@ -0,0 +1,105 @@ +/** + * Copyright (c) 2017-present, Facebook, Inc. + * + * This source code is licensed under the MIT license found in the + * LICENSE file in the root directory of this source tree. + */ +export interface PluginOptions { + path: string; + routeBasePath: string; + include: string[]; + sidebarPath: string; + docLayoutComponent: string; + docItemComponent: string; + remarkPlugins: string[]; + rehypePlugins: string[]; +} + +export type SidebarItemDoc = { + type: string; + id: string; +}; + +export interface SidebarItemLink { + type: string; + href: string; + label: string; +} + +export interface SidebarItemCategory { + type: string; + label: string; + items: SidebarItem[]; +} + +export interface SidebarItemCategoryRaw { + type: string; + label: string; + items: SidebarItemRaw[]; +} + +export type SidebarItem = + | SidebarItemDoc + | SidebarItemLink + | SidebarItemCategory; +export type SidebarItemRaw = + | string + | SidebarItemDoc + | SidebarItemLink + | SidebarItemCategoryRaw; + +// Sidebar given by user that is not normalized yet. e.g: sidebars.json +export interface SidebarRaw { + [sidebarId: string]: { + [sidebarCategory: string]: SidebarItemRaw[]; + }; +} + +export interface Sidebar { + [sidebarId: string]: SidebarItemCategory[]; +} + +export interface OrderMetadata { + previous?: string; + next?: string; + sidebar?: string; + category?: string; + subCategory?: string; +} + +export interface Order { + [id: string]: OrderMetadata; +} + +export interface MetadataRaw extends OrderMetadata { + id: string; + title: string; + description: string; + source: string; + permalink: string; +} + +export interface Metadata extends MetadataRaw { + previous_title?: string; + next_title?: string; +} + +export interface DocsMetadata { + [id: string]: Metadata; +} + +export interface SourceToPermalink { + [source: string]: string; +} + +export interface PermalinkToId { + [permalink: string]: string; +} + +export interface LoadedContent { + docs: DocsMetadata; + docsDir: string; + docsSidebars: Sidebar; + sourceToPermalink: SourceToPermalink; + permalinkToId: PermalinkToId; +} diff --git a/packages/docusaurus-plugin-content-docs-legacy/tsconfig.json b/packages/docusaurus-plugin-content-docs-legacy/tsconfig.json new file mode 100644 index 0000000000..f50aa9ee6d --- /dev/null +++ b/packages/docusaurus-plugin-content-docs-legacy/tsconfig.json @@ -0,0 +1,9 @@ +{ + "extends": "../../tsconfig.json", + "compilerOptions": { + "incremental": true, + "tsBuildInfoFile": "./lib/.tsbuildinfo", + "rootDir": "src", + "outDir": "lib", + } +} diff --git a/packages/docusaurus-types/src/index.d.ts b/packages/docusaurus-types/src/index.d.ts index 3e864bdd20..22b537f017 100644 --- a/packages/docusaurus-types/src/index.d.ts +++ b/packages/docusaurus-types/src/index.d.ts @@ -57,7 +57,7 @@ export interface PluginContentLoadedActions { export interface Plugin { name: string; - loadContent?(): T; + loadContent?(): Promise; contentLoaded?({ content, actions, @@ -67,7 +67,11 @@ export interface Plugin { }): void; postBuild?(props: Props): void; postStart?(props: Props): void; - configureWebpack?(config: Configuration, isServer: boolean): Configuration; + configureWebpack?( + config: Configuration, + isServer: boolean, + utils: ConfigureWebpackUtils, + ): Configuration; getThemePath?(): string; getPathsToWatch?(): string[]; getClientModules?(): string[]; diff --git a/packages/docusaurus/package.json b/packages/docusaurus/package.json index bd4e248413..4a1d451f4e 100644 --- a/packages/docusaurus/package.json +++ b/packages/docusaurus/package.json @@ -52,7 +52,7 @@ "fs-extra": "^8.1.0", "globby": "^10.0.1", "html-webpack-plugin": "^4.0.0-beta.8", - "import-fresh": "^3.0.0", + "import-fresh": "^3.1.0", "lodash": "^4.17.15", "mini-css-extract-plugin": "^0.8.0", "nprogress": "^0.2.0", diff --git a/packages/docusaurus/src/commands/swizzle.ts b/packages/docusaurus/src/commands/swizzle.ts index bbb87df6bc..2c2dfcadba 100644 --- a/packages/docusaurus/src/commands/swizzle.ts +++ b/packages/docusaurus/src/commands/swizzle.ts @@ -17,7 +17,7 @@ export async function swizzle( themeName: string, componentName?: string, ): Promise { - const plugin = importFresh(themeName); + const plugin: any = importFresh(themeName); const pluginInstance = plugin({siteDir}); let fromPath = pluginInstance.getThemePath(); diff --git a/packages/docusaurus/src/server/config.ts b/packages/docusaurus/src/server/config.ts index 5e0fe9a779..69d58c6428 100644 --- a/packages/docusaurus/src/server/config.ts +++ b/packages/docusaurus/src/server/config.ts @@ -51,7 +51,7 @@ export function loadConfig(siteDir: string): DocusaurusConfig { if (!fs.existsSync(configPath)) { throw new Error(`${CONFIG_FILE_NAME} not found`); } - const loadedConfig = importFresh(configPath); + const loadedConfig = importFresh(configPath) as Partial; const missingFields = REQUIRED_FIELDS.filter( field => !_.has(loadedConfig, field), ); @@ -64,7 +64,10 @@ export function loadConfig(siteDir: string): DocusaurusConfig { } // Merge default config with loaded config. - const config: DocusaurusConfig = {...DEFAULT_CONFIG, ...loadedConfig}; + const config: DocusaurusConfig = { + ...DEFAULT_CONFIG, + ...loadedConfig, + } as DocusaurusConfig; // Don't allow unrecognized fields. const allowedFields = [...REQUIRED_FIELDS, ...OPTIONAL_FIELDS]; diff --git a/packages/docusaurus/src/server/plugins/index.ts b/packages/docusaurus/src/server/plugins/index.ts index 87ac6cb1d9..51c66ac7db 100644 --- a/packages/docusaurus/src/server/plugins/index.ts +++ b/packages/docusaurus/src/server/plugins/index.ts @@ -49,7 +49,7 @@ export async function loadPlugins({ } // module is any valid module identifier - npm package or locally-resolved path. - const pluginModule = importFresh(pluginModuleImport); + const pluginModule: any = importFresh(pluginModuleImport); return (pluginModule.default || pluginModule)(context, pluginOptions); }), ); diff --git a/packages/docusaurus/src/server/presets/index.ts b/packages/docusaurus/src/server/presets/index.ts index 2c3693fe92..5074592b9c 100644 --- a/packages/docusaurus/src/server/presets/index.ts +++ b/packages/docusaurus/src/server/presets/index.ts @@ -32,9 +32,11 @@ export function loadPresets( } else if (Array.isArray(presetItem)) { presetModuleImport = presetItem[0]; presetOptions = presetItem[1] || {}; + } else { + throw new Error('Invalid presets format detected in config.'); } - const presetModule = importFresh(presetModuleImport); + const presetModule: any = importFresh(presetModuleImport); const preset: Preset = (presetModule.default || presetModule)( context, presetOptions, diff --git a/yarn.lock b/yarn.lock index cf76f4ad5c..cd428e4f45 100644 --- a/yarn.lock +++ b/yarn.lock @@ -2494,6 +2494,14 @@ resolved "https://registry.yarnpkg.com/@types/json-schema/-/json-schema-7.0.3.tgz#bdfd69d61e464dcc81b25159c270d75a73c1a636" integrity sha512-Il2DtDVRGDcqjDtE+rF8iqg1CArehSK84HZJCT7AMITlyXRBpuPhqGLDQMowraqqu1coEaimg4ZOqggt6L6L+A== +"@types/loader-utils@^1.1.3": + version "1.1.3" + resolved "https://registry.yarnpkg.com/@types/loader-utils/-/loader-utils-1.1.3.tgz#82b9163f2ead596c68a8c03e450fbd6e089df401" + integrity sha512-euKGFr2oCB3ASBwG39CYJMR3N9T0nanVqXdiH7Zu/Nqddt6SmFRxytq/i2w9LQYNQekEtGBz+pE3qG6fQTNvRg== + dependencies: + "@types/node" "*" + "@types/webpack" "*" + "@types/lodash.kebabcase@^4.1.6": version "4.1.6" resolved "https://registry.yarnpkg.com/@types/lodash.kebabcase/-/lodash.kebabcase-4.1.6.tgz#07b07aeca6c0647836de46f87a3cdfff72166c8e" @@ -8126,10 +8134,10 @@ import-fresh@^2.0.0: caller-path "^2.0.0" resolve-from "^3.0.0" -import-fresh@^3.0.0: - version "3.0.0" - resolved "https://registry.yarnpkg.com/import-fresh/-/import-fresh-3.0.0.tgz#a3d897f420cab0e671236897f75bc14b4885c390" - integrity sha512-pOnA9tfM3Uwics+SaBLCNyZZZbK+4PTu0OPZtLlMIrv17EdBoC15S9Kn8ckJ9TZTyKb3ywNE5y1yeDxxGA7nTQ== +import-fresh@^3.1.0: + version "3.1.0" + resolved "https://registry.yarnpkg.com/import-fresh/-/import-fresh-3.1.0.tgz#6d33fa1dcef6df930fae003446f33415af905118" + integrity sha512-PpuksHKGt8rXfWEr9m9EHIpgyyaltBy8+eF6GJM0QCAxMgxCfucMF3mjecK2QsJr0amJW7gTqh5/wht0z2UhEQ== dependencies: parent-module "^1.0.0" resolve-from "^4.0.0"