From 6f2a68537cac98eb1885de8e42d104e3dae0331e Mon Sep 17 00:00:00 2001 From: Jody Heavener Date: Sun, 23 Jan 2022 20:50:59 -0400 Subject: [PATCH] feat(content-docs): exclude unlisted docs from sidebars --- .../__snapshots__/index.test.ts.snap | 117 +++++++++++++++--- .../src/__tests__/docFrontMatter.test.ts | 16 +++ .../src/__tests__/docs.test.ts | 18 +++ .../src/docFrontMatter.ts | 1 + .../src/docs.ts | 2 + .../src/sidebars/__tests__/generator.test.ts | 42 +++++++ .../src/sidebars/__tests__/processor.test.ts | 25 ++++ .../src/sidebars/generator.ts | 3 +- .../src/sidebars/processor.ts | 5 +- .../src/sidebars/types.ts | 1 + .../src/sidebars/utils.ts | 5 + .../src/types.ts | 2 + .../docs/api/plugins/plugin-content-docs.md | 1 + 13 files changed, 216 insertions(+), 22 deletions(-) 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 d6b6daa227613..88bc87f1ba1a2 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 @@ -45,6 +45,7 @@ Object { }, "id": "foo/baz", "isDraft": false, + "isUnlisted": false, "lastUpdatedAt": undefined, "lastUpdatedBy": undefined, "next": Object { @@ -94,6 +95,7 @@ Object { }, "id": "hello", "isDraft": false, + "isUnlisted": false, "lastUpdatedAt": undefined, "lastUpdatedBy": undefined, "next": undefined, @@ -137,6 +139,7 @@ Object { }, "id": "foo/bar", "isDraft": false, + "isUnlisted": false, "lastUpdatedAt": undefined, "lastUpdatedBy": undefined, "next": undefined, @@ -385,7 +388,8 @@ Object { \\"tags\\": [], \\"version\\": \\"current\\", \\"frontMatter\\": {}, - \\"isDraft\\": false + \\"isDraft\\": false, + \\"isUnlisted\\": false }", "site-docs-draft-md-5b1.json": "{ \\"unversionedId\\": \\"draft\\", @@ -401,7 +405,8 @@ Object { \\"frontMatter\\": { \\"draft\\": true }, - \\"isDraft\\": false + \\"isDraft\\": false, + \\"isUnlisted\\": false }", "site-docs-foo-bar-md-8c2.json": "{ \\"unversionedId\\": \\"foo/bar\\", @@ -422,6 +427,7 @@ Object { \\"pagination_prev\\": null }, \\"isDraft\\": false, + \\"isUnlisted\\": false, \\"sidebar\\": \\"docs\\" }", "site-docs-foo-baz-md-a69.json": "{ @@ -459,6 +465,7 @@ Object { ] }, \\"isDraft\\": false, + \\"isUnlisted\\": false, \\"sidebar\\": \\"docs\\", \\"previous\\": { \\"title\\": \\"Bar\\", @@ -482,6 +489,7 @@ Object { \\"version\\": \\"current\\", \\"frontMatter\\": {}, \\"isDraft\\": false, + \\"isUnlisted\\": false, \\"sidebar\\": \\"docs\\", \\"previous\\": { \\"title\\": \\"rootTryToEscapeSlug\\", @@ -523,6 +531,7 @@ Object { \\"slug\\": \\"/\\" }, \\"isDraft\\": false, + \\"isUnlisted\\": false, \\"sidebar\\": \\"docs\\", \\"previous\\": { \\"title\\": \\"My heading as title\\", @@ -544,7 +553,8 @@ Object { \\"frontMatter\\": { \\"custom_edit_url\\": null }, - \\"isDraft\\": false + \\"isDraft\\": false, + \\"isUnlisted\\": false }", "site-docs-lorem-md-b27.json": "{ \\"unversionedId\\": \\"lorem\\", @@ -562,7 +572,8 @@ Object { \\"custom_edit_url\\": \\"https://github.com/customUrl/docs/lorem.md\\", \\"unrelated_front_matter\\": \\"won't be part of metadata\\" }, - \\"isDraft\\": false + \\"isDraft\\": false, + \\"isUnlisted\\": false }", "site-docs-root-absolute-slug-md-db5.json": "{ \\"unversionedId\\": \\"rootAbsoluteSlug\\", @@ -581,6 +592,7 @@ Object { \\"pagination_prev\\": \\"foo/baz\\" }, \\"isDraft\\": false, + \\"isUnlisted\\": false, \\"sidebar\\": \\"docs\\", \\"previous\\": { \\"title\\": \\"baz pagination_label\\", @@ -608,6 +620,7 @@ Object { \\"pagination_prev\\": \\"foo/baz\\" }, \\"isDraft\\": false, + \\"isUnlisted\\": false, \\"sidebar\\": \\"docs\\", \\"previous\\": { \\"title\\": \\"baz pagination_label\\", @@ -635,6 +648,7 @@ Object { \\"pagination_prev\\": \\"foo/baz\\" }, \\"isDraft\\": false, + \\"isUnlisted\\": false, \\"sidebar\\": \\"docs\\", \\"previous\\": { \\"title\\": \\"baz pagination_label\\", @@ -662,6 +676,7 @@ Object { \\"pagination_prev\\": \\"foo/baz\\" }, \\"isDraft\\": false, + \\"isUnlisted\\": false, \\"sidebar\\": \\"docs\\", \\"previous\\": { \\"title\\": \\"baz pagination_label\\", @@ -686,7 +701,8 @@ Object { \\"frontMatter\\": { \\"slug\\": \\"/absoluteSlug\\" }, - \\"isDraft\\": false + \\"isDraft\\": false, + \\"isUnlisted\\": false }", "site-docs-slugs-relative-slug-md-d1c.json": "{ \\"unversionedId\\": \\"slugs/relativeSlug\\", @@ -702,7 +718,8 @@ Object { \\"frontMatter\\": { \\"slug\\": \\"relativeSlug\\" }, - \\"isDraft\\": false + \\"isDraft\\": false, + \\"isUnlisted\\": false }", "site-docs-slugs-resolved-slug-md-02b.json": "{ \\"unversionedId\\": \\"slugs/resolvedSlug\\", @@ -718,7 +735,8 @@ Object { \\"frontMatter\\": { \\"slug\\": \\"./hey/ho/../resolvedSlug\\" }, - \\"isDraft\\": false + \\"isDraft\\": false, + \\"isUnlisted\\": false }", "site-docs-slugs-try-to-escape-slug-md-70d.json": "{ \\"unversionedId\\": \\"slugs/tryToEscapeSlug\\", @@ -734,7 +752,8 @@ Object { \\"frontMatter\\": { \\"slug\\": \\"../../../../../../../../tryToEscapeSlug\\" }, - \\"isDraft\\": false + \\"isDraft\\": false, + \\"isUnlisted\\": false }", "tag-docs-tags-tag-1-b3f.json": "{ \\"name\\": \\"tag 1\\", @@ -1436,6 +1455,7 @@ Object { "frontMatter": Object {}, "id": "API/Core APIs/Client API", "isDraft": false, + "isUnlisted": false, "sidebarPosition": 0, "source": "@site/docs/3-API/01_Core APIs/0 --- Client API.md", "sourceDirName": "3-API/01_Core APIs", @@ -1445,6 +1465,7 @@ Object { "frontMatter": Object {}, "id": "API/Core APIs/Server API", "isDraft": false, + "isUnlisted": false, "sidebarPosition": 1, "source": "@site/docs/3-API/01_Core APIs/1 --- Server API.md", "sourceDirName": "3-API/01_Core APIs", @@ -1454,6 +1475,7 @@ Object { "frontMatter": Object {}, "id": "API/Extension APIs/Plugin API", "isDraft": false, + "isUnlisted": false, "sidebarPosition": 0, "source": "@site/docs/3-API/02_Extension APIs/0. Plugin API.md", "sourceDirName": "3-API/02_Extension APIs", @@ -1463,6 +1485,7 @@ Object { "frontMatter": Object {}, "id": "API/Extension APIs/Theme API", "isDraft": false, + "isUnlisted": false, "sidebarPosition": 1, "source": "@site/docs/3-API/02_Extension APIs/1. Theme API.md", "sourceDirName": "3-API/02_Extension APIs", @@ -1472,6 +1495,7 @@ Object { "frontMatter": Object {}, "id": "API/api-end", "isDraft": false, + "isUnlisted": false, "sidebarPosition": 3, "source": "@site/docs/3-API/03_api-end.md", "sourceDirName": "3-API", @@ -1481,6 +1505,7 @@ Object { "frontMatter": Object {}, "id": "API/api-overview", "isDraft": false, + "isUnlisted": false, "sidebarPosition": 0, "source": "@site/docs/3-API/00_api-overview.md", "sourceDirName": "3-API", @@ -1493,6 +1518,7 @@ Object { }, "id": "Guides/guide1", "isDraft": false, + "isUnlisted": false, "sidebarPosition": 1, "source": "@site/docs/Guides/z-guide1.md", "sourceDirName": "Guides", @@ -1504,6 +1530,7 @@ Object { }, "id": "Guides/guide2", "isDraft": false, + "isUnlisted": false, "sidebarPosition": 2, "source": "@site/docs/Guides/02-guide2.md", "sourceDirName": "Guides", @@ -1516,6 +1543,7 @@ Object { }, "id": "Guides/guide2.5", "isDraft": false, + "isUnlisted": false, "sidebarPosition": 2.5, "source": "@site/docs/Guides/0-guide2.5.md", "sourceDirName": "Guides", @@ -1528,6 +1556,7 @@ Object { }, "id": "Guides/guide3", "isDraft": false, + "isUnlisted": false, "sidebarPosition": 3, "source": "@site/docs/Guides/guide3.md", "sourceDirName": "Guides", @@ -1539,6 +1568,7 @@ Object { }, "id": "Guides/guide4", "isDraft": false, + "isUnlisted": false, "sidebarPosition": undefined, "source": "@site/docs/Guides/a-guide4.md", "sourceDirName": "Guides", @@ -1550,6 +1580,7 @@ Object { }, "id": "Guides/guide5", "isDraft": false, + "isUnlisted": false, "sidebarPosition": undefined, "source": "@site/docs/Guides/b-guide5.md", "sourceDirName": "Guides", @@ -1559,6 +1590,7 @@ Object { "frontMatter": Object {}, "id": "getting-started", "isDraft": false, + "isUnlisted": false, "sidebarPosition": 0, "source": "@site/docs/0-getting-started.md", "sourceDirName": ".", @@ -1568,6 +1600,7 @@ Object { "frontMatter": Object {}, "id": "installation", "isDraft": false, + "isUnlisted": false, "sidebarPosition": 1, "source": "@site/docs/1-installation.md", "sourceDirName": ".", @@ -1599,6 +1632,7 @@ Object { "frontMatter": Object {}, "id": "getting-started", "isDraft": false, + "isUnlisted": false, "lastUpdatedAt": undefined, "lastUpdatedBy": undefined, "next": Object { @@ -1627,6 +1661,7 @@ Object { "frontMatter": Object {}, "id": "installation", "isDraft": false, + "isUnlisted": false, "lastUpdatedAt": undefined, "lastUpdatedBy": undefined, "next": Object { @@ -1661,6 +1696,7 @@ Object { }, "id": "Guides/guide1", "isDraft": false, + "isUnlisted": false, "lastUpdatedAt": undefined, "lastUpdatedBy": undefined, "next": Object { @@ -1694,6 +1730,7 @@ Object { }, "id": "Guides/guide2", "isDraft": false, + "isUnlisted": false, "lastUpdatedAt": undefined, "lastUpdatedBy": undefined, "next": Object { @@ -1728,6 +1765,7 @@ Object { }, "id": "Guides/guide2.5", "isDraft": false, + "isUnlisted": false, "lastUpdatedAt": undefined, "lastUpdatedBy": undefined, "next": Object { @@ -1762,6 +1800,7 @@ Object { }, "id": "Guides/guide3", "isDraft": false, + "isUnlisted": false, "lastUpdatedAt": undefined, "lastUpdatedBy": undefined, "next": Object { @@ -1795,6 +1834,7 @@ Object { }, "id": "Guides/guide4", "isDraft": false, + "isUnlisted": false, "lastUpdatedAt": undefined, "lastUpdatedBy": undefined, "next": Object { @@ -1828,6 +1868,7 @@ Object { }, "id": "Guides/guide5", "isDraft": false, + "isUnlisted": false, "lastUpdatedAt": undefined, "lastUpdatedBy": undefined, "next": Object { @@ -1859,6 +1900,7 @@ Object { "frontMatter": Object {}, "id": "API/api-overview", "isDraft": false, + "isUnlisted": false, "lastUpdatedAt": undefined, "lastUpdatedBy": undefined, "next": Object { @@ -1890,6 +1932,7 @@ Object { "frontMatter": Object {}, "id": "API/Core APIs/Client API", "isDraft": false, + "isUnlisted": false, "lastUpdatedAt": undefined, "lastUpdatedBy": undefined, "next": Object { @@ -1921,6 +1964,7 @@ Object { "frontMatter": Object {}, "id": "API/Core APIs/Server API", "isDraft": false, + "isUnlisted": false, "lastUpdatedAt": undefined, "lastUpdatedBy": undefined, "next": Object { @@ -1952,6 +1996,7 @@ Object { "frontMatter": Object {}, "id": "API/Extension APIs/Plugin API", "isDraft": false, + "isUnlisted": false, "lastUpdatedAt": undefined, "lastUpdatedBy": undefined, "next": Object { @@ -1983,6 +2028,7 @@ Object { "frontMatter": Object {}, "id": "API/Extension APIs/Theme API", "isDraft": false, + "isUnlisted": false, "lastUpdatedAt": undefined, "lastUpdatedBy": undefined, "next": Object { @@ -2014,6 +2060,7 @@ Object { "frontMatter": Object {}, "id": "API/api-end", "isDraft": false, + "isUnlisted": false, "lastUpdatedAt": undefined, "lastUpdatedBy": undefined, "next": undefined, @@ -2194,6 +2241,7 @@ Object { "frontMatter": Object {}, "id": "API/api-end", "isDraft": false, + "isUnlisted": false, "lastUpdatedAt": undefined, "lastUpdatedBy": undefined, "next": Object { @@ -2222,6 +2270,7 @@ Object { "frontMatter": Object {}, "id": "API/api-overview", "isDraft": false, + "isUnlisted": false, "lastUpdatedAt": undefined, "lastUpdatedBy": undefined, "next": Object { @@ -2253,6 +2302,7 @@ Object { "frontMatter": Object {}, "id": "API/Extension APIs/Plugin API", "isDraft": false, + "isUnlisted": false, "lastUpdatedAt": undefined, "lastUpdatedBy": undefined, "next": Object { @@ -2284,6 +2334,7 @@ Object { "frontMatter": Object {}, "id": "API/Extension APIs/Theme API", "isDraft": false, + "isUnlisted": false, "lastUpdatedAt": undefined, "lastUpdatedBy": undefined, "next": undefined, @@ -2346,6 +2397,7 @@ Object { }, "id": "team", "isDraft": false, + "isUnlisted": false, "lastUpdatedAt": undefined, "lastUpdatedBy": undefined, "next": undefined, @@ -2371,6 +2423,7 @@ Object { "frontMatter": Object {}, "id": "version-1.0.0/team", "isDraft": false, + "isUnlisted": false, "lastUpdatedAt": undefined, "lastUpdatedBy": undefined, "next": undefined, @@ -2425,6 +2478,7 @@ Object { \\"version\\": \\"1.0.0\\", \\"frontMatter\\": {}, \\"isDraft\\": false, + \\"isUnlisted\\": false, \\"sidebar\\": \\"version-1.0.0/community\\" }", "site-i-18-n-en-docusaurus-plugin-content-docs-community-current-team-md-7e5.json": "{ @@ -2442,6 +2496,7 @@ Object { \\"title\\": \\"Team title translated\\" }, \\"isDraft\\": false, + \\"isUnlisted\\": false, \\"sidebar\\": \\"community\\" }", "version-1-0-0-metadata-prop-608.json": "{ @@ -2620,6 +2675,7 @@ Object { }, "id": "foo/bar", "isDraft": false, + "isUnlisted": false, "lastUpdatedAt": undefined, "lastUpdatedBy": undefined, "next": Object { @@ -2661,6 +2717,7 @@ Object { "frontMatter": Object {}, "id": "version-1.0.1/foo/bar", "isDraft": false, + "isUnlisted": false, "lastUpdatedAt": undefined, "lastUpdatedBy": undefined, "next": Object { @@ -2691,6 +2748,7 @@ Object { }, "id": "hello", "isDraft": false, + "isUnlisted": false, "lastUpdatedAt": undefined, "lastUpdatedBy": undefined, "next": undefined, @@ -2721,6 +2779,7 @@ Object { }, "id": "version-1.0.1/hello", "isDraft": false, + "isUnlisted": false, "lastUpdatedAt": undefined, "lastUpdatedBy": undefined, "next": undefined, @@ -2749,6 +2808,7 @@ Object { "frontMatter": Object {}, "id": "version-1.0.0/foo/baz", "isDraft": false, + "isUnlisted": false, "lastUpdatedAt": undefined, "lastUpdatedBy": undefined, "next": Object { @@ -2913,6 +2973,7 @@ Object { ] }, \\"isDraft\\": false, + \\"isUnlisted\\": false, \\"sidebar\\": \\"docs\\", \\"next\\": { \\"title\\": \\"hello\\", @@ -2934,6 +2995,7 @@ Object { \\"slug\\": \\"/\\" }, \\"isDraft\\": false, + \\"isUnlisted\\": false, \\"sidebar\\": \\"docs\\", \\"previous\\": { \\"title\\": \\"bar\\", @@ -2954,7 +3016,8 @@ Object { \\"frontMatter\\": { \\"slug\\": \\"/absoluteSlug\\" }, - \\"isDraft\\": false + \\"isDraft\\": false, + \\"isUnlisted\\": false }", "site-docs-slugs-relative-slug-md-d1c.json": "{ \\"unversionedId\\": \\"slugs/relativeSlug\\", @@ -2970,7 +3033,8 @@ Object { \\"frontMatter\\": { \\"slug\\": \\"relativeSlug\\" }, - \\"isDraft\\": false + \\"isDraft\\": false, + \\"isUnlisted\\": false }", "site-docs-slugs-resolved-slug-md-02b.json": "{ \\"unversionedId\\": \\"slugs/resolvedSlug\\", @@ -2986,7 +3050,8 @@ Object { \\"frontMatter\\": { \\"slug\\": \\"./hey/ho/../resolvedSlug\\" }, - \\"isDraft\\": false + \\"isDraft\\": false, + \\"isUnlisted\\": false }", "site-docs-slugs-try-to-escape-slug-md-70d.json": "{ \\"unversionedId\\": \\"slugs/tryToEscapeSlug\\", @@ -3002,7 +3067,8 @@ Object { \\"frontMatter\\": { \\"slug\\": \\"../../../../../../../../tryToEscapeSlug\\" }, - \\"isDraft\\": false + \\"isDraft\\": false, + \\"isUnlisted\\": false }", "site-i-18-n-en-docusaurus-plugin-content-docs-version-1-0-0-hello-md-fe5.json": "{ \\"unversionedId\\": \\"hello\\", @@ -3019,6 +3085,7 @@ Object { \\"slug\\": \\"/\\" }, \\"isDraft\\": false, + \\"isUnlisted\\": false, \\"sidebar\\": \\"version-1.0.0/docs\\", \\"previous\\": { \\"title\\": \\"baz\\", @@ -3040,6 +3107,7 @@ Object { \\"slug\\": \\"barSlug\\" }, \\"isDraft\\": false, + \\"isUnlisted\\": false, \\"sidebar\\": \\"version-1.0.0/docs\\", \\"next\\": { \\"title\\": \\"baz\\", @@ -3059,6 +3127,7 @@ Object { \\"version\\": \\"1.0.0\\", \\"frontMatter\\": {}, \\"isDraft\\": false, + \\"isUnlisted\\": false, \\"sidebar\\": \\"version-1.0.0/docs\\", \\"previous\\": { \\"title\\": \\"bar\\", @@ -3082,6 +3151,7 @@ Object { \\"version\\": \\"1.0.1\\", \\"frontMatter\\": {}, \\"isDraft\\": false, + \\"isUnlisted\\": false, \\"sidebar\\": \\"VersionedSideBarNameDoesNotMatter/docs\\", \\"next\\": { \\"title\\": \\"hello\\", @@ -3103,6 +3173,7 @@ Object { \\"slug\\": \\"/\\" }, \\"isDraft\\": false, + \\"isUnlisted\\": false, \\"sidebar\\": \\"VersionedSideBarNameDoesNotMatter/docs\\", \\"previous\\": { \\"title\\": \\"bar\\", @@ -3124,6 +3195,7 @@ Object { \\"slug\\": \\"/rootAbsoluteSlug\\" }, \\"isDraft\\": false, + \\"isUnlisted\\": false, \\"sidebar\\": \\"version-1.0.1/docs\\" }", "site-versioned-docs-version-with-slugs-root-relative-slug-md-32a.json": "{ @@ -3140,7 +3212,8 @@ Object { \\"frontMatter\\": { \\"slug\\": \\"rootRelativeSlug\\" }, - \\"isDraft\\": false + \\"isDraft\\": false, + \\"isUnlisted\\": false }", "site-versioned-docs-version-with-slugs-root-resolved-slug-md-aee.json": "{ \\"unversionedId\\": \\"rootResolvedSlug\\", @@ -3156,7 +3229,8 @@ Object { \\"frontMatter\\": { \\"slug\\": \\"./hey/ho/../rootResolvedSlug\\" }, - \\"isDraft\\": false + \\"isDraft\\": false, + \\"isUnlisted\\": false }", "site-versioned-docs-version-with-slugs-root-try-to-escape-slug-md-b5d.json": "{ \\"unversionedId\\": \\"rootTryToEscapeSlug\\", @@ -3172,7 +3246,8 @@ Object { \\"frontMatter\\": { \\"slug\\": \\"../../../../../../../../rootTryToEscapeSlug\\" }, - \\"isDraft\\": false + \\"isDraft\\": false, + \\"isUnlisted\\": false }", "site-versioned-docs-version-with-slugs-slugs-absolute-slug-md-47a.json": "{ \\"unversionedId\\": \\"slugs/absoluteSlug\\", @@ -3188,7 +3263,8 @@ Object { \\"frontMatter\\": { \\"slug\\": \\"/absoluteSlug\\" }, - \\"isDraft\\": false + \\"isDraft\\": false, + \\"isUnlisted\\": false }", "site-versioned-docs-version-with-slugs-slugs-relative-slug-md-a95.json": "{ \\"unversionedId\\": \\"slugs/relativeSlug\\", @@ -3204,7 +3280,8 @@ Object { \\"frontMatter\\": { \\"slug\\": \\"relativeSlug\\" }, - \\"isDraft\\": false + \\"isDraft\\": false, + \\"isUnlisted\\": false }", "site-versioned-docs-version-with-slugs-slugs-resolved-slug-md-5a1.json": "{ \\"unversionedId\\": \\"slugs/resolvedSlug\\", @@ -3220,7 +3297,8 @@ Object { \\"frontMatter\\": { \\"slug\\": \\"./hey/ho/../resolvedSlug\\" }, - \\"isDraft\\": false + \\"isDraft\\": false, + \\"isUnlisted\\": false }", "site-versioned-docs-version-with-slugs-slugs-try-to-escape-slug-md-4e1.json": "{ \\"unversionedId\\": \\"slugs/tryToEscapeSlug\\", @@ -3236,7 +3314,8 @@ Object { \\"frontMatter\\": { \\"slug\\": \\"../../../../../../../../tryToEscapeSlug\\" }, - \\"isDraft\\": false + \\"isDraft\\": false, + \\"isUnlisted\\": false }", "tag-docs-next-tags-bar-tag-1-a8f.json": "{ \\"name\\": \\"barTag 1\\", diff --git a/packages/docusaurus-plugin-content-docs/src/__tests__/docFrontMatter.test.ts b/packages/docusaurus-plugin-content-docs/src/__tests__/docFrontMatter.test.ts index e152e2afd457d..3f456a581f97e 100644 --- a/packages/docusaurus-plugin-content-docs/src/__tests__/docFrontMatter.test.ts +++ b/packages/docusaurus-plugin-content-docs/src/__tests__/docFrontMatter.test.ts @@ -375,3 +375,19 @@ describe('validateDocFrontMatter draft', () => { ], }); }); + +describe('validateDocFrontMatter unlisted', () => { + testField({ + prefix: 'unlisted', + validFrontMatters: [{unlisted: true}, {unlisted: false}], + convertibleFrontMatter: [ + [{unlisted: 'true'}, {unlisted: true}], + [{unlisted: 'false'}, {unlisted: false}], + ], + invalidFrontMatters: [ + [{unlisted: 'yes'}, 'must be a boolean'], + [{unlisted: 'no'}, 'must be a boolean'], + [{unlisted: ''}, 'must be a boolean'], + ], + }); +}); 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 0d67c267748c0..9ff17b33b5040 100644 --- a/packages/docusaurus-plugin-content-docs/src/__tests__/docs.test.ts +++ b/packages/docusaurus-plugin-content-docs/src/__tests__/docs.test.ts @@ -236,6 +236,7 @@ describe('simple site', () => { }, tags: [], isDraft: false, + isUnlisted: false, }); await defaultTestUtils.testMeta(path.join('hello.md'), { version: 'current', @@ -264,6 +265,7 @@ describe('simple site', () => { }, ], isDraft: false, + isUnlisted: false, }); }); @@ -314,6 +316,7 @@ describe('simple site', () => { }, ], isDraft: false, + isUnlisted: false, }); }); @@ -336,6 +339,7 @@ describe('simple site', () => { }, tags: [], isDraft: false, + isUnlisted: false, }); }); @@ -389,6 +393,7 @@ describe('simple site', () => { }, ], isDraft: false, + isUnlisted: false, }); expect(editUrlFunction).toHaveBeenCalledTimes(1); @@ -435,6 +440,7 @@ describe('simple site', () => { lastUpdatedBy: 'Author', tags: [], isDraft: false, + isUnlisted: false, }); }); @@ -460,6 +466,7 @@ describe('simple site', () => { }, tags: [], isDraft: true, + isUnlisted: false, }); }); @@ -643,6 +650,7 @@ describe('versioned site', () => { }, ], isDraft: false, + isUnlisted: false, }); await currentVersionTestUtils.testMeta(path.join('hello.md'), { id: 'hello', @@ -658,6 +666,7 @@ describe('versioned site', () => { }, tags: [], isDraft: false, + isUnlisted: false, }); }); @@ -676,6 +685,7 @@ describe('versioned site', () => { version: '1.0.0', tags: [], isDraft: false, + isUnlisted: false, }); await version100TestUtils.testMeta(path.join('hello.md'), { id: 'version-1.0.0/hello', @@ -693,6 +703,7 @@ describe('versioned site', () => { '@site/i18n/en/docusaurus-plugin-content-docs/version-1.0.0/hello.md', tags: [], isDraft: false, + isUnlisted: false, }); await version101TestUtils.testMeta(path.join('foo', 'bar.md'), { id: 'version-1.0.1/foo/bar', @@ -706,6 +717,7 @@ describe('versioned site', () => { frontMatter: {}, tags: [], isDraft: false, + isUnlisted: false, }); await version101TestUtils.testMeta(path.join('hello.md'), { id: 'version-1.0.1/hello', @@ -721,6 +733,7 @@ describe('versioned site', () => { }, tags: [], isDraft: false, + isUnlisted: false, }); }); @@ -818,6 +831,7 @@ describe('versioned site', () => { editUrl: hardcodedEditUrl, tags: [], isDraft: false, + isUnlisted: false, }); expect(editUrlFunction).toHaveBeenCalledTimes(1); @@ -863,6 +877,7 @@ describe('versioned site', () => { 'https://github.com/facebook/docusaurus/edit/main/website/versioned_docs/version-1.0.0/hello.md', tags: [], isDraft: false, + isUnlisted: false, }); }); @@ -899,6 +914,7 @@ describe('versioned site', () => { 'https://github.com/facebook/docusaurus/edit/main/website/docs/hello.md', tags: [], isDraft: false, + isUnlisted: false, }); }); @@ -936,6 +952,7 @@ describe('versioned site', () => { 'https://github.com/facebook/docusaurus/edit/main/website/i18n/fr/docusaurus-plugin-content-docs/version-1.0.0/hello.md', tags: [], isDraft: false, + isUnlisted: false, }); }); @@ -974,6 +991,7 @@ describe('versioned site', () => { 'https://github.com/facebook/docusaurus/edit/main/website/i18n/fr/docusaurus-plugin-content-docs/current/hello.md', tags: [], isDraft: false, + isUnlisted: false, }); }); }); diff --git a/packages/docusaurus-plugin-content-docs/src/docFrontMatter.ts b/packages/docusaurus-plugin-content-docs/src/docFrontMatter.ts index 17735376d9349..749e1db529096 100644 --- a/packages/docusaurus-plugin-content-docs/src/docFrontMatter.ts +++ b/packages/docusaurus-plugin-content-docs/src/docFrontMatter.ts @@ -38,6 +38,7 @@ const DocFrontMatterSchema = Joi.object({ pagination_next: Joi.string().allow(null), pagination_prev: Joi.string().allow(null), draft: Joi.boolean(), + unlisted: Joi.boolean(), ...FrontMatterTOCHeadingLevels, }).unknown(); diff --git a/packages/docusaurus-plugin-content-docs/src/docs.ts b/packages/docusaurus-plugin-content-docs/src/docs.ts index 92db958400fe5..c4bbfefe15ac4 100644 --- a/packages/docusaurus-plugin-content-docs/src/docs.ts +++ b/packages/docusaurus-plugin-content-docs/src/docs.ts @@ -138,6 +138,7 @@ function doProcessDocMetadata({ const isDraft = (frontMatter.draft && process.env.NODE_ENV === 'production') || false; + const isUnlisted = frontMatter.unlisted || false; const { custom_edit_url: customEditURL, @@ -269,6 +270,7 @@ function doProcessDocMetadata({ sidebarPosition, frontMatter, isDraft, + isUnlisted, }; } 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 1bff5f835e610..2e7892801df6a 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 @@ -652,4 +652,46 @@ describe('DefaultSidebarItemsGenerator', () => { expect(sidebarSlice).toEqual([{type: 'doc', id: 'doc2'}] as Sidebar); }); + + test('excludes items for unlisted 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: { + unlisted: true, + }, + isUnlisted: true, + }, + { + id: 'doc2', + source: 'doc2.md', + sourceDirName: '.', + sidebarPosition: 2, + frontMatter: { + unlisted: false, + }, + isUnlisted: 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 9712abffa0d43..fdedb98b524c9 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 @@ -332,4 +332,29 @@ describe('processSidebars', () => { someSidebar: [{type: 'doc', id: 'doc2'}], }); }); + + test('excludes items for unlisted docs', async () => { + const unprocessedSidebars: NormalizedSidebars = { + someSidebar: [ + {type: 'doc', id: 'doc1'}, + {type: 'doc', id: 'doc2'}, + ], + }; + + const processedSidebar = await testProcessSidebars(unprocessedSidebars, { + docs: [ + { + id: 'doc1', + isUnlisted: true, + }, + { + id: 'doc2', + isUnlisted: 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 1fe163db815df..800fa4efdb913 100644 --- a/packages/docusaurus-plugin-content-docs/src/sidebars/generator.ts +++ b/packages/docusaurus-plugin-content-docs/src/sidebars/generator.ts @@ -18,6 +18,7 @@ import {addTrailingSlash, posixPath} from '@docusaurus/utils'; import logger from '@docusaurus/logger'; import path from 'path'; import {createDocsByIdIndex, toCategoryIndexMatcherParam} from '../docs'; +import {docIsInvisible} from './utils'; const BreadcrumbSeparator = '/'; // To avoid possible name clashes with a folder of the same name as the ID @@ -52,7 +53,7 @@ export const DefaultSidebarItemsGenerator: SidebarItemsGenerator = async ({ item: {dirName: autogenDir}, categoriesMetadata, }) => { - const visibleDocs = allDocs.filter((doc) => !doc.isDraft); + const visibleDocs = allDocs.filter((doc) => !docIsInvisible(doc)); const docsById = createDocsByIdIndex(visibleDocs); const findDoc = (docId: string): SidebarItemsGeneratorDoc | undefined => docsById[docId]; diff --git a/packages/docusaurus-plugin-content-docs/src/sidebars/processor.ts b/packages/docusaurus-plugin-content-docs/src/sidebars/processor.ts index 951ad8de5c12f..5c7b023b21427 100644 --- a/packages/docusaurus-plugin-content-docs/src/sidebars/processor.ts +++ b/packages/docusaurus-plugin-content-docs/src/sidebars/processor.ts @@ -21,7 +21,7 @@ import type { SidebarItemAutogenerated, CategoryMetadataFile, } from './types'; -import {transformSidebarItems} from './utils'; +import {docIsInvisible, transformSidebarItems} from './utils'; import {DefaultSidebarItemsGenerator} from './generator'; import {mapValues, memoize, pick} from 'lodash'; import combinePromises from 'combine-promises'; @@ -54,6 +54,7 @@ function toSidebarItemsGeneratorDoc( 'sourceDirName', 'sidebarPosition', 'isDraft', + 'isUnlisted', ]); } @@ -157,7 +158,7 @@ async function processSidebar( } if ( item.type === 'doc' && - docs.find((doc) => doc.id === item.id)?.isDraft + docIsInvisible(docs.find((doc) => doc.id === item.id)) ) { return []; } diff --git a/packages/docusaurus-plugin-content-docs/src/sidebars/types.ts b/packages/docusaurus-plugin-content-docs/src/sidebars/types.ts index fe5de194e291e..afc379ee3029d 100644 --- a/packages/docusaurus-plugin-content-docs/src/sidebars/types.ts +++ b/packages/docusaurus-plugin-content-docs/src/sidebars/types.ts @@ -214,6 +214,7 @@ export type SidebarItemsGeneratorDoc = Pick< | 'sourceDirName' | 'sidebarPosition' | 'isDraft' + | 'isUnlisted' >; export type SidebarItemsGeneratorVersion = Pick< VersionMetadata, diff --git a/packages/docusaurus-plugin-content-docs/src/sidebars/utils.ts b/packages/docusaurus-plugin-content-docs/src/sidebars/utils.ts index 7b2e902fad43f..ebfc2d2c0b1c1 100644 --- a/packages/docusaurus-plugin-content-docs/src/sidebars/utils.ts +++ b/packages/docusaurus-plugin-content-docs/src/sidebars/utils.ts @@ -17,6 +17,7 @@ import type { SidebarItemConfig, SidebarItemCategoryWithGeneratedIndex, SidebarNavigationItem, + SidebarItemsGeneratorDoc, } from './types'; import {mapValues, difference, uniq} from 'lodash'; @@ -391,3 +392,7 @@ export function toNavigationLink( } throw new Error('unexpected navigation item'); } + +export function docIsInvisible(doc?: SidebarItemsGeneratorDoc): boolean { + return doc ? doc.isDraft || doc.isUnlisted : false; +} diff --git a/packages/docusaurus-plugin-content-docs/src/types.ts b/packages/docusaurus-plugin-content-docs/src/types.ts index eed718f5ef002..e80316c248e79 100644 --- a/packages/docusaurus-plugin-content-docs/src/types.ts +++ b/packages/docusaurus-plugin-content-docs/src/types.ts @@ -75,6 +75,7 @@ export type DocFrontMatter = { pagination_next?: string | null; pagination_prev?: string | null; draft?: boolean; + unlisted?: boolean; }; export type DocMetadataBase = LastUpdateData & { @@ -92,6 +93,7 @@ export type DocMetadataBase = LastUpdateData & { tags: Tag[]; frontMatter: DocFrontMatter & Record; isDraft: boolean; + isUnlisted: boolean; }; export type DocNavLink = { diff --git a/website/docs/api/plugins/plugin-content-docs.md b/website/docs/api/plugins/plugin-content-docs.md index 3bb140f556125..c5ccf33c62cb1 100644 --- a/website/docs/api/plugins/plugin-content-docs.md +++ b/website/docs/api/plugins/plugin-content-docs.md @@ -234,6 +234,7 @@ Accepted fields: | `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. | +| `unlisted` | `boolean` | `false` | Whether to exclude this document from sidebars, while remaining accessible with the direct URL. |