From 06dce4cfeb01627eb2d3908e92fa333ad401ca81 Mon Sep 17 00:00:00 2001 From: Jody Heavener Date: Sun, 23 Jan 2022 19:09:39 -0400 Subject: [PATCH] feat(content-docs): exclude draft docs from builds, sidebars --- .../__fixtures__/simple-site/docs/draft.md | 5 + .../__tests__/__snapshots__/docs.test.ts.snap | 5 + .../__snapshots__/index.test.ts.snap | 154 ++++++++++++++++-- .../src/__tests__/docs.test.ts | 43 +++++ .../src/__tests__/frontMatter.test.ts | 16 ++ .../src/docs.ts | 4 + .../src/frontMatter.ts | 1 + .../src/plugin-content-docs.d.ts | 4 + .../src/routes.ts | 48 +++--- .../src/sidebars/__tests__/generator.test.ts | 42 +++++ .../src/sidebars/__tests__/processor.test.ts | 29 ++++ .../src/sidebars/generator.ts | 5 +- .../src/sidebars/processor.ts | 7 + .../src/sidebars/types.ts | 1 + website/_dogfooding/_docs tests/draft.md | 7 + .../_dogfooding/_docs tests/tests/draft.md | 7 + website/_dogfooding/docs-tests-sidebars.js | 1 + .../docs/api/plugins/plugin-content-docs.md | 1 + 18 files changed, 337 insertions(+), 43 deletions(-) create mode 100644 packages/docusaurus-plugin-content-docs/src/__tests__/__fixtures__/simple-site/docs/draft.md create mode 100644 website/_dogfooding/_docs tests/draft.md create mode 100644 website/_dogfooding/_docs tests/tests/draft.md diff --git a/packages/docusaurus-plugin-content-docs/src/__tests__/__fixtures__/simple-site/docs/draft.md b/packages/docusaurus-plugin-content-docs/src/__tests__/__fixtures__/simple-site/docs/draft.md new file mode 100644 index 0000000000000..dfc31e3f3594f --- /dev/null +++ b/packages/docusaurus-plugin-content-docs/src/__tests__/__fixtures__/simple-site/docs/draft.md @@ -0,0 +1,5 @@ +--- +draft: true +--- + +This is a draft document diff --git a/packages/docusaurus-plugin-content-docs/src/__tests__/__snapshots__/docs.test.ts.snap b/packages/docusaurus-plugin-content-docs/src/__tests__/__snapshots__/docs.test.ts.snap index eaed1c90bbbb5..fd9e3739fd70e 100644 --- a/packages/docusaurus-plugin-content-docs/src/__tests__/__snapshots__/docs.test.ts.snap +++ b/packages/docusaurus-plugin-content-docs/src/__tests__/__snapshots__/docs.test.ts.snap @@ -11,6 +11,11 @@ exports[`simple site custom pagination 1`] = ` }, "prev": undefined, }, + { + "id": "draft", + "next": undefined, + "prev": undefined, + }, { "id": "foo/bar", "next": undefined, 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 index 44346d589b451..dda4b542546d6 100644 --- 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 @@ -23,6 +23,7 @@ These sidebar document ids do not exist: Available document ids are: - doc with space +- draft - foo/bar - foo/baz - headingAsTitle @@ -59,6 +60,7 @@ exports[`simple website content 1`] = ` "title": "baz", }, "id": "foo/baz", + "isDraft": false, "lastUpdatedAt": undefined, "lastUpdatedBy": undefined, "next": { @@ -107,6 +109,7 @@ exports[`simple website content 2`] = ` "title": "Hello, World !", }, "id": "hello", + "isDraft": false, "lastUpdatedAt": undefined, "lastUpdatedBy": undefined, "next": undefined, @@ -149,6 +152,7 @@ exports[`simple website content 3`] = ` "title": "Bar", }, "id": "foo/bar", + "isDraft": false, "lastUpdatedAt": undefined, "lastUpdatedBy": undefined, "next": undefined, @@ -268,6 +272,11 @@ exports[`simple website content 5`] = ` "path": "/docs/doc with space", "sidebar": undefined, }, + { + "id": "draft", + "path": "/docs/draft", + "sidebar": undefined, + }, { "id": "foo/bar", "path": "/docs/foo/bar", @@ -392,7 +401,24 @@ exports[`simple website content: data 1`] = ` \\"permalink\\": \\"/docs/doc with space\\", \\"tags\\": [], \\"version\\": \\"current\\", - \\"frontMatter\\": {} + \\"frontMatter\\": {}, + \\"isDraft\\": false +}", + "site-docs-draft-md-5b1.json": "{ + \\"unversionedId\\": \\"draft\\", + \\"id\\": \\"draft\\", + \\"title\\": \\"draft\\", + \\"description\\": \\"This is a draft document\\", + \\"source\\": \\"@site/docs/draft.md\\", + \\"sourceDirName\\": \\".\\", + \\"slug\\": \\"/draft\\", + \\"permalink\\": \\"/docs/draft\\", + \\"tags\\": [], + \\"version\\": \\"current\\", + \\"frontMatter\\": { + \\"draft\\": true + }, + \\"isDraft\\": false }", "site-docs-foo-bar-md-8c2.json": "{ \\"unversionedId\\": \\"foo/bar\\", @@ -412,6 +438,7 @@ exports[`simple website content: data 1`] = ` \\"pagination_next\\": null, \\"pagination_prev\\": null }, + \\"isDraft\\": false, \\"sidebar\\": \\"docs\\" }", "site-docs-foo-baz-md-a69.json": "{ @@ -448,6 +475,7 @@ exports[`simple website content: data 1`] = ` } ] }, + \\"isDraft\\": false, \\"sidebar\\": \\"docs\\", \\"previous\\": { \\"title\\": \\"Bar\\", @@ -470,6 +498,7 @@ exports[`simple website content: data 1`] = ` \\"tags\\": [], \\"version\\": \\"current\\", \\"frontMatter\\": {}, + \\"isDraft\\": false, \\"sidebar\\": \\"docs\\", \\"previous\\": { \\"title\\": \\"rootTryToEscapeSlug\\", @@ -510,6 +539,7 @@ exports[`simple website content: data 1`] = ` ], \\"slug\\": \\"/\\" }, + \\"isDraft\\": false, \\"sidebar\\": \\"docs\\", \\"previous\\": { \\"title\\": \\"My heading as title\\", @@ -530,7 +560,8 @@ exports[`simple website content: data 1`] = ` \\"version\\": \\"current\\", \\"frontMatter\\": { \\"custom_edit_url\\": null - } + }, + \\"isDraft\\": false }", "site-docs-lorem-md-b27.json": "{ \\"unversionedId\\": \\"lorem\\", @@ -547,7 +578,8 @@ exports[`simple website content: data 1`] = ` \\"frontMatter\\": { \\"custom_edit_url\\": \\"https://github.com/customUrl/docs/lorem.md\\", \\"unrelated_front_matter\\": \\"won't be part of metadata\\" - } + }, + \\"isDraft\\": false }", "site-docs-root-absolute-slug-md-db5.json": "{ \\"unversionedId\\": \\"rootAbsoluteSlug\\", @@ -565,6 +597,7 @@ exports[`simple website content: data 1`] = ` \\"pagination_next\\": \\"headingAsTitle\\", \\"pagination_prev\\": \\"foo/baz\\" }, + \\"isDraft\\": false, \\"sidebar\\": \\"docs\\", \\"previous\\": { \\"title\\": \\"baz pagination_label\\", @@ -591,6 +624,7 @@ exports[`simple website content: data 1`] = ` \\"pagination_next\\": \\"headingAsTitle\\", \\"pagination_prev\\": \\"foo/baz\\" }, + \\"isDraft\\": false, \\"sidebar\\": \\"docs\\", \\"previous\\": { \\"title\\": \\"baz pagination_label\\", @@ -617,6 +651,7 @@ exports[`simple website content: data 1`] = ` \\"pagination_next\\": \\"headingAsTitle\\", \\"pagination_prev\\": \\"foo/baz\\" }, + \\"isDraft\\": false, \\"sidebar\\": \\"docs\\", \\"previous\\": { \\"title\\": \\"baz pagination_label\\", @@ -643,6 +678,7 @@ exports[`simple website content: data 1`] = ` \\"pagination_next\\": \\"headingAsTitle\\", \\"pagination_prev\\": \\"foo/baz\\" }, + \\"isDraft\\": false, \\"sidebar\\": \\"docs\\", \\"previous\\": { \\"title\\": \\"baz pagination_label\\", @@ -666,7 +702,8 @@ exports[`simple website content: data 1`] = ` \\"version\\": \\"current\\", \\"frontMatter\\": { \\"slug\\": \\"/absoluteSlug\\" - } + }, + \\"isDraft\\": false }", "site-docs-slugs-relative-slug-md-d1c.json": "{ \\"unversionedId\\": \\"slugs/relativeSlug\\", @@ -681,7 +718,8 @@ exports[`simple website content: data 1`] = ` \\"version\\": \\"current\\", \\"frontMatter\\": { \\"slug\\": \\"relativeSlug\\" - } + }, + \\"isDraft\\": false }", "site-docs-slugs-resolved-slug-md-02b.json": "{ \\"unversionedId\\": \\"slugs/resolvedSlug\\", @@ -696,7 +734,8 @@ exports[`simple website content: data 1`] = ` \\"version\\": \\"current\\", \\"frontMatter\\": { \\"slug\\": \\"./hey/ho/../resolvedSlug\\" - } + }, + \\"isDraft\\": false }", "site-docs-slugs-try-to-escape-slug-md-70d.json": "{ \\"unversionedId\\": \\"slugs/tryToEscapeSlug\\", @@ -711,7 +750,8 @@ exports[`simple website content: data 1`] = ` \\"version\\": \\"current\\", \\"frontMatter\\": { \\"slug\\": \\"../../../../../../../../tryToEscapeSlug\\" - } + }, + \\"isDraft\\": false }", "tag-docs-tags-tag-1-b3f.json": "{ \\"name\\": \\"tag 1\\", @@ -885,6 +925,11 @@ exports[`simple website content: data 1`] = ` \\"title\\": \\"Hoo hoo, if this path tricks you...\\", \\"description\\": \\"\\" }, + \\"draft\\": { + \\"id\\": \\"draft\\", + \\"title\\": \\"draft\\", + \\"description\\": \\"This is a draft document\\" + }, \\"foo/bar\\": { \\"id\\": \\"foo/bar\\", \\"title\\": \\"Bar\\", @@ -982,6 +1027,11 @@ exports[`simple website content: global data 1`] = ` "path": "/docs/doc with space", "sidebar": undefined, }, + { + "id": "draft", + "path": "/docs/draft", + "sidebar": undefined, + }, { "id": "foo/bar", "path": "/docs/foo/bar", @@ -1155,6 +1205,14 @@ exports[`simple website content: route config 1`] = ` }, "path": "/docs/doc with space", }, + { + "component": "@theme/DocItem", + "exact": true, + "modules": { + "content": "@site/docs/draft.md", + }, + "path": "/docs/draft", + }, { "component": "@theme/DocItem", "exact": true, @@ -1404,6 +1462,7 @@ exports[`site with custom sidebar items generator sidebarItemsGenerator is calle { "frontMatter": {}, "id": "API/Core APIs/Client API", + "isDraft": false, "sidebarPosition": 0, "source": "@site/docs/3-API/01_Core APIs/0 --- Client API.md", "sourceDirName": "3-API/01_Core APIs", @@ -1413,6 +1472,7 @@ exports[`site with custom sidebar items generator sidebarItemsGenerator is calle { "frontMatter": {}, "id": "API/Core APIs/Server API", + "isDraft": false, "sidebarPosition": 1, "source": "@site/docs/3-API/01_Core APIs/1 --- Server API.md", "sourceDirName": "3-API/01_Core APIs", @@ -1422,6 +1482,7 @@ exports[`site with custom sidebar items generator sidebarItemsGenerator is calle { "frontMatter": {}, "id": "API/Extension APIs/Plugin API", + "isDraft": false, "sidebarPosition": 0, "source": "@site/docs/3-API/02_Extension APIs/0. Plugin API.md", "sourceDirName": "3-API/02_Extension APIs", @@ -1431,6 +1492,7 @@ exports[`site with custom sidebar items generator sidebarItemsGenerator is calle { "frontMatter": {}, "id": "API/Extension APIs/Theme API", + "isDraft": false, "sidebarPosition": 1, "source": "@site/docs/3-API/02_Extension APIs/1. Theme API.md", "sourceDirName": "3-API/02_Extension APIs", @@ -1440,6 +1502,7 @@ exports[`site with custom sidebar items generator sidebarItemsGenerator is calle { "frontMatter": {}, "id": "API/api-end", + "isDraft": false, "sidebarPosition": 3, "source": "@site/docs/3-API/03_api-end.md", "sourceDirName": "3-API", @@ -1449,6 +1512,7 @@ exports[`site with custom sidebar items generator sidebarItemsGenerator is calle { "frontMatter": {}, "id": "API/api-overview", + "isDraft": false, "sidebarPosition": 0, "source": "@site/docs/3-API/00_api-overview.md", "sourceDirName": "3-API", @@ -1461,6 +1525,7 @@ exports[`site with custom sidebar items generator sidebarItemsGenerator is calle "sidebar_position": 1, }, "id": "Guides/guide1", + "isDraft": false, "sidebarPosition": 1, "source": "@site/docs/Guides/z-guide1.md", "sourceDirName": "Guides", @@ -1472,6 +1537,7 @@ exports[`site with custom sidebar items generator sidebarItemsGenerator is calle "id": "guide2", }, "id": "Guides/guide2", + "isDraft": false, "sidebarPosition": 2, "source": "@site/docs/Guides/02-guide2.md", "sourceDirName": "Guides", @@ -1484,6 +1550,7 @@ exports[`site with custom sidebar items generator sidebarItemsGenerator is calle "sidebar_position": 2.5, }, "id": "Guides/guide2.5", + "isDraft": false, "sidebarPosition": 2.5, "source": "@site/docs/Guides/0-guide2.5.md", "sourceDirName": "Guides", @@ -1496,6 +1563,7 @@ exports[`site with custom sidebar items generator sidebarItemsGenerator is calle "sidebar_position": 3, }, "id": "Guides/guide3", + "isDraft": false, "sidebarPosition": 3, "source": "@site/docs/Guides/guide3.md", "sourceDirName": "Guides", @@ -1507,6 +1575,7 @@ exports[`site with custom sidebar items generator sidebarItemsGenerator is calle "id": "guide4", }, "id": "Guides/guide4", + "isDraft": false, "sidebarPosition": undefined, "source": "@site/docs/Guides/a-guide4.md", "sourceDirName": "Guides", @@ -1518,6 +1587,7 @@ exports[`site with custom sidebar items generator sidebarItemsGenerator is calle "id": "guide5", }, "id": "Guides/guide5", + "isDraft": false, "sidebarPosition": undefined, "source": "@site/docs/Guides/b-guide5.md", "sourceDirName": "Guides", @@ -1527,6 +1597,7 @@ exports[`site with custom sidebar items generator sidebarItemsGenerator is calle { "frontMatter": {}, "id": "getting-started", + "isDraft": false, "sidebarPosition": 0, "source": "@site/docs/0-getting-started.md", "sourceDirName": ".", @@ -1536,6 +1607,7 @@ exports[`site with custom sidebar items generator sidebarItemsGenerator is calle { "frontMatter": {}, "id": "installation", + "isDraft": false, "sidebarPosition": 1, "source": "@site/docs/1-installation.md", "sourceDirName": ".", @@ -1563,6 +1635,7 @@ exports[`site with full autogenerated sidebar docs in fully generated sidebar ha "formattedLastUpdatedAt": undefined, "frontMatter": {}, "id": "getting-started", + "isDraft": false, "lastUpdatedAt": undefined, "lastUpdatedBy": undefined, "next": { @@ -1590,6 +1663,7 @@ exports[`site with full autogenerated sidebar docs in fully generated sidebar ha "formattedLastUpdatedAt": undefined, "frontMatter": {}, "id": "installation", + "isDraft": false, "lastUpdatedAt": undefined, "lastUpdatedBy": undefined, "next": { @@ -1623,6 +1697,7 @@ exports[`site with full autogenerated sidebar docs in fully generated sidebar ha "sidebar_position": 1, }, "id": "Guides/guide1", + "isDraft": false, "lastUpdatedAt": undefined, "lastUpdatedBy": undefined, "next": { @@ -1655,6 +1730,7 @@ exports[`site with full autogenerated sidebar docs in fully generated sidebar ha "id": "guide2", }, "id": "Guides/guide2", + "isDraft": false, "lastUpdatedAt": undefined, "lastUpdatedBy": undefined, "next": { @@ -1688,6 +1764,7 @@ exports[`site with full autogenerated sidebar docs in fully generated sidebar ha "sidebar_position": 2.5, }, "id": "Guides/guide2.5", + "isDraft": false, "lastUpdatedAt": undefined, "lastUpdatedBy": undefined, "next": { @@ -1721,6 +1798,7 @@ exports[`site with full autogenerated sidebar docs in fully generated sidebar ha "sidebar_position": 3, }, "id": "Guides/guide3", + "isDraft": false, "lastUpdatedAt": undefined, "lastUpdatedBy": undefined, "next": { @@ -1753,6 +1831,7 @@ exports[`site with full autogenerated sidebar docs in fully generated sidebar ha "id": "guide4", }, "id": "Guides/guide4", + "isDraft": false, "lastUpdatedAt": undefined, "lastUpdatedBy": undefined, "next": { @@ -1785,6 +1864,7 @@ exports[`site with full autogenerated sidebar docs in fully generated sidebar ha "id": "guide5", }, "id": "Guides/guide5", + "isDraft": false, "lastUpdatedAt": undefined, "lastUpdatedBy": undefined, "next": { @@ -1815,6 +1895,7 @@ exports[`site with full autogenerated sidebar docs in fully generated sidebar ha "formattedLastUpdatedAt": undefined, "frontMatter": {}, "id": "API/api-overview", + "isDraft": false, "lastUpdatedAt": undefined, "lastUpdatedBy": undefined, "next": { @@ -1845,6 +1926,7 @@ exports[`site with full autogenerated sidebar docs in fully generated sidebar ha "formattedLastUpdatedAt": undefined, "frontMatter": {}, "id": "API/Core APIs/Client API", + "isDraft": false, "lastUpdatedAt": undefined, "lastUpdatedBy": undefined, "next": { @@ -1875,6 +1957,7 @@ exports[`site with full autogenerated sidebar docs in fully generated sidebar ha "formattedLastUpdatedAt": undefined, "frontMatter": {}, "id": "API/Core APIs/Server API", + "isDraft": false, "lastUpdatedAt": undefined, "lastUpdatedBy": undefined, "next": { @@ -1905,6 +1988,7 @@ exports[`site with full autogenerated sidebar docs in fully generated sidebar ha "formattedLastUpdatedAt": undefined, "frontMatter": {}, "id": "API/Extension APIs/Plugin API", + "isDraft": false, "lastUpdatedAt": undefined, "lastUpdatedBy": undefined, "next": { @@ -1935,6 +2019,7 @@ exports[`site with full autogenerated sidebar docs in fully generated sidebar ha "formattedLastUpdatedAt": undefined, "frontMatter": {}, "id": "API/Extension APIs/Theme API", + "isDraft": false, "lastUpdatedAt": undefined, "lastUpdatedBy": undefined, "next": { @@ -1965,6 +2050,7 @@ exports[`site with full autogenerated sidebar docs in fully generated sidebar ha "formattedLastUpdatedAt": undefined, "frontMatter": {}, "id": "API/api-end", + "isDraft": false, "lastUpdatedAt": undefined, "lastUpdatedBy": undefined, "next": undefined, @@ -2144,6 +2230,7 @@ exports[`site with partial autogenerated sidebars docs in partially generated si "formattedLastUpdatedAt": undefined, "frontMatter": {}, "id": "API/api-end", + "isDraft": false, "lastUpdatedAt": undefined, "lastUpdatedBy": undefined, "next": { @@ -2171,6 +2258,7 @@ exports[`site with partial autogenerated sidebars docs in partially generated si "formattedLastUpdatedAt": undefined, "frontMatter": {}, "id": "API/api-overview", + "isDraft": false, "lastUpdatedAt": undefined, "lastUpdatedBy": undefined, "next": { @@ -2201,6 +2289,7 @@ exports[`site with partial autogenerated sidebars docs in partially generated si "formattedLastUpdatedAt": undefined, "frontMatter": {}, "id": "API/Extension APIs/Plugin API", + "isDraft": false, "lastUpdatedAt": undefined, "lastUpdatedBy": undefined, "next": { @@ -2231,6 +2320,7 @@ exports[`site with partial autogenerated sidebars docs in partially generated si "formattedLastUpdatedAt": undefined, "frontMatter": {}, "id": "API/Extension APIs/Theme API", + "isDraft": false, "lastUpdatedAt": undefined, "lastUpdatedBy": undefined, "next": undefined, @@ -2292,6 +2382,7 @@ exports[`versioned website (community) content 1`] = ` "title": "Team title translated", }, "id": "team", + "isDraft": false, "lastUpdatedAt": undefined, "lastUpdatedBy": undefined, "next": undefined, @@ -2316,6 +2407,7 @@ exports[`versioned website (community) content 2`] = ` "formattedLastUpdatedAt": undefined, "frontMatter": {}, "id": "version-1.0.0/team", + "isDraft": false, "lastUpdatedAt": undefined, "lastUpdatedBy": undefined, "next": undefined, @@ -2369,6 +2461,7 @@ exports[`versioned website (community) content: data 1`] = ` \\"tags\\": [], \\"version\\": \\"1.0.0\\", \\"frontMatter\\": {}, + \\"isDraft\\": false, \\"sidebar\\": \\"version-1.0.0/community\\" }", "site-i-18-n-en-docusaurus-plugin-content-docs-community-current-team-md-7e5.json": "{ @@ -2385,6 +2478,7 @@ exports[`versioned website (community) content: data 1`] = ` \\"frontMatter\\": { \\"title\\": \\"Team title translated\\" }, + \\"isDraft\\": false, \\"sidebar\\": \\"community\\" }", "version-1-0-0-metadata-prop-608.json": "{ @@ -2576,6 +2670,7 @@ exports[`versioned website content 1`] = ` ], }, "id": "foo/bar", + "isDraft": false, "lastUpdatedAt": undefined, "lastUpdatedBy": undefined, "next": { @@ -2616,6 +2711,7 @@ exports[`versioned website content 2`] = ` "formattedLastUpdatedAt": undefined, "frontMatter": {}, "id": "version-1.0.1/foo/bar", + "isDraft": false, "lastUpdatedAt": undefined, "lastUpdatedBy": undefined, "next": { @@ -2645,6 +2741,7 @@ exports[`versioned website content 3`] = ` "slug": "/", }, "id": "hello", + "isDraft": false, "lastUpdatedAt": undefined, "lastUpdatedBy": undefined, "next": undefined, @@ -2674,6 +2771,7 @@ exports[`versioned website content 4`] = ` "slug": "/", }, "id": "version-1.0.1/hello", + "isDraft": false, "lastUpdatedAt": undefined, "lastUpdatedBy": undefined, "next": undefined, @@ -2701,6 +2799,7 @@ exports[`versioned website content 5`] = ` "formattedLastUpdatedAt": undefined, "frontMatter": {}, "id": "version-1.0.0/foo/baz", + "isDraft": false, "lastUpdatedAt": undefined, "lastUpdatedBy": undefined, "next": { @@ -2864,6 +2963,7 @@ exports[`versioned website content: data 1`] = ` } ] }, + \\"isDraft\\": false, \\"sidebar\\": \\"docs\\", \\"next\\": { \\"title\\": \\"hello\\", @@ -2884,6 +2984,7 @@ exports[`versioned website content: data 1`] = ` \\"frontMatter\\": { \\"slug\\": \\"/\\" }, + \\"isDraft\\": false, \\"sidebar\\": \\"docs\\", \\"previous\\": { \\"title\\": \\"bar\\", @@ -2903,7 +3004,8 @@ exports[`versioned website content: data 1`] = ` \\"version\\": \\"current\\", \\"frontMatter\\": { \\"slug\\": \\"/absoluteSlug\\" - } + }, + \\"isDraft\\": false }", "site-docs-slugs-relative-slug-md-d1c.json": "{ \\"unversionedId\\": \\"slugs/relativeSlug\\", @@ -2918,7 +3020,8 @@ exports[`versioned website content: data 1`] = ` \\"version\\": \\"current\\", \\"frontMatter\\": { \\"slug\\": \\"relativeSlug\\" - } + }, + \\"isDraft\\": false }", "site-docs-slugs-resolved-slug-md-02b.json": "{ \\"unversionedId\\": \\"slugs/resolvedSlug\\", @@ -2933,7 +3036,8 @@ exports[`versioned website content: data 1`] = ` \\"version\\": \\"current\\", \\"frontMatter\\": { \\"slug\\": \\"./hey/ho/../resolvedSlug\\" - } + }, + \\"isDraft\\": false }", "site-docs-slugs-try-to-escape-slug-md-70d.json": "{ \\"unversionedId\\": \\"slugs/tryToEscapeSlug\\", @@ -2948,7 +3052,8 @@ exports[`versioned website content: data 1`] = ` \\"version\\": \\"current\\", \\"frontMatter\\": { \\"slug\\": \\"../../../../../../../../tryToEscapeSlug\\" - } + }, + \\"isDraft\\": false }", "site-i-18-n-en-docusaurus-plugin-content-docs-version-1-0-0-hello-md-fe5.json": "{ \\"unversionedId\\": \\"hello\\", @@ -2964,6 +3069,7 @@ exports[`versioned website content: data 1`] = ` \\"frontMatter\\": { \\"slug\\": \\"/\\" }, + \\"isDraft\\": false, \\"sidebar\\": \\"version-1.0.0/docs\\", \\"previous\\": { \\"title\\": \\"baz\\", @@ -2984,6 +3090,7 @@ exports[`versioned website content: data 1`] = ` \\"frontMatter\\": { \\"slug\\": \\"barSlug\\" }, + \\"isDraft\\": false, \\"sidebar\\": \\"version-1.0.0/docs\\", \\"next\\": { \\"title\\": \\"baz\\", @@ -3002,6 +3109,7 @@ exports[`versioned website content: data 1`] = ` \\"tags\\": [], \\"version\\": \\"1.0.0\\", \\"frontMatter\\": {}, + \\"isDraft\\": false, \\"sidebar\\": \\"version-1.0.0/docs\\", \\"previous\\": { \\"title\\": \\"bar\\", @@ -3024,6 +3132,7 @@ exports[`versioned website content: data 1`] = ` \\"tags\\": [], \\"version\\": \\"1.0.1\\", \\"frontMatter\\": {}, + \\"isDraft\\": false, \\"sidebar\\": \\"VersionedSideBarNameDoesNotMatter/docs\\", \\"next\\": { \\"title\\": \\"hello\\", @@ -3044,6 +3153,7 @@ exports[`versioned website content: data 1`] = ` \\"frontMatter\\": { \\"slug\\": \\"/\\" }, + \\"isDraft\\": false, \\"sidebar\\": \\"VersionedSideBarNameDoesNotMatter/docs\\", \\"previous\\": { \\"title\\": \\"bar\\", @@ -3064,6 +3174,7 @@ exports[`versioned website content: data 1`] = ` \\"frontMatter\\": { \\"slug\\": \\"/rootAbsoluteSlug\\" }, + \\"isDraft\\": false, \\"sidebar\\": \\"version-1.0.1/docs\\" }", "site-versioned-docs-version-with-slugs-root-relative-slug-md-32a.json": "{ @@ -3079,7 +3190,8 @@ exports[`versioned website content: data 1`] = ` \\"version\\": \\"withSlugs\\", \\"frontMatter\\": { \\"slug\\": \\"rootRelativeSlug\\" - } + }, + \\"isDraft\\": false }", "site-versioned-docs-version-with-slugs-root-resolved-slug-md-aee.json": "{ \\"unversionedId\\": \\"rootResolvedSlug\\", @@ -3094,7 +3206,8 @@ exports[`versioned website content: data 1`] = ` \\"version\\": \\"withSlugs\\", \\"frontMatter\\": { \\"slug\\": \\"./hey/ho/../rootResolvedSlug\\" - } + }, + \\"isDraft\\": false }", "site-versioned-docs-version-with-slugs-root-try-to-escape-slug-md-b5d.json": "{ \\"unversionedId\\": \\"rootTryToEscapeSlug\\", @@ -3109,7 +3222,8 @@ exports[`versioned website content: data 1`] = ` \\"version\\": \\"withSlugs\\", \\"frontMatter\\": { \\"slug\\": \\"../../../../../../../../rootTryToEscapeSlug\\" - } + }, + \\"isDraft\\": false }", "site-versioned-docs-version-with-slugs-slugs-absolute-slug-md-47a.json": "{ \\"unversionedId\\": \\"slugs/absoluteSlug\\", @@ -3124,7 +3238,8 @@ exports[`versioned website content: data 1`] = ` \\"version\\": \\"withSlugs\\", \\"frontMatter\\": { \\"slug\\": \\"/absoluteSlug\\" - } + }, + \\"isDraft\\": false }", "site-versioned-docs-version-with-slugs-slugs-relative-slug-md-a95.json": "{ \\"unversionedId\\": \\"slugs/relativeSlug\\", @@ -3139,7 +3254,8 @@ exports[`versioned website content: data 1`] = ` \\"version\\": \\"withSlugs\\", \\"frontMatter\\": { \\"slug\\": \\"relativeSlug\\" - } + }, + \\"isDraft\\": false }", "site-versioned-docs-version-with-slugs-slugs-resolved-slug-md-5a1.json": "{ \\"unversionedId\\": \\"slugs/resolvedSlug\\", @@ -3154,7 +3270,8 @@ exports[`versioned website content: data 1`] = ` \\"version\\": \\"withSlugs\\", \\"frontMatter\\": { \\"slug\\": \\"./hey/ho/../resolvedSlug\\" - } + }, + \\"isDraft\\": false }", "site-versioned-docs-version-with-slugs-slugs-try-to-escape-slug-md-4e1.json": "{ \\"unversionedId\\": \\"slugs/tryToEscapeSlug\\", @@ -3169,7 +3286,8 @@ exports[`versioned website content: data 1`] = ` \\"version\\": \\"withSlugs\\", \\"frontMatter\\": { \\"slug\\": \\"../../../../../../../../tryToEscapeSlug\\" - } + }, + \\"isDraft\\": false }", "tag-docs-next-tags-bar-tag-1-a8f.json": "{ \\"name\\": \\"barTag 1\\", 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 0623a345cc2f8..1948287063812 100644 --- a/packages/docusaurus-plugin-content-docs/src/__tests__/docs.test.ts +++ b/packages/docusaurus-plugin-content-docs/src/__tests__/docs.test.ts @@ -211,6 +211,7 @@ describe('simple site', () => { 'rootTryToEscapeSlug.md', 'headingAsTitle.md', 'doc with space.md', + 'draft.md', 'foo/bar.md', 'foo/baz.md', 'slugs/absoluteSlug.md', @@ -240,6 +241,7 @@ describe('simple site', () => { pagination_prev: null, }, tags: [], + isDraft: false, }); await defaultTestUtils.testMeta(path.join('hello.md'), { version: 'current', @@ -267,6 +269,7 @@ describe('simple site', () => { permalink: '/docs/tags/tag-3', }, ], + isDraft: false, }); }); @@ -316,6 +319,7 @@ describe('simple site', () => { permalink: '/docs/tags/tag2-custom-permalink', }, ], + isDraft: false, }); }); @@ -337,6 +341,7 @@ describe('simple site', () => { unrelated_front_matter: "won't be part of metadata", }, tags: [], + isDraft: false, }); }); @@ -389,6 +394,7 @@ describe('simple site', () => { permalink: '/docs/tags/tag2-custom-permalink', }, ], + isDraft: false, }); expect(editUrlFunction).toHaveBeenCalledTimes(1); @@ -434,6 +440,32 @@ describe('simple site', () => { formattedLastUpdatedAt: '10/14/2018', lastUpdatedBy: 'Author', tags: [], + isDraft: false, + }); + }); + + it('docs with draft frontmatter', async () => { + process.env.NODE_ENV = 'production'; + + const {defaultTestUtils} = await loadSite(); + + await defaultTestUtils.testMeta('draft.md', { + version: 'current', + id: 'draft', + unversionedId: 'draft', + sourceDirName: '.', + permalink: '/docs/draft', + sidebarPosition: undefined, + slug: '/draft', + title: 'draft', + editUrl: undefined, + formattedLastUpdatedAt: undefined, + description: 'This is a draft document', + frontMatter: { + draft: true, + }, + tags: [], + isDraft: true, }); }); @@ -617,6 +649,7 @@ describe('versioned site', () => { permalink: '/docs/next/tags/barTag-3-permalink', }, ], + isDraft: false, }); await currentVersionTestUtils.testMeta(path.join('hello.md'), { id: 'hello', @@ -631,6 +664,7 @@ describe('versioned site', () => { slug: '/', }, tags: [], + isDraft: false, }); }); @@ -648,6 +682,7 @@ describe('versioned site', () => { frontMatter: {slug: 'barSlug'}, version: '1.0.0', tags: [], + isDraft: false, }); await version100TestUtils.testMeta(path.join('hello.md'), { id: 'version-1.0.0/hello', @@ -664,6 +699,7 @@ describe('versioned site', () => { source: '@site/i18n/en/docusaurus-plugin-content-docs/version-1.0.0/hello.md', tags: [], + isDraft: false, }); await version101TestUtils.testMeta(path.join('foo', 'bar.md'), { id: 'version-1.0.1/foo/bar', @@ -676,6 +712,7 @@ describe('versioned site', () => { version: '1.0.1', frontMatter: {}, tags: [], + isDraft: false, }); await version101TestUtils.testMeta(path.join('hello.md'), { id: 'version-1.0.1/hello', @@ -690,6 +727,7 @@ describe('versioned site', () => { slug: '/', }, tags: [], + isDraft: false, }); }); @@ -786,6 +824,7 @@ describe('versioned site', () => { '@site/i18n/en/docusaurus-plugin-content-docs/version-1.0.0/hello.md', editUrl: hardcodedEditUrl, tags: [], + isDraft: false, }); expect(editUrlFunction).toHaveBeenCalledTimes(1); @@ -830,6 +869,7 @@ describe('versioned site', () => { editUrl: 'https://github.com/facebook/docusaurus/edit/main/website/versioned_docs/version-1.0.0/hello.md', tags: [], + isDraft: false, }); }); @@ -865,6 +905,7 @@ describe('versioned site', () => { editUrl: 'https://github.com/facebook/docusaurus/edit/main/website/docs/hello.md', tags: [], + isDraft: false, }); }); @@ -901,6 +942,7 @@ describe('versioned site', () => { editUrl: 'https://github.com/facebook/docusaurus/edit/main/website/i18n/fr/docusaurus-plugin-content-docs/version-1.0.0/hello.md', tags: [], + isDraft: false, }); }); @@ -938,6 +980,7 @@ describe('versioned site', () => { editUrl: 'https://github.com/facebook/docusaurus/edit/main/website/i18n/fr/docusaurus-plugin-content-docs/current/hello.md', tags: [], + isDraft: false, }); }); }); diff --git a/packages/docusaurus-plugin-content-docs/src/__tests__/frontMatter.test.ts b/packages/docusaurus-plugin-content-docs/src/__tests__/frontMatter.test.ts index 7e295afb0cb02..81276f48b3ae8 100644 --- a/packages/docusaurus-plugin-content-docs/src/__tests__/frontMatter.test.ts +++ b/packages/docusaurus-plugin-content-docs/src/__tests__/frontMatter.test.ts @@ -375,3 +375,19 @@ describe('toc min/max consistency', () => { ], }); }); + +describe('validateDocFrontMatter draft', () => { + testField({ + prefix: 'draft', + validFrontMatters: [{draft: true}, {draft: false}], + convertibleFrontMatter: [ + [{draft: 'true'}, {draft: true}], + [{draft: 'false'}, {draft: false}], + ], + invalidFrontMatters: [ + [{draft: 'yes'}, 'must be a boolean'], + [{draft: 'no'}, 'must be a boolean'], + [{draft: ''}, 'must be a boolean'], + ], + }); +}); diff --git a/packages/docusaurus-plugin-content-docs/src/docs.ts b/packages/docusaurus-plugin-content-docs/src/docs.ts index ee247ec0a97ad..de46ce3ea3b66 100644 --- a/packages/docusaurus-plugin-content-docs/src/docs.ts +++ b/packages/docusaurus-plugin-content-docs/src/docs.ts @@ -131,6 +131,9 @@ function doProcessDocMetadata({ } = parseMarkdownString(content); const frontMatter = validateDocFrontMatter(unsafeFrontMatter); + const isDraft = + (frontMatter.draft && process.env.NODE_ENV === 'production') || false; + const { custom_edit_url: customEditURL, @@ -260,6 +263,7 @@ function doProcessDocMetadata({ : undefined, sidebarPosition, frontMatter, + isDraft, }; } diff --git a/packages/docusaurus-plugin-content-docs/src/frontMatter.ts b/packages/docusaurus-plugin-content-docs/src/frontMatter.ts index 52e5af68b3830..5c7d3bc97dba7 100644 --- a/packages/docusaurus-plugin-content-docs/src/frontMatter.ts +++ b/packages/docusaurus-plugin-content-docs/src/frontMatter.ts @@ -38,6 +38,7 @@ const DocFrontMatterSchema = Joi.object({ parse_number_prefixes: Joi.boolean(), pagination_next: Joi.string().allow(null), pagination_prev: Joi.string().allow(null), + draft: Joi.boolean(), ...FrontMatterTOCHeadingLevels, }).unknown(); 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 92d375fc700ad..a72a6661dc907 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 @@ -345,6 +345,8 @@ declare module '@docusaurus/plugin-content-docs' { * @see {@link DocMetadata.prev} */ pagination_prev?: string | null; + /** Should this doc be excluded from production builds? */ + draft?: boolean; }; export type LastUpdateData = { @@ -404,6 +406,8 @@ declare module '@docusaurus/plugin-content-docs' { tags: Tag[]; /** Front matter, as-is. */ frontMatter: DocFrontMatter & {[key: string]: unknown}; + /** Is the doc going to be excluded from production builds? */ + isDraft: boolean; }; export type DocMetadata = DocMetadataBase & diff --git a/packages/docusaurus-plugin-content-docs/src/routes.ts b/packages/docusaurus-plugin-content-docs/src/routes.ts index 3ef6e60ba1464..c76783046aca1 100644 --- a/packages/docusaurus-plugin-content-docs/src/routes.ts +++ b/packages/docusaurus-plugin-content-docs/src/routes.ts @@ -70,31 +70,33 @@ export async function createDocRoutes({ docItemComponent: string; }): Promise { return Promise.all( - docs.map(async (metadataItem) => { - await actions.createData( - // Note that this created data path must be in sync with - // metadataPath provided to mdx-loader. - `${docuHash(metadataItem.source)}.json`, - JSON.stringify(metadataItem, null, 2), - ); + docs + .filter((metadataItem) => !metadataItem.isDraft) + .map(async (metadataItem) => { + await actions.createData( + // Note that this created data path must be in sync with + // metadataPath provided to mdx-loader. + `${docuHash(metadataItem.source)}.json`, + JSON.stringify(metadataItem, null, 2), + ); - const docRoute: RouteConfig = { - path: metadataItem.permalink, - component: docItemComponent, - exact: true, - modules: { - content: metadataItem.source, - }, - // Because the parent (DocPage) comp need to access it easily - // This permits to render the sidebar once without unmount/remount when - // navigating (and preserve sidebar state) - ...(metadataItem.sidebar && { - sidebar: metadataItem.sidebar, - }), - }; + const docRoute: RouteConfig = { + path: metadataItem.permalink, + component: docItemComponent, + exact: true, + modules: { + content: metadataItem.source, + }, + // Because the parent (DocPage) comp need to access it easily + // This permits to render the sidebar once without unmount/remount + // when navigating (and preserve sidebar state) + ...(metadataItem.sidebar && { + sidebar: metadataItem.sidebar, + }), + }; - return docRoute; - }), + return docRoute; + }), ); } diff --git a/packages/docusaurus-plugin-content-docs/src/sidebars/__tests__/generator.test.ts b/packages/docusaurus-plugin-content-docs/src/sidebars/__tests__/generator.test.ts index 66281f746b68b..840fc8607fc0c 100644 --- a/packages/docusaurus-plugin-content-docs/src/sidebars/__tests__/generator.test.ts +++ b/packages/docusaurus-plugin-content-docs/src/sidebars/__tests__/generator.test.ts @@ -505,4 +505,46 @@ describe('DefaultSidebarItemsGenerator', () => { - intro" `); }); + + it('excludes items for draft docs', async () => { + const sidebarSlice = await DefaultSidebarItemsGenerator({ + numberPrefixParser: DefaultNumberPrefixParser, + item: { + type: 'autogenerated', + dirName: '.', + }, + version: { + versionName: 'current', + contentPath: '', + }, + docs: [ + { + id: 'doc1', + source: 'doc1.md', + sourceDirName: '.', + sidebarPosition: 1, + frontMatter: { + draft: true, + }, + isDraft: true, + }, + { + id: 'doc2', + source: 'doc2.md', + sourceDirName: '.', + sidebarPosition: 2, + frontMatter: { + draft: false, + }, + isDraft: false, + }, + ], + options: { + sidebarCollapsed: true, + sidebarCollapsible: true, + }, + }); + + expect(sidebarSlice).toEqual([{type: 'doc', id: 'doc2'}] as Sidebar); + }); }); diff --git a/packages/docusaurus-plugin-content-docs/src/sidebars/__tests__/processor.test.ts b/packages/docusaurus-plugin-content-docs/src/sidebars/__tests__/processor.test.ts index 500eefbfe1dd5..deb654591f506 100644 --- a/packages/docusaurus-plugin-content-docs/src/sidebars/__tests__/processor.test.ts +++ b/packages/docusaurus-plugin-content-docs/src/sidebars/__tests__/processor.test.ts @@ -247,4 +247,33 @@ describe('processSidebars', () => { ], } as ProcessedSidebars); }); + + it('excludes items for draft docs', async () => { + const unprocessedSidebars: NormalizedSidebars = { + someSidebar: [ + {type: 'doc', id: 'doc1'}, + {type: 'doc', id: 'doc2'}, + ], + }; + + const processedSidebar = await testProcessSidebars( + unprocessedSidebars, + {}, + { + docs: [ + { + id: 'doc1', + isDraft: true, + }, + { + id: 'doc2', + isDraft: false, + }, + ], + }, + ); + expect(processedSidebar).toEqual({ + someSidebar: [{type: 'doc', id: 'doc2'}], + }); + }); }); diff --git a/packages/docusaurus-plugin-content-docs/src/sidebars/generator.ts b/packages/docusaurus-plugin-content-docs/src/sidebars/generator.ts index 4642897f3df48..115b1bd6c08b3 100644 --- a/packages/docusaurus-plugin-content-docs/src/sidebars/generator.ts +++ b/packages/docusaurus-plugin-content-docs/src/sidebars/generator.ts @@ -53,7 +53,8 @@ export const DefaultSidebarItemsGenerator: SidebarItemsGenerator = async ({ item: {dirName: autogenDir}, categoriesMetadata, }) => { - const docsById = createDocsByIdIndex(allDocs); + const visibleDocs = allDocs.filter((doc) => !doc.isDraft); + const docsById = createDocsByIdIndex(visibleDocs); const findDoc = (docId: string): SidebarItemsGeneratorDoc | undefined => docsById[docId]; const getDoc = (docId: string): SidebarItemsGeneratorDoc => { @@ -83,7 +84,7 @@ Available doc IDs: doc.sourceDirName.startsWith(addTrailingSlash(autogenDir)) ); } - const docs = allDocs.filter(isInAutogeneratedDir); + const docs = visibleDocs.filter(isInAutogeneratedDir); if (docs.length === 0) { logger.warn`No docs found in path=${autogenDir}: can't auto-generate a sidebar.`; diff --git a/packages/docusaurus-plugin-content-docs/src/sidebars/processor.ts b/packages/docusaurus-plugin-content-docs/src/sidebars/processor.ts index 7e83dd08a9217..7a943d9f08ec8 100644 --- a/packages/docusaurus-plugin-content-docs/src/sidebars/processor.ts +++ b/packages/docusaurus-plugin-content-docs/src/sidebars/processor.ts @@ -39,6 +39,7 @@ function toSidebarItemsGeneratorDoc( 'source', 'sourceDirName', 'sidebarPosition', + 'isDraft', ]); } @@ -95,6 +96,12 @@ async function processSidebar( if (item.type === 'autogenerated') { return processAutoGeneratedItem(item); } + if ( + item.type === 'doc' && + docs.find((doc) => doc.id === item.id)?.isDraft + ) { + return []; + } return [item]; } diff --git a/packages/docusaurus-plugin-content-docs/src/sidebars/types.ts b/packages/docusaurus-plugin-content-docs/src/sidebars/types.ts index 9f4d68a3ae45f..1908662635861 100644 --- a/packages/docusaurus-plugin-content-docs/src/sidebars/types.ts +++ b/packages/docusaurus-plugin-content-docs/src/sidebars/types.ts @@ -227,6 +227,7 @@ export type SidebarItemsGeneratorDoc = Pick< | 'source' | 'sourceDirName' | 'sidebarPosition' + | 'isDraft' >; export type SidebarItemsGeneratorVersion = Pick< VersionMetadata, diff --git a/website/_dogfooding/_docs tests/draft.md b/website/_dogfooding/_docs tests/draft.md new file mode 100644 index 0000000000000..6b43d6e58b85c --- /dev/null +++ b/website/_dogfooding/_docs tests/draft.md @@ -0,0 +1,7 @@ +--- +draft: true +--- + +# Draft test + +This page should only be visible in local development diff --git a/website/_dogfooding/_docs tests/tests/draft.md b/website/_dogfooding/_docs tests/tests/draft.md new file mode 100644 index 0000000000000..6b43d6e58b85c --- /dev/null +++ b/website/_dogfooding/_docs tests/tests/draft.md @@ -0,0 +1,7 @@ +--- +draft: true +--- + +# Draft test + +This page should only be visible in local development diff --git a/website/_dogfooding/docs-tests-sidebars.js b/website/_dogfooding/docs-tests-sidebars.js index 8043013199430..d274c0a6a33ee 100644 --- a/website/_dogfooding/docs-tests-sidebars.js +++ b/website/_dogfooding/docs-tests-sidebars.js @@ -109,6 +109,7 @@ const sidebars = { }, ], }, + 'draft', ], anotherSidebar: ['dummy'], }; diff --git a/website/docs/api/plugins/plugin-content-docs.md b/website/docs/api/plugins/plugin-content-docs.md index 7ef92f29f5b16..86642d6117b51 100644 --- a/website/docs/api/plugins/plugin-content-docs.md +++ b/website/docs/api/plugins/plugin-content-docs.md @@ -262,6 +262,7 @@ Accepted fields: | `image` | `string` | `undefined` | Cover or thumbnail image that will be used when displaying the link to your post. | | `slug` | `string` | File path | Allows to customize the document url (`//`). Support multiple patterns: `slug: my-doc`, `slug: /my/path/myDoc`, `slug: /`. | | `tags` | `Tag[]` | `undefined` | A list of strings or objects of two string fields `label` and `permalink` to tag to your docs. | +| `draft` | `boolean` | `false` | Whether to exclude this document from production builds and sidebars. |