diff --git a/CHANGELOG-2.x.md b/CHANGELOG-2.x.md index bda664f80888..88943187a057 100644 --- a/CHANGELOG-2.x.md +++ b/CHANGELOG-2.x.md @@ -13,6 +13,7 @@ - Prioritize `@docusaurus/core` dependencies/ node_modules over user's node_modules. This fix a bug whereby if user has core-js@3 on its own node_modules but docusaurus depends on core-js@2, we previously encounter `Module not found: core-js/modules/xxxx` (because core-js@3 doesn't have that). Another example is if user installed webpack@3 but docusaurus depends on webpack@4. - Added code block line highlighting feature (thanks @lex111)! If you have previously swizzled the `CodeBlock` theme component, it is recommended to update your source code to have this feature. +- Fix a bug where docs plugin add `/docs` route even if docs folder is empty. We also improved docs plugin test coverage to 100% for stability before working on docs versioning. ## 2.0.0-alpha.31 diff --git a/jest.config.js b/jest.config.js index 07bf8d64ec38..3afda9ceec2c 100644 --- a/jest.config.js +++ b/jest.config.js @@ -7,20 +7,23 @@ const path = require('path'); +const ignorePatterns = [ + '/node_modules/', + '__fixtures__', + '/packages/docusaurus/lib', + '/packages/docusaurus-utils/lib', + '/packages/docusaurus-plugin-content-blog/lib', + '/packages/docusaurus-plugin-content-docs/lib', + '/packages/docusaurus-plugin-content-pages/lib', +]; + module.exports = { rootDir: path.resolve(__dirname), verbose: true, testURL: 'http://localhost/', testEnvironment: 'node', - testPathIgnorePatterns: [ - '/node_modules/', - '__fixtures__', - '/packages/docusaurus/lib', - '/packages/docusaurus-utils/lib', - '/packages/docusaurus-plugin-content-blog/lib', - '/packages/docusaurus-plugin-content-docs-legacy/lib', - '/packages/docusaurus-plugin-content-pages/lib', - ], + testPathIgnorePatterns: ignorePatterns, + coveragePathIgnorePatterns: ignorePatterns, transform: { '^.+\\.[jt]sx?$': 'babel-jest', }, diff --git a/packages/docusaurus-plugin-content-docs/src/__tests__/__fixtures__/bad-site/docs/invalid-id.md b/packages/docusaurus-plugin-content-docs/src/__tests__/__fixtures__/bad-site/docs/invalid-id.md new file mode 100644 index 000000000000..1ffe4fa38eac --- /dev/null +++ b/packages/docusaurus-plugin-content-docs/src/__tests__/__fixtures__/bad-site/docs/invalid-id.md @@ -0,0 +1,5 @@ +--- +id: hello/super +--- + +Lorem diff --git a/packages/docusaurus-plugin-content-docs/src/__tests__/__fixtures__/empty-site/docusaurus.config.js b/packages/docusaurus-plugin-content-docs/src/__tests__/__fixtures__/empty-site/docusaurus.config.js new file mode 100644 index 000000000000..4b278c9a7b13 --- /dev/null +++ b/packages/docusaurus-plugin-content-docs/src/__tests__/__fixtures__/empty-site/docusaurus.config.js @@ -0,0 +1,16 @@ +/** + * 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. + */ + +module.exports = { + title: 'My Site', + tagline: 'The tagline of my site', + url: 'https://your-docusaurus-test-site.com', + baseUrl: '/', + favicon: 'img/favicon.ico', + organizationName: 'facebook', // Usually your GitHub org/user name. + projectName: 'docusaurus', // Usually your repo name. +}; diff --git a/packages/docusaurus-plugin-content-docs/src/__tests__/__fixtures__/sidebars/sidebars-category-wrong-items.json b/packages/docusaurus-plugin-content-docs/src/__tests__/__fixtures__/sidebars/sidebars-category-wrong-items.json new file mode 100644 index 000000000000..25bdf99e2032 --- /dev/null +++ b/packages/docusaurus-plugin-content-docs/src/__tests__/__fixtures__/sidebars/sidebars-category-wrong-items.json @@ -0,0 +1,11 @@ +{ + "docs": { + "Test": [ + { + "type": "category", + "label": "Category Label", + "items": "doc1" + } + ] + } +} diff --git a/packages/docusaurus-plugin-content-docs/src/__tests__/__fixtures__/website/sidebars-category.js b/packages/docusaurus-plugin-content-docs/src/__tests__/__fixtures__/sidebars/sidebars-category.js similarity index 100% rename from packages/docusaurus-plugin-content-docs/src/__tests__/__fixtures__/website/sidebars-category.js rename to packages/docusaurus-plugin-content-docs/src/__tests__/__fixtures__/sidebars/sidebars-category.js diff --git a/packages/docusaurus-plugin-content-docs/src/__tests__/__fixtures__/website/bad-sidebars.json b/packages/docusaurus-plugin-content-docs/src/__tests__/__fixtures__/sidebars/sidebars-unknown-type.json similarity index 100% rename from packages/docusaurus-plugin-content-docs/src/__tests__/__fixtures__/website/bad-sidebars.json rename to packages/docusaurus-plugin-content-docs/src/__tests__/__fixtures__/sidebars/sidebars-unknown-type.json diff --git a/packages/docusaurus-plugin-content-docs/src/__tests__/__fixtures__/sidebars/sidebars-wrong-field.json b/packages/docusaurus-plugin-content-docs/src/__tests__/__fixtures__/sidebars/sidebars-wrong-field.json new file mode 100644 index 000000000000..43dff88d7c96 --- /dev/null +++ b/packages/docusaurus-plugin-content-docs/src/__tests__/__fixtures__/sidebars/sidebars-wrong-field.json @@ -0,0 +1,20 @@ +{ + "docs": { + "Test": [ + "foo/bar", + "foo/baz", + { + "type": "category", + "label": "category", + "href": "https://github.com" + }, + { + "type": "ref", + "id": "hello" + } + ], + "Guides": [ + "hello" + ] + } +} diff --git a/packages/docusaurus-plugin-content-docs/src/__tests__/__fixtures__/website/sidebars.json b/packages/docusaurus-plugin-content-docs/src/__tests__/__fixtures__/sidebars/sidebars.json similarity index 100% rename from packages/docusaurus-plugin-content-docs/src/__tests__/__fixtures__/website/sidebars.json rename to packages/docusaurus-plugin-content-docs/src/__tests__/__fixtures__/sidebars/sidebars.json diff --git a/packages/docusaurus-plugin-content-docs/src/__tests__/__fixtures__/website/docs/foo/bar.md b/packages/docusaurus-plugin-content-docs/src/__tests__/__fixtures__/simple-site/docs/foo/bar.md similarity index 100% rename from packages/docusaurus-plugin-content-docs/src/__tests__/__fixtures__/website/docs/foo/bar.md rename to packages/docusaurus-plugin-content-docs/src/__tests__/__fixtures__/simple-site/docs/foo/bar.md diff --git a/packages/docusaurus-plugin-content-docs/src/__tests__/__fixtures__/website/docs/foo/baz.md b/packages/docusaurus-plugin-content-docs/src/__tests__/__fixtures__/simple-site/docs/foo/baz.md similarity index 100% rename from packages/docusaurus-plugin-content-docs/src/__tests__/__fixtures__/website/docs/foo/baz.md rename to packages/docusaurus-plugin-content-docs/src/__tests__/__fixtures__/simple-site/docs/foo/baz.md diff --git a/packages/docusaurus-plugin-content-docs/src/__tests__/__fixtures__/website/docs/hello.md b/packages/docusaurus-plugin-content-docs/src/__tests__/__fixtures__/simple-site/docs/hello.md similarity index 100% rename from packages/docusaurus-plugin-content-docs/src/__tests__/__fixtures__/website/docs/hello.md rename to packages/docusaurus-plugin-content-docs/src/__tests__/__fixtures__/simple-site/docs/hello.md diff --git a/packages/docusaurus-plugin-content-docs/src/__tests__/__fixtures__/website/docs/lorem.md b/packages/docusaurus-plugin-content-docs/src/__tests__/__fixtures__/simple-site/docs/lorem.md similarity index 89% rename from packages/docusaurus-plugin-content-docs/src/__tests__/__fixtures__/website/docs/lorem.md rename to packages/docusaurus-plugin-content-docs/src/__tests__/__fixtures__/simple-site/docs/lorem.md index 15589144c4a9..b088a6ec006b 100644 --- a/packages/docusaurus-plugin-content-docs/src/__tests__/__fixtures__/website/docs/lorem.md +++ b/packages/docusaurus-plugin-content-docs/src/__tests__/__fixtures__/simple-site/docs/lorem.md @@ -1,5 +1,4 @@ --- -id: lorem custom_edit_url: https://github.com/customUrl/docs/lorem.md --- diff --git a/packages/docusaurus-plugin-content-docs/src/__tests__/__fixtures__/website/docs/permalink.md b/packages/docusaurus-plugin-content-docs/src/__tests__/__fixtures__/simple-site/docs/permalink.md similarity index 100% rename from packages/docusaurus-plugin-content-docs/src/__tests__/__fixtures__/website/docs/permalink.md rename to packages/docusaurus-plugin-content-docs/src/__tests__/__fixtures__/simple-site/docs/permalink.md diff --git a/packages/docusaurus-plugin-content-docs/src/__tests__/__fixtures__/simple-site/docusaurus.config.js b/packages/docusaurus-plugin-content-docs/src/__tests__/__fixtures__/simple-site/docusaurus.config.js new file mode 100644 index 000000000000..4b278c9a7b13 --- /dev/null +++ b/packages/docusaurus-plugin-content-docs/src/__tests__/__fixtures__/simple-site/docusaurus.config.js @@ -0,0 +1,16 @@ +/** + * 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. + */ + +module.exports = { + title: 'My Site', + tagline: 'The tagline of my site', + url: 'https://your-docusaurus-test-site.com', + baseUrl: '/', + favicon: 'img/favicon.ico', + organizationName: 'facebook', // Usually your GitHub org/user name. + projectName: 'docusaurus', // Usually your repo name. +}; diff --git a/packages/docusaurus-plugin-content-docs/src/__tests__/__fixtures__/simple-site/sidebars.json b/packages/docusaurus-plugin-content-docs/src/__tests__/__fixtures__/simple-site/sidebars.json new file mode 100644 index 000000000000..7892de099a43 --- /dev/null +++ b/packages/docusaurus-plugin-content-docs/src/__tests__/__fixtures__/simple-site/sidebars.json @@ -0,0 +1,23 @@ +{ + "docs": { + "Test": [ + { + "type": "category", + "label": "foo", + "items": ["foo/bar", "foo/baz"] + }, + { + "type": "link", + "label": "Github", + "href": "https://github.com" + }, + { + "type": "ref", + "id": "hello" + } + ], + "Guides": [ + "hello" + ] + } +} diff --git a/packages/docusaurus-plugin-content-docs/src/__tests__/__fixtures__/simple-site/wrong-sidebars.json b/packages/docusaurus-plugin-content-docs/src/__tests__/__fixtures__/simple-site/wrong-sidebars.json new file mode 100644 index 000000000000..6f56ce2c0b5a --- /dev/null +++ b/packages/docusaurus-plugin-content-docs/src/__tests__/__fixtures__/simple-site/wrong-sidebars.json @@ -0,0 +1,7 @@ +{ + "docs": { + "Test": [ + "goku" + ] + } +} diff --git a/packages/docusaurus-plugin-content-docs/src/__tests__/__snapshots__/index.test.ts.snap b/packages/docusaurus-plugin-content-docs/src/__tests__/__snapshots__/index.test.ts.snap new file mode 100644 index 000000000000..c59be9c120ee --- /dev/null +++ b/packages/docusaurus-plugin-content-docs/src/__tests__/__snapshots__/index.test.ts.snap @@ -0,0 +1,110 @@ +// Jest Snapshot v1, https://goo.gl/fbAQLP + +exports[`simple website content 1`] = ` +Object { + "docs": Array [ + Object { + "items": Array [ + Object { + "items": Array [ + Object { + "href": "/docs/foo/bar", + "label": "Bar", + "type": "link", + }, + Object { + "href": "/docs/foo/baz", + "label": "baz", + "type": "link", + }, + ], + "label": "foo", + "type": "category", + }, + Object { + "href": "https://github.com", + "label": "Github", + "type": "link", + }, + Object { + "href": "/docs/hello", + "label": "Hello, World !", + "type": "link", + }, + ], + "label": "Test", + "type": "category", + }, + Object { + "items": Array [ + Object { + "href": "/docs/hello", + "label": "Hello, World !", + "type": "link", + }, + ], + "label": "Guides", + "type": "category", + }, + ], +} +`; + +exports[`simple website content 2`] = ` +Array [ + Object { + "component": "@theme/DocPage", + "modules": Object { + "docsMetadata": "@docusaurus-plugin-content-docs/docs-b5f.json", + }, + "path": "/docs", + "routes": Array [ + Object { + "component": "@theme/DocItem", + "exact": true, + "modules": Object { + "content": "@site/docs/permalink.md", + "metadata": "@docusaurus-plugin-content-docs/docs-endiliey-permalink-086.json", + }, + "path": "/docs/endiliey/permalink", + }, + Object { + "component": "@theme/DocItem", + "exact": true, + "modules": Object { + "content": "@site/docs/foo/bar.md", + "metadata": "@docusaurus-plugin-content-docs/docs-foo-bar-cef.json", + }, + "path": "/docs/foo/bar", + }, + Object { + "component": "@theme/DocItem", + "exact": true, + "modules": Object { + "content": "@site/docs/foo/baz.md", + "metadata": "@docusaurus-plugin-content-docs/docs-foo-baz-dd9.json", + }, + "path": "/docs/foo/baz", + }, + Object { + "component": "@theme/DocItem", + "exact": true, + "modules": Object { + "content": "@site/docs/hello.md", + "metadata": "@docusaurus-plugin-content-docs/docs-hello-da2.json", + }, + "path": "/docs/hello", + }, + Object { + "component": "@theme/DocItem", + "exact": true, + "modules": Object { + "content": "@site/docs/lorem.md", + "metadata": "@docusaurus-plugin-content-docs/docs-lorem-17b.json", + }, + "path": "/docs/lorem", + }, + ], + }, +] +`; diff --git a/packages/docusaurus-plugin-content-docs/src/__tests__/index.test.ts b/packages/docusaurus-plugin-content-docs/src/__tests__/index.test.ts index a338bed2aadb..a044c52325b7 100644 --- a/packages/docusaurus-plugin-content-docs/src/__tests__/index.test.ts +++ b/packages/docusaurus-plugin-content-docs/src/__tests__/index.test.ts @@ -6,32 +6,109 @@ */ import path from 'path'; - +import {validate} from 'webpack'; +import fs from 'fs-extra'; import pluginContentDocs from '../index'; -import {LoadContext} from '@docusaurus/types'; - -describe('loadDocs', () => { - test('simple website', async () => { - const siteDir = path.join(__dirname, '__fixtures__', 'website'); - const generatedFilesDir: string = path.resolve(siteDir, '.docusaurus'); - const siteConfig = { - title: 'Hello', - baseUrl: '/', - url: 'https://docusaurus.io', - }; - const context = { - siteDir, - siteConfig, - generatedFilesDir, - } as LoadContext; - const sidebarPath = path.join(siteDir, 'sidebars.json'); - const pluginPath = 'docs'; - const plugin = pluginContentDocs(context, { - path: pluginPath, - sidebarPath, +import {loadContext} from '@docusaurus/core/src/server/index'; +import {applyConfigureWebpack} from '@docusaurus/core/src/webpack/utils'; +import {RouteConfig} from '@docusaurus/types'; + +const createFakeActions = (routeConfigs: RouteConfig[], contentDir) => { + return { + addRoute: (config: RouteConfig) => { + config.routes.sort((a, b) => + a.path > b.path ? 1 : b.path > a.path ? -1 : 0, + ); + routeConfigs.push(config); + }, + createData: async (name, _content) => { + return path.join(contentDir, name); + }, + }; +}; + +test('site with wrong sidebar file', async () => { + const siteDir = path.join(__dirname, '__fixtures__', 'simple-site'); + const context = loadContext(siteDir); + const sidebarPath = path.join(siteDir, 'wrong-sidebars.json'); + const plugin = pluginContentDocs(context, { + sidebarPath, + }); + return plugin + .loadContent() + .catch(e => + expect(e).toMatchInlineSnapshot( + `[Error: Improper sidebars file, document with id 'goku' not found.]`, + ), + ); +}); + +describe('empty/no docs website', () => { + const siteDir = path.join(__dirname, '__fixtures__', 'empty-site'); + const context = loadContext(siteDir); + + test('no files in docs folder', async () => { + await fs.ensureDir(path.join(siteDir, 'docs')); + const plugin = pluginContentDocs(context, {}); + const content = await plugin.loadContent(); + const {docsMetadata, docsSidebars} = content; + expect(docsMetadata).toMatchInlineSnapshot(`Object {}`); + expect(docsSidebars).toMatchInlineSnapshot(`Object {}`); + + const routeConfigs = []; + const pluginContentDir = path.join(context.generatedFilesDir, plugin.name); + const actions = createFakeActions(routeConfigs, pluginContentDir); + + await plugin.contentLoaded({ + content, + actions, }); - const {docsMetadata} = await plugin.loadContent(); + expect(routeConfigs).toEqual([]); + }); + + test('docs folder does not exist', async () => { + const plugin = pluginContentDocs(context, {path: '/path/does/not/exist/'}); + const content = await plugin.loadContent(); + expect(content).toBeNull(); + }); +}); + +describe('simple website', () => { + const siteDir = path.join(__dirname, '__fixtures__', 'simple-site'); + const context = loadContext(siteDir); + const sidebarPath = path.join(siteDir, 'sidebars.json'); + const pluginPath = 'docs'; + const plugin = pluginContentDocs(context, { + path: pluginPath, + sidebarPath, + }); + const pluginContentDir = path.join(context.generatedFilesDir, plugin.name); + + test('getPathToWatch', () => { + const pathToWatch = plugin.getPathsToWatch(); + expect(pathToWatch).not.toEqual([]); + }); + + test('configureWebpack', async () => { + const config = applyConfigureWebpack( + plugin.configureWebpack, + { + entry: './src/index.js', + output: { + filename: 'main.js', + path: path.resolve(__dirname, 'dist'), + }, + }, + false, + ); + const errors = validate(config); + expect(errors.length).toBe(0); + }); + + test('content', async () => { + const content = await plugin.loadContent(); + const {docsMetadata, docsSidebars} = content; expect(docsMetadata.hello).toEqual({ id: 'hello', permalink: '/docs/hello', @@ -57,5 +134,18 @@ describe('loadDocs', () => { title: 'Bar', description: 'This is custom description', }); + + expect(docsSidebars).toMatchSnapshot(); + + const routeConfigs = []; + const actions = createFakeActions(routeConfigs, pluginContentDir); + + await plugin.contentLoaded({ + content, + actions, + }); + + expect(routeConfigs).not.toEqual([]); + expect(routeConfigs).toMatchSnapshot(); }); }); diff --git a/packages/docusaurus-plugin-content-docs/src/__tests__/lastUpdate.test.ts b/packages/docusaurus-plugin-content-docs/src/__tests__/lastUpdate.test.ts index bf088ed828d0..52210e918478 100644 --- a/packages/docusaurus-plugin-content-docs/src/__tests__/lastUpdate.test.ts +++ b/packages/docusaurus-plugin-content-docs/src/__tests__/lastUpdate.test.ts @@ -7,15 +7,17 @@ import fs from 'fs'; import path from 'path'; +import shell from 'shelljs'; +import spawn from 'cross-spawn'; import lastUpdate from '../lastUpdate'; describe('lastUpdate', () => { + const existingFilePath = path.join( + __dirname, + '__fixtures__/simple-site/docs/hello.md', + ); test('existing test file in repository with Git timestamp', () => { - const existingFilePath = path.join( - __dirname, - '__fixtures__/website/docs/hello.md', - ); const lastUpdateData = lastUpdate(existingFilePath); expect(lastUpdateData).not.toBeNull(); @@ -44,4 +46,30 @@ describe('lastUpdate', () => { expect(lastUpdate(tempFilePath)).toBeNull(); fs.unlinkSync(tempFilePath); }); + + test('Git does not exist', () => { + const mock = jest.spyOn(shell, 'which').mockImplementationOnce(() => null); + const consoleMock = jest.spyOn(console, 'warn').mockImplementation(); + const lastUpdateData = lastUpdate(existingFilePath); + expect(lastUpdateData).toBeNull(); + expect(consoleMock).toHaveBeenLastCalledWith( + 'Sorry, the docs plugin last update options require Git.', + ); + + consoleMock.mockRestore(); + mock.mockRestore(); + }); + + test('Error', () => { + const mock = jest.spyOn(spawn, 'sync').mockImplementationOnce(() => { + throw new Error('PERMISSION Error'); + }); + const consoleMock = jest.spyOn(console, 'error').mockImplementation(); + const lastUpdateData = lastUpdate('/fake/path/'); + expect(lastUpdateData).toBeNull(); + expect(consoleMock).toHaveBeenLastCalledWith(new Error('PERMISSION Error')); + + consoleMock.mockRestore(); + mock.mockRestore(); + }); }); diff --git a/packages/docusaurus-plugin-content-docs/src/__tests__/metadata.test.ts b/packages/docusaurus-plugin-content-docs/src/__tests__/metadata.test.ts index 1a6ca22a172b..1caaab4a17cf 100644 --- a/packages/docusaurus-plugin-content-docs/src/__tests__/metadata.test.ts +++ b/packages/docusaurus-plugin-content-docs/src/__tests__/metadata.test.ts @@ -9,14 +9,15 @@ import path from 'path'; import processMetadata from '../metadata'; describe('processMetadata', () => { - const siteDir = path.join(__dirname, '__fixtures__', 'website'); + const fixtureDir = path.join(__dirname, '__fixtures__'); + const simpleSiteDir = path.join(fixtureDir, 'simple-site'); const siteConfig = { title: 'Hello', baseUrl: '/', url: 'https://docusaurus.io', }; const pluginPath = 'docs'; - const docsDir = path.resolve(siteDir, pluginPath); + const docsDir = path.resolve(simpleSiteDir, pluginPath); test('normal docs', async () => { const sourceA = path.join('foo', 'bar.md'); @@ -29,7 +30,7 @@ describe('processMetadata', () => { order: {}, siteConfig, docsBasePath: pluginPath, - siteDir, + siteDir: simpleSiteDir, }), processMetadata({ source: sourceB, @@ -37,7 +38,7 @@ describe('processMetadata', () => { order: {}, siteConfig, docsBasePath: pluginPath, - siteDir, + siteDir: simpleSiteDir, }), ]); @@ -65,7 +66,7 @@ describe('processMetadata', () => { order: {}, siteConfig, docsBasePath: pluginPath, - siteDir, + siteDir: simpleSiteDir, }); expect(data).toEqual({ @@ -87,7 +88,7 @@ describe('processMetadata', () => { order: {}, siteConfig, docsBasePath: pluginPath, - siteDir, + siteDir: simpleSiteDir, editUrl, }); @@ -110,7 +111,7 @@ describe('processMetadata', () => { order: {}, siteConfig, docsBasePath: pluginPath, - siteDir, + siteDir: simpleSiteDir, }); expect(data).toEqual({ @@ -122,4 +123,46 @@ describe('processMetadata', () => { description: 'Lorem ipsum.', }); }); + + test('docs with last update time and author', async () => { + const source = 'lorem.md'; + const data = await processMetadata({ + source, + docsDir, + order: {}, + siteConfig, + docsBasePath: pluginPath, + siteDir: simpleSiteDir, + showLastUpdateAuthor: true, + showLastUpdateTime: true, + }); + + expect(data).toEqual({ + id: 'lorem', + permalink: '/docs/lorem', + source: path.join('@site', pluginPath, source), + title: 'lorem', + editUrl: 'https://github.com/customUrl/docs/lorem.md', + description: 'Lorem ipsum.', + lastUpdatedAt: '1539502055', + lastUpdatedBy: 'Author', + }); + }); + + test('docs with invalid id', async () => { + const badSiteDir = path.join(fixtureDir, 'bad-site'); + + return processMetadata({ + source: 'invalid-id.md', + docsDir: path.join(badSiteDir, 'docs'), + order: {}, + siteConfig, + docsBasePath: 'docs', + siteDir: simpleSiteDir, + }).catch(e => + expect(e).toMatchInlineSnapshot( + `[Error: Document id cannot include "/".]`, + ), + ); + }); }); diff --git a/packages/docusaurus-plugin-content-docs/src/__tests__/order.test.ts b/packages/docusaurus-plugin-content-docs/src/__tests__/order.test.ts index 1f237318b747..7cdc265dbdd0 100644 --- a/packages/docusaurus-plugin-content-docs/src/__tests__/order.test.ts +++ b/packages/docusaurus-plugin-content-docs/src/__tests__/order.test.ts @@ -218,6 +218,29 @@ describe('createOrder', () => { }); }); + test('multiple sidebars with unknown sidebar item type', () => { + expect(() => + createOrder({ + docs: [ + { + type: 'category', + label: 'Category1', + items: [{type: 'endi', id: 'doc1'}, {type: 'doc', id: 'doc2'}], + }, + ], + otherDocs: [ + { + type: 'category', + label: 'Category1', + items: [{type: 'doc', id: 'doc5'}], + }, + ], + }), + ).toThrowErrorMatchingInlineSnapshot( + `"Unknown item type: endi. Item: {\\"type\\":\\"endi\\",\\"id\\":\\"doc1\\"}"`, + ); + }); + test('edge cases', () => { expect(createOrder({})).toEqual({}); expect(createOrder(undefined)).toEqual({}); diff --git a/packages/docusaurus-plugin-content-docs/src/__tests__/sidebars.test.ts b/packages/docusaurus-plugin-content-docs/src/__tests__/sidebars.test.ts index 9239041d57c1..0a153e45f8d7 100644 --- a/packages/docusaurus-plugin-content-docs/src/__tests__/sidebars.test.ts +++ b/packages/docusaurus-plugin-content-docs/src/__tests__/sidebars.test.ts @@ -11,40 +11,43 @@ import loadSidebars from '../sidebars'; /* eslint-disable global-require, import/no-dynamic-require */ describe('loadSidebars', () => { + const fixtureDir = path.join(__dirname, '__fixtures__', 'sidebars'); test('sidebars with known sidebar item type', async () => { - const sidebarPath = path.join( - __dirname, - '__fixtures__', - 'website', - 'sidebars.json', - ); + const sidebarPath = path.join(fixtureDir, 'sidebars.json'); const result = loadSidebars(sidebarPath); expect(result).toMatchSnapshot(); }); test('sidebars with deep level of category', async () => { - const sidebarPath = path.join( - __dirname, - '__fixtures__', - 'website', - 'sidebars-category.js', - ); + const sidebarPath = path.join(fixtureDir, 'sidebars-category.js'); const result = loadSidebars(sidebarPath); expect(result).toMatchSnapshot(); }); - test('sidebars with unknown sidebar item type', async () => { + test('sidebars with category but category.items is not an array', async () => { const sidebarPath = path.join( - __dirname, - '__fixtures__', - 'website', - 'bad-sidebars.json', + fixtureDir, + 'sidebars-category-wrong-items.json', + ); + expect(() => loadSidebars(sidebarPath)).toThrowErrorMatchingInlineSnapshot( + `"Error loading \\"Category Label\\" category. Category items must be array."`, ); + }); + + test('sidebars with unknown sidebar item type', async () => { + const sidebarPath = path.join(fixtureDir, 'sidebars-unknown-type.json'); expect(() => loadSidebars(sidebarPath)).toThrowErrorMatchingInlineSnapshot( `"Unknown sidebar item type: superman"`, ); }); + test('sidebars with known sidebar item type but wrong field', async () => { + const sidebarPath = path.join(fixtureDir, 'sidebars-wrong-field.json'); + expect(() => loadSidebars(sidebarPath)).toThrowErrorMatchingInlineSnapshot( + `"Unknown sidebar item keys: href. Item: {\\"type\\":\\"category\\",\\"label\\":\\"category\\",\\"href\\":\\"https://github.com\\"}"`, + ); + }); + test('no sidebars', () => { const result = loadSidebars(null); expect(result).toEqual({}); diff --git a/packages/docusaurus-plugin-content-docs/src/index.ts b/packages/docusaurus-plugin-content-docs/src/index.ts index c40852153818..a2e1061c29c9 100644 --- a/packages/docusaurus-plugin-content-docs/src/index.ts +++ b/packages/docusaurus-plugin-content-docs/src/index.ts @@ -177,9 +177,8 @@ export default function pluginContentDocs( case 'doc': return convertDocLink(item as SidebarItemDoc); case 'link': - break; default: - throw new Error(`Unknown sidebar item type: ${item.type}`); + break; } return item as SidebarItemLink; }); @@ -208,7 +207,7 @@ export default function pluginContentDocs( }, async contentLoaded({content, actions}) { - if (!content) { + if (!content || Object.keys(content.docsMetadata).length === 0) { return; } diff --git a/packages/docusaurus-plugin-content-docs/src/lastUpdate.ts b/packages/docusaurus-plugin-content-docs/src/lastUpdate.ts index c1ac941e3411..da24c3add86d 100644 --- a/packages/docusaurus-plugin-content-docs/src/lastUpdate.ts +++ b/packages/docusaurus-plugin-content-docs/src/lastUpdate.ts @@ -33,7 +33,7 @@ export default function getFileLastUpdate( if (!shell.which('git')) { if (!showedGitRequirementError) { showedGitRequirementError = true; - console.log('Sorry, the docs plugin last update options require Git.'); + console.warn('Sorry, the docs plugin last update options require Git.'); } return null; diff --git a/packages/docusaurus-plugin-content-docs/src/sidebars.ts b/packages/docusaurus-plugin-content-docs/src/sidebars.ts index a8cb3c7516c4..dd0d108a41b2 100644 --- a/packages/docusaurus-plugin-content-docs/src/sidebars.ts +++ b/packages/docusaurus-plugin-content-docs/src/sidebars.ts @@ -44,7 +44,7 @@ function normalizeCategory( if (!Array.isArray(category.items)) { throw new Error( - `Error loading ${category.label} category. Category items must be array.`, + `Error loading "${category.label}" category. Category items must be array.`, ); } @@ -62,15 +62,11 @@ function normalizeCategory( assertItem(item, ['href', 'label']); break; case 'ref': + case 'doc': assertItem(item, ['id']); break; default: - if (item.type !== 'doc') { - throw new Error(`Unknown sidebar item type: ${item.type}`); - } - - assertItem(item, ['id']); - break; + throw new Error(`Unknown sidebar item type: ${item.type}`); } return item as SidebarItem;