feat(content-docs): new front matter options to customize pagination (#5705)

This commit is contained in:
Joshua Chen 2021-10-21 18:27:57 +08:00 committed by GitHub
parent 29d13351a4
commit 3127f12654
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
15 changed files with 489 additions and 95 deletions

View file

@ -1,5 +1,7 @@
---
slug: /rootAbsoluteSlug
pagination_next: headingAsTitle
pagination_prev: foo/baz
---
Lorem

View file

@ -1,5 +1,7 @@
---
slug: rootRelativeSlug
pagination_next: headingAsTitle
pagination_prev: foo/baz
---
Lorem

View file

@ -1,5 +1,7 @@
---
slug: ./hey/ho/../rootResolvedSlug
pagination_next: headingAsTitle
pagination_prev: foo/baz
---
Lorem

View file

@ -1,5 +1,7 @@
---
slug: ../../../../../../../../rootTryToEscapeSlug
pagination_next: headingAsTitle
pagination_prev: foo/baz
---
Lorem

View file

@ -4,7 +4,21 @@
{
"type": "category",
"label": "foo",
"items": ["foo/bar", "foo/baz"]
"items": ["foo/bar", "foo/baz"]
},
{
"type": "category",
"label": "Slugs",
"items": [
"rootAbsoluteSlug",
"rootRelativeSlug",
"rootResolvedSlug",
"rootTryToEscapeSlug"
]
},
{
"type": "doc",
"id": "headingAsTitle"
},
{
"type": "link",

View file

@ -23,6 +23,34 @@ Object {
"label": "foo",
"type": "category",
},
Object {
"collapsed": true,
"collapsible": true,
"items": Array [
Object {
"id": "version-1.0.0/rootAbsoluteSlug",
"type": "doc",
},
Object {
"id": "version-1.0.0/rootRelativeSlug",
"type": "doc",
},
Object {
"id": "version-1.0.0/rootResolvedSlug",
"type": "doc",
},
Object {
"id": "version-1.0.0/rootTryToEscapeSlug",
"type": "doc",
},
],
"label": "Slugs",
"type": "category",
},
Object {
"id": "version-1.0.0/headingAsTitle",
"type": "doc",
},
Object {
"href": "https://github.com",
"label": "Github",

View file

@ -0,0 +1,140 @@
// Jest Snapshot v1, https://goo.gl/fbAQLP
exports[`simple site custom pagination 1`] = `
Array [
Array [
Object {
"permalink": "/docs/rootTryToEscapeSlug",
"title": "rootTryToEscapeSlug",
},
Object {
"permalink": "/docs/foo/bazSlug.html",
"title": "baz pagination_label",
},
],
Array [
Object {
"permalink": "/docs/foo/bar",
"title": "Bar",
},
Object {
"permalink": "/docs/absoluteSlug",
"title": "absoluteSlug",
},
],
Array [
undefined,
Object {
"permalink": "/docs/hello",
"title": "Hello sidebar_label",
},
],
Array [
Object {
"permalink": "/docs/headingAsTitle",
"title": "My heading as title",
},
Object {
"permalink": "/docs/ipsum",
"title": "ipsum",
},
],
Array [
Object {
"permalink": "/docs/hello",
"title": "Hello sidebar_label",
},
Object {
"permalink": "/docs/lorem",
"title": "lorem",
},
],
Array [
Object {
"permalink": "/docs/ipsum",
"title": "ipsum",
},
Object {
"permalink": "/docs/rootAbsoluteSlug",
"title": "rootAbsoluteSlug",
},
],
Array [
Object {
"permalink": "/docs/foo/bazSlug.html",
"title": "baz pagination_label",
},
Object {
"permalink": "/docs/headingAsTitle",
"title": "My heading as title",
},
],
Array [
Object {
"permalink": "/docs/foo/bazSlug.html",
"title": "baz pagination_label",
},
Object {
"permalink": "/docs/headingAsTitle",
"title": "My heading as title",
},
],
Array [
Object {
"permalink": "/docs/foo/bazSlug.html",
"title": "baz pagination_label",
},
Object {
"permalink": "/docs/headingAsTitle",
"title": "My heading as title",
},
],
Array [
Object {
"permalink": "/docs/foo/bazSlug.html",
"title": "baz pagination_label",
},
Object {
"permalink": "/docs/headingAsTitle",
"title": "My heading as title",
},
],
Array [
Object {
"permalink": "/docs/foo/bazSlug.html",
"title": "baz pagination_label",
},
Object {
"permalink": "/docs/slugs/relativeSlug",
"title": "relativeSlug",
},
],
Array [
Object {
"permalink": "/docs/absoluteSlug",
"title": "absoluteSlug",
},
Object {
"permalink": "/docs/slugs/hey/resolvedSlug",
"title": "resolvedSlug",
},
],
Array [
Object {
"permalink": "/docs/slugs/relativeSlug",
"title": "relativeSlug",
},
Object {
"permalink": "/docs/tryToEscapeSlug",
"title": "tryToEscapeSlug",
},
],
Array [
Object {
"permalink": "/docs/slugs/hey/resolvedSlug",
"title": "resolvedSlug",
},
undefined,
],
]
`;

View file

@ -45,6 +45,34 @@ Object {
"label": "foo",
"type": "category",
},
Object {
"collapsed": true,
"collapsible": true,
"items": Array [
Object {
"id": "rootAbsoluteSlug",
"type": "doc",
},
Object {
"id": "rootRelativeSlug",
"type": "doc",
},
Object {
"id": "rootResolvedSlug",
"type": "doc",
},
Object {
"id": "rootTryToEscapeSlug",
"type": "doc",
},
],
"label": "Slugs",
"type": "category",
},
Object {
"id": "headingAsTitle",
"type": "doc",
},
Object {
"href": "https://github.com",
"label": "Github",
@ -95,7 +123,7 @@ Object {
Object {
"id": "headingAsTitle",
"path": "/docs/headingAsTitle",
"sidebar": undefined,
"sidebar": "docs",
},
Object {
"id": "hello",
@ -115,22 +143,22 @@ Object {
Object {
"id": "rootAbsoluteSlug",
"path": "/docs/rootAbsoluteSlug",
"sidebar": undefined,
"sidebar": "docs",
},
Object {
"id": "rootRelativeSlug",
"path": "/docs/rootRelativeSlug",
"sidebar": undefined,
"sidebar": "docs",
},
Object {
"id": "rootResolvedSlug",
"path": "/docs/hey/rootResolvedSlug",
"sidebar": undefined,
"sidebar": "docs",
},
Object {
"id": "rootTryToEscapeSlug",
"path": "/docs/rootTryToEscapeSlug",
"sidebar": undefined,
"sidebar": "docs",
},
Object {
"id": "slugs/absoluteSlug",
@ -231,8 +259,8 @@ Object {
\\"permalink\\": \\"/docs/foo/bar\\"
},
\\"next\\": {
\\"title\\": \\"Hello sidebar_label\\",
\\"permalink\\": \\"/docs/\\"
\\"title\\": \\"rootAbsoluteSlug\\",
\\"permalink\\": \\"/docs/rootAbsoluteSlug\\"
}
}",
"site-docs-heading-as-title-md-c6d.json": "{
@ -247,7 +275,16 @@ Object {
\\"permalink\\": \\"/docs/headingAsTitle\\",
\\"tags\\": [],
\\"version\\": \\"current\\",
\\"frontMatter\\": {}
\\"frontMatter\\": {},
\\"sidebar\\": \\"docs\\",
\\"previous\\": {
\\"title\\": \\"rootTryToEscapeSlug\\",
\\"permalink\\": \\"/docs/rootTryToEscapeSlug\\"
},
\\"next\\": {
\\"title\\": \\"Hello sidebar_label\\",
\\"permalink\\": \\"/docs/\\"
}
}",
"site-docs-hello-md-9df.json": "{
\\"unversionedId\\": \\"hello\\",
@ -281,8 +318,8 @@ Object {
},
\\"sidebar\\": \\"docs\\",
\\"previous\\": {
\\"title\\": \\"baz pagination_label\\",
\\"permalink\\": \\"/docs/foo/bazSlug.html\\"
\\"title\\": \\"My heading as title\\",
\\"permalink\\": \\"/docs/headingAsTitle\\"
}
}",
"site-docs-ipsum-md-c61.json": "{
@ -333,7 +370,18 @@ Object {
\\"tags\\": [],
\\"version\\": \\"current\\",
\\"frontMatter\\": {
\\"slug\\": \\"/rootAbsoluteSlug\\"
\\"slug\\": \\"/rootAbsoluteSlug\\",
\\"pagination_next\\": \\"headingAsTitle\\",
\\"pagination_prev\\": \\"foo/baz\\"
},
\\"sidebar\\": \\"docs\\",
\\"previous\\": {
\\"title\\": \\"baz pagination_label\\",
\\"permalink\\": \\"/docs/foo/bazSlug.html\\"
},
\\"next\\": {
\\"title\\": \\"My heading as title\\",
\\"permalink\\": \\"/docs/headingAsTitle\\"
}
}",
"site-docs-root-relative-slug-md-3dd.json": "{
@ -349,7 +397,18 @@ Object {
\\"tags\\": [],
\\"version\\": \\"current\\",
\\"frontMatter\\": {
\\"slug\\": \\"rootRelativeSlug\\"
\\"slug\\": \\"rootRelativeSlug\\",
\\"pagination_next\\": \\"headingAsTitle\\",
\\"pagination_prev\\": \\"foo/baz\\"
},
\\"sidebar\\": \\"docs\\",
\\"previous\\": {
\\"title\\": \\"baz pagination_label\\",
\\"permalink\\": \\"/docs/foo/bazSlug.html\\"
},
\\"next\\": {
\\"title\\": \\"My heading as title\\",
\\"permalink\\": \\"/docs/headingAsTitle\\"
}
}",
"site-docs-root-resolved-slug-md-4d1.json": "{
@ -365,7 +424,18 @@ Object {
\\"tags\\": [],
\\"version\\": \\"current\\",
\\"frontMatter\\": {
\\"slug\\": \\"./hey/ho/../rootResolvedSlug\\"
\\"slug\\": \\"./hey/ho/../rootResolvedSlug\\",
\\"pagination_next\\": \\"headingAsTitle\\",
\\"pagination_prev\\": \\"foo/baz\\"
},
\\"sidebar\\": \\"docs\\",
\\"previous\\": {
\\"title\\": \\"baz pagination_label\\",
\\"permalink\\": \\"/docs/foo/bazSlug.html\\"
},
\\"next\\": {
\\"title\\": \\"My heading as title\\",
\\"permalink\\": \\"/docs/headingAsTitle\\"
}
}",
"site-docs-root-try-to-escape-slug-md-9ee.json": "{
@ -381,7 +451,18 @@ Object {
\\"tags\\": [],
\\"version\\": \\"current\\",
\\"frontMatter\\": {
\\"slug\\": \\"../../../../../../../../rootTryToEscapeSlug\\"
\\"slug\\": \\"../../../../../../../../rootTryToEscapeSlug\\",
\\"pagination_next\\": \\"headingAsTitle\\",
\\"pagination_prev\\": \\"foo/baz\\"
},
\\"sidebar\\": \\"docs\\",
\\"previous\\": {
\\"title\\": \\"baz pagination_label\\",
\\"permalink\\": \\"/docs/foo/bazSlug.html\\"
},
\\"next\\": {
\\"title\\": \\"My heading as title\\",
\\"permalink\\": \\"/docs/headingAsTitle\\"
}
}",
"site-docs-slugs-absolute-slug-md-4e8.json": "{
@ -544,6 +625,39 @@ Object {
\\"collapsible\\": true,
\\"collapsed\\": true
},
{
\\"type\\": \\"category\\",
\\"label\\": \\"Slugs\\",
\\"items\\": [
{
\\"type\\": \\"link\\",
\\"label\\": \\"rootAbsoluteSlug\\",
\\"href\\": \\"/docs/rootAbsoluteSlug\\"
},
{
\\"type\\": \\"link\\",
\\"label\\": \\"rootRelativeSlug\\",
\\"href\\": \\"/docs/rootRelativeSlug\\"
},
{
\\"type\\": \\"link\\",
\\"label\\": \\"rootResolvedSlug\\",
\\"href\\": \\"/docs/hey/rootResolvedSlug\\"
},
{
\\"type\\": \\"link\\",
\\"label\\": \\"rootTryToEscapeSlug\\",
\\"href\\": \\"/docs/rootTryToEscapeSlug\\"
}
],
\\"collapsible\\": true,
\\"collapsed\\": true
},
{
\\"type\\": \\"link\\",
\\"label\\": \\"My heading as title\\",
\\"href\\": \\"/docs/headingAsTitle\\"
},
{
\\"type\\": \\"link\\",
\\"label\\": \\"Github\\",
@ -596,7 +710,7 @@ Object {
Object {
"id": "headingAsTitle",
"path": "/docs/headingAsTitle",
"sidebar": undefined,
"sidebar": "docs",
},
Object {
"id": "hello",
@ -616,22 +730,22 @@ Object {
Object {
"id": "rootAbsoluteSlug",
"path": "/docs/rootAbsoluteSlug",
"sidebar": undefined,
"sidebar": "docs",
},
Object {
"id": "rootRelativeSlug",
"path": "/docs/rootRelativeSlug",
"sidebar": undefined,
"sidebar": "docs",
},
Object {
"id": "rootResolvedSlug",
"path": "/docs/hey/rootResolvedSlug",
"sidebar": undefined,
"sidebar": "docs",
},
Object {
"id": "rootTryToEscapeSlug",
"path": "/docs/rootTryToEscapeSlug",
"sidebar": undefined,
"sidebar": "docs",
},
Object {
"id": "slugs/absoluteSlug",
@ -751,6 +865,7 @@ Array [
"content": "@site/docs/headingAsTitle.md",
},
"path": "/docs/headingAsTitle",
"sidebar": "docs",
},
Object {
"component": "@theme/DocItem",
@ -759,6 +874,7 @@ Array [
"content": "@site/docs/rootResolvedSlug.md",
},
"path": "/docs/hey/rootResolvedSlug",
"sidebar": "docs",
},
Object {
"component": "@theme/DocItem",
@ -783,6 +899,7 @@ Array [
"content": "@site/docs/rootAbsoluteSlug.md",
},
"path": "/docs/rootAbsoluteSlug",
"sidebar": "docs",
},
Object {
"component": "@theme/DocItem",
@ -791,6 +908,7 @@ Array [
"content": "@site/docs/rootRelativeSlug.md",
},
"path": "/docs/rootRelativeSlug",
"sidebar": "docs",
},
Object {
"component": "@theme/DocItem",
@ -799,6 +917,7 @@ Array [
"content": "@site/docs/rootTryToEscapeSlug.md",
},
"path": "/docs/rootTryToEscapeSlug",
"sidebar": "docs",
},
Object {
"component": "@theme/DocItem",

View file

@ -7,7 +7,13 @@
import path from 'path';
import {loadContext} from '@docusaurus/core/src/server/index';
import {processDocMetadata, readVersionDocs, readDocFile} from '../docs';
import {
processDocMetadata,
readVersionDocs,
readDocFile,
handleNavigation,
} from '../docs';
import {loadSidebars} from '../sidebars';
import {readVersionsMetadata} from '../versions';
import {
DocFile,
@ -16,6 +22,7 @@ import {
VersionMetadata,
PluginOptions,
EditUrlFunction,
DocNavLink,
} from '../types';
import {LoadContext} from '@docusaurus/types';
import {DEFAULT_PLUGIN_ID} from '@docusaurus/core/lib/constants';
@ -110,7 +117,38 @@ function createTestUtils({
expect(metadata.permalink).toEqual(expectedPermalink);
}
return {processDocFile, testMeta, testSlug};
async function generateNavigation(
docFiles: DocFile[],
): Promise<[DocNavLink, DocNavLink][]> {
const rawDocs = await Promise.all(
docFiles.map((docFile) =>
processDocMetadata({
docFile,
versionMetadata,
context,
options,
}),
),
);
const sidebars = await loadSidebars(versionMetadata.sidebarFilePath, {
sidebarItemsGenerator: ({defaultSidebarItemsGenerator, ...args}) =>
defaultSidebarItemsGenerator({...args}),
numberPrefixParser: options.numberPrefixParser,
docs: rawDocs,
version: versionMetadata,
options: {
sidebarCollapsed: false,
sidebarCollapsible: true,
},
});
return handleNavigation(
rawDocs,
sidebars,
versionMetadata.sidebarFilePath as string,
).docs.map((doc) => [doc.previous, doc.next]);
}
return {processDocFile, testMeta, testSlug, generateNavigation};
}
describe('simple site', () => {
@ -541,6 +579,28 @@ describe('simple site', () => {
`"The docs homepage (homePageId=homePageId) is not allowed to have a frontmatter slug=/x/y => you have to choose either homePageId or slug, not both"`,
);
});
test('custom pagination', async () => {
const {defaultTestUtils, options, versionsMetadata} = await loadSite();
const docs = await readVersionDocs(versionsMetadata[0], options);
expect(await defaultTestUtils.generateNavigation(docs)).toMatchSnapshot();
});
test('bad pagination', async () => {
const {defaultTestUtils, options, versionsMetadata} = await loadSite();
const docs = await readVersionDocs(versionsMetadata[0], options);
docs.push(
createFakeDocFile({
source: 'hehe',
frontmatter: {pagination_prev: 'nonexistent'},
}),
);
await expect(async () => {
await defaultTestUtils.generateNavigation(docs);
}).rejects.toThrowErrorMatchingInlineSnapshot(
`"Error when loading hehe in .: the pagination_prev front matter points to a non-existent ID nonexistent."`,
);
});
});
describe('versioned site', () => {

View file

@ -345,10 +345,11 @@ describe('simple website', () => {
permalink: '/docs/foo/bar',
},
next: {
title: 'Hello sidebar_label',
permalink: '/docs/',
title: 'rootAbsoluteSlug',
permalink: '/docs/rootAbsoluteSlug',
},
sidebar: 'docs',
sidebarPosition: undefined,
source: path.posix.join(
'@site',
posixPath(path.relative(siteDir, currentVersion.contentPath)),
@ -391,8 +392,8 @@ describe('simple website', () => {
permalink: '/docs/',
slug: '/',
previous: {
title: 'baz pagination_label',
permalink: '/docs/foo/bazSlug.html',
title: 'My heading as title',
permalink: '/docs/headingAsTitle',
},
sidebar: 'docs',
source: path.posix.join(