mirror of
https://github.com/facebook/docusaurus.git
synced 2025-05-29 17:07:08 +02:00
fix(v2): fix docs homepage permalink issues (#2905)
* better fixes for docs homepage * fix tests * create special route for docs homepage + cleanup existing code * no need to create multiple docs parent paths * useful comment * add test for slug + doc home usage at the same time error * remove confusing variable name * fix tests by using same suffix as before for docs base metadata path * metadata: use homePageId correctly for nested docs: the full docId (including /) should be used to compare against homePageId * add folder/testNested test doc * refactor a bit processMetadata, the home should be handled correctly for all versions * Workaround to fix issue when parent layout route (DocPage) has same path as the child route (DocItem): see https://github.com/facebook/docusaurus/issues/2917 * revert homePageId * remove test doc * remove test doc * add useful comment
This commit is contained in:
Sébastien Lorber
GitHub
parent
a3f54d747d
commit
f6b1c85b01
10 changed files with 264 additions and 218 deletions
|
|
@ -0,0 +1,5 @@
|
|||
---
|
||||
slug: docWithSlug.html
|
||||
---
|
||||
|
||||
Lorem
|
||||
|
|
@ -29,7 +29,7 @@ Object {
|
|||
"type": "link",
|
||||
},
|
||||
Object {
|
||||
"href": "/docs",
|
||||
"href": "/docs/",
|
||||
"label": "Hello, World !",
|
||||
"type": "link",
|
||||
},
|
||||
|
|
@ -41,7 +41,7 @@ Object {
|
|||
"collapsed": true,
|
||||
"items": Array [
|
||||
Object {
|
||||
"href": "/docs",
|
||||
"href": "/docs/",
|
||||
"label": "Hello, World !",
|
||||
"type": "link",
|
||||
},
|
||||
|
|
@ -57,21 +57,21 @@ exports[`simple website content 2`] = `
|
|||
Array [
|
||||
Object {
|
||||
"component": "@theme/DocPage",
|
||||
"exact": true,
|
||||
"modules": Object {
|
||||
"content": "@site/docs/hello.md",
|
||||
"docsMetadata": "~docs/site-docs-hello-md-9df-base.json",
|
||||
},
|
||||
"path": "/docs",
|
||||
},
|
||||
Object {
|
||||
"component": "@theme/DocPage",
|
||||
"exact": false,
|
||||
"modules": Object {
|
||||
"docsMetadata": "~docs/docs-route-ff2.json",
|
||||
},
|
||||
"path": "/docs/:route",
|
||||
"path": "/docs",
|
||||
"priority": undefined,
|
||||
"routes": Array [
|
||||
Object {
|
||||
"component": "@theme/DocItem",
|
||||
"exact": true,
|
||||
"modules": Object {
|
||||
"content": "@site/docs/hello.md",
|
||||
},
|
||||
"path": "/docs/",
|
||||
},
|
||||
Object {
|
||||
"component": "@theme/DocItem",
|
||||
"exact": true,
|
||||
|
|
@ -123,39 +123,21 @@ exports[`versioned website content 1`] = `
|
|||
Array [
|
||||
Object {
|
||||
"component": "@theme/DocPage",
|
||||
"exact": true,
|
||||
"modules": Object {
|
||||
"content": "@site/versioned_docs/version-1.0.1/hello.md",
|
||||
"docsMetadata": "~docs/site-versioned-docs-version-1-0-1-hello-md-0c7-base.json",
|
||||
},
|
||||
"path": "/docs",
|
||||
},
|
||||
Object {
|
||||
"component": "@theme/DocPage",
|
||||
"exact": true,
|
||||
"modules": Object {
|
||||
"content": "@site/versioned_docs/version-1.0.0/hello.md",
|
||||
"docsMetadata": "~docs/site-versioned-docs-version-1-0-0-hello-md-3ef-base.json",
|
||||
},
|
||||
"path": "/docs/1.0.0",
|
||||
},
|
||||
Object {
|
||||
"component": "@theme/DocPage",
|
||||
"exact": true,
|
||||
"modules": Object {
|
||||
"content": "@site/docs/hello.md",
|
||||
"docsMetadata": "~docs/site-docs-hello-md-9df-base.json",
|
||||
},
|
||||
"path": "/docs/next",
|
||||
},
|
||||
Object {
|
||||
"component": "@theme/DocPage",
|
||||
"exact": false,
|
||||
"modules": Object {
|
||||
"docsMetadata": "~docs/docs-1-0-0-route-660.json",
|
||||
},
|
||||
"path": "/docs/1.0.0/:route",
|
||||
"path": "/docs/1.0.0",
|
||||
"priority": undefined,
|
||||
"routes": Array [
|
||||
Object {
|
||||
"component": "@theme/DocItem",
|
||||
"exact": true,
|
||||
"modules": Object {
|
||||
"content": "@site/versioned_docs/version-1.0.0/hello.md",
|
||||
},
|
||||
"path": "/docs/1.0.0/",
|
||||
},
|
||||
Object {
|
||||
"component": "@theme/DocItem",
|
||||
"exact": true,
|
||||
|
|
@ -176,12 +158,21 @@ Array [
|
|||
},
|
||||
Object {
|
||||
"component": "@theme/DocPage",
|
||||
"exact": false,
|
||||
"modules": Object {
|
||||
"docsMetadata": "~docs/docs-next-route-1c8.json",
|
||||
},
|
||||
"path": "/docs/next/:route",
|
||||
"path": "/docs/next",
|
||||
"priority": undefined,
|
||||
"routes": Array [
|
||||
Object {
|
||||
"component": "@theme/DocItem",
|
||||
"exact": true,
|
||||
"modules": Object {
|
||||
"content": "@site/docs/hello.md",
|
||||
},
|
||||
"path": "/docs/next/",
|
||||
},
|
||||
Object {
|
||||
"component": "@theme/DocItem",
|
||||
"exact": true,
|
||||
|
|
@ -194,12 +185,21 @@ Array [
|
|||
},
|
||||
Object {
|
||||
"component": "@theme/DocPage",
|
||||
"exact": false,
|
||||
"modules": Object {
|
||||
"docsMetadata": "~docs/docs-route-ff2.json",
|
||||
},
|
||||
"path": "/docs/:route",
|
||||
"path": "/docs",
|
||||
"priority": -1,
|
||||
"routes": Array [
|
||||
Object {
|
||||
"component": "@theme/DocItem",
|
||||
"exact": true,
|
||||
"modules": Object {
|
||||
"content": "@site/versioned_docs/version-1.0.1/hello.md",
|
||||
},
|
||||
"path": "/docs/",
|
||||
},
|
||||
Object {
|
||||
"component": "@theme/DocItem",
|
||||
"exact": true,
|
||||
|
|
@ -232,7 +232,7 @@ Object {
|
|||
"collapsed": true,
|
||||
"items": Array [
|
||||
Object {
|
||||
"href": "/docs/next",
|
||||
"href": "/docs/next/",
|
||||
"label": "hello",
|
||||
"type": "link",
|
||||
},
|
||||
|
|
@ -263,7 +263,7 @@ Object {
|
|||
"collapsed": true,
|
||||
"items": Array [
|
||||
Object {
|
||||
"href": "/docs/1.0.0",
|
||||
"href": "/docs/1.0.0/",
|
||||
"label": "hello",
|
||||
"type": "link",
|
||||
},
|
||||
|
|
@ -289,7 +289,7 @@ Object {
|
|||
"collapsed": true,
|
||||
"items": Array [
|
||||
Object {
|
||||
"href": "/docs",
|
||||
"href": "/docs/",
|
||||
"label": "hello",
|
||||
"type": "link",
|
||||
},
|
||||
|
|
@ -326,7 +326,7 @@ Object {
|
|||
"collapsed": true,
|
||||
"items": Array [
|
||||
Object {
|
||||
"href": "/docs/1.0.0",
|
||||
"href": "/docs/1.0.0/",
|
||||
"label": "hello",
|
||||
"type": "link",
|
||||
},
|
||||
|
|
@ -337,9 +337,9 @@ Object {
|
|||
],
|
||||
},
|
||||
"permalinkToSidebar": Object {
|
||||
"/docs/1.0.0/": "version-1.0.0/docs",
|
||||
"/docs/1.0.0/foo/barSlug": "version-1.0.0/docs",
|
||||
"/docs/1.0.0/foo/baz": "version-1.0.0/docs",
|
||||
"/docs/1.0.0/hello": "version-1.0.0/docs",
|
||||
},
|
||||
"version": "1.0.0",
|
||||
}
|
||||
|
|
@ -365,7 +365,7 @@ Object {
|
|||
"collapsed": true,
|
||||
"items": Array [
|
||||
Object {
|
||||
"href": "/docs",
|
||||
"href": "/docs/",
|
||||
"label": "hello",
|
||||
"type": "link",
|
||||
},
|
||||
|
|
@ -376,8 +376,8 @@ Object {
|
|||
],
|
||||
},
|
||||
"permalinkToSidebar": Object {
|
||||
"/docs/": "version-1.0.1/docs",
|
||||
"/docs/foo/bar": "version-1.0.1/docs",
|
||||
"/docs/hello": "version-1.0.1/docs",
|
||||
},
|
||||
"version": "1.0.1",
|
||||
}
|
||||
|
|
@ -403,7 +403,7 @@ Object {
|
|||
"collapsed": true,
|
||||
"items": Array [
|
||||
Object {
|
||||
"href": "/docs/next",
|
||||
"href": "/docs/next/",
|
||||
"label": "hello",
|
||||
"type": "link",
|
||||
},
|
||||
|
|
@ -414,8 +414,8 @@ Object {
|
|||
],
|
||||
},
|
||||
"permalinkToSidebar": Object {
|
||||
"/docs/next/": "docs",
|
||||
"/docs/next/foo/barSlug": "docs",
|
||||
"/docs/next/hello": "docs",
|
||||
},
|
||||
"version": "next",
|
||||
}
|
||||
|
|
|
|||
|
|
@ -154,7 +154,8 @@ describe('simple website', () => {
|
|||
expect(versionToSidebars).toEqual({});
|
||||
expect(docsMetadata.hello).toEqual({
|
||||
id: 'hello',
|
||||
permalink: '/docs/hello',
|
||||
isDocsHomePage: true,
|
||||
permalink: '/docs/',
|
||||
previous: {
|
||||
title: 'baz',
|
||||
permalink: '/docs/foo/bazSlug.html',
|
||||
|
|
@ -168,6 +169,7 @@ describe('simple website', () => {
|
|||
|
||||
expect(docsMetadata['foo/bar']).toEqual({
|
||||
id: 'foo/bar',
|
||||
isDocsHomePage: false,
|
||||
next: {
|
||||
title: 'baz',
|
||||
permalink: '/docs/foo/bazSlug.html',
|
||||
|
|
@ -296,6 +298,7 @@ describe('versioned website', () => {
|
|||
expect(docsMetadata['version-1.0.1/foo/baz']).toBeUndefined();
|
||||
expect(docsMetadata['foo/bar']).toEqual({
|
||||
id: 'foo/bar',
|
||||
isDocsHomePage: false,
|
||||
permalink: '/docs/next/foo/barSlug',
|
||||
source: path.join('@site', routeBasePath, 'foo', 'bar.md'),
|
||||
title: 'bar',
|
||||
|
|
@ -304,12 +307,13 @@ describe('versioned website', () => {
|
|||
sidebar: 'docs',
|
||||
next: {
|
||||
title: 'hello',
|
||||
permalink: '/docs/next/hello',
|
||||
permalink: '/docs/next/',
|
||||
},
|
||||
});
|
||||
expect(docsMetadata['hello']).toEqual({
|
||||
id: 'hello',
|
||||
permalink: '/docs/next/hello',
|
||||
isDocsHomePage: true,
|
||||
permalink: '/docs/next/',
|
||||
source: path.join('@site', routeBasePath, 'hello.md'),
|
||||
title: 'hello',
|
||||
description: 'Hello next !',
|
||||
|
|
@ -322,7 +326,8 @@ describe('versioned website', () => {
|
|||
});
|
||||
expect(docsMetadata['version-1.0.1/hello']).toEqual({
|
||||
id: 'version-1.0.1/hello',
|
||||
permalink: '/docs/hello',
|
||||
isDocsHomePage: true,
|
||||
permalink: '/docs/',
|
||||
source: path.join(
|
||||
'@site',
|
||||
path.relative(siteDir, versionedDir),
|
||||
|
|
@ -341,6 +346,7 @@ describe('versioned website', () => {
|
|||
});
|
||||
expect(docsMetadata['version-1.0.0/foo/baz']).toEqual({
|
||||
id: 'version-1.0.0/foo/baz',
|
||||
isDocsHomePage: false,
|
||||
permalink: '/docs/1.0.0/foo/baz',
|
||||
source: path.join(
|
||||
'@site',
|
||||
|
|
@ -356,7 +362,7 @@ describe('versioned website', () => {
|
|||
sidebar: 'version-1.0.0/docs',
|
||||
next: {
|
||||
title: 'hello',
|
||||
permalink: '/docs/1.0.0/hello',
|
||||
permalink: '/docs/1.0.0/',
|
||||
},
|
||||
previous: {
|
||||
title: 'bar',
|
||||
|
|
|
|||
|
|
@ -46,6 +46,7 @@ describe('simple site', () => {
|
|||
|
||||
expect(dataA).toEqual({
|
||||
id: 'foo/bar',
|
||||
isDocsHomePage: false,
|
||||
permalink: '/docs/foo/bar',
|
||||
source: path.join('@site', routeBasePath, sourceA),
|
||||
title: 'Bar',
|
||||
|
|
@ -54,6 +55,7 @@ describe('simple site', () => {
|
|||
});
|
||||
expect(dataB).toEqual({
|
||||
id: 'hello',
|
||||
isDocsHomePage: false,
|
||||
permalink: '/docs/hello',
|
||||
source: path.join('@site', routeBasePath, sourceB),
|
||||
title: 'Hello, World !',
|
||||
|
|
@ -62,6 +64,56 @@ describe('simple site', () => {
|
|||
});
|
||||
});
|
||||
|
||||
test('homePageId doc', async () => {
|
||||
const source = path.join('hello.md');
|
||||
const options = {
|
||||
routeBasePath,
|
||||
homePageId: 'hello',
|
||||
};
|
||||
|
||||
const data = await processMetadata({
|
||||
source,
|
||||
refDir: docsDir,
|
||||
context,
|
||||
options,
|
||||
env,
|
||||
});
|
||||
|
||||
expect(data).toEqual({
|
||||
id: 'hello',
|
||||
isDocsHomePage: true,
|
||||
permalink: '/docs/',
|
||||
source: path.join('@site', routeBasePath, source),
|
||||
title: 'Hello, World !',
|
||||
description: `Hi, Endilie here :)`,
|
||||
});
|
||||
});
|
||||
|
||||
test('homePageId doc nested', async () => {
|
||||
const source = path.join('foo', 'bar.md');
|
||||
const options = {
|
||||
routeBasePath,
|
||||
homePageId: 'foo/bar',
|
||||
};
|
||||
|
||||
const data = await processMetadata({
|
||||
source,
|
||||
refDir: docsDir,
|
||||
context,
|
||||
options,
|
||||
env,
|
||||
});
|
||||
|
||||
expect(data).toEqual({
|
||||
id: 'foo/bar',
|
||||
isDocsHomePage: true,
|
||||
permalink: '/docs/',
|
||||
source: path.join('@site', routeBasePath, source),
|
||||
title: 'Bar',
|
||||
description: 'This is custom description',
|
||||
});
|
||||
});
|
||||
|
||||
test('docs with editUrl', async () => {
|
||||
const editUrl =
|
||||
'https://github.com/facebook/docusaurus/edit/master/website';
|
||||
|
|
@ -81,6 +133,7 @@ describe('simple site', () => {
|
|||
|
||||
expect(data).toEqual({
|
||||
id: 'foo/baz',
|
||||
isDocsHomePage: false,
|
||||
permalink: '/docs/foo/bazSlug.html',
|
||||
source: path.join('@site', routeBasePath, source),
|
||||
title: 'baz',
|
||||
|
|
@ -107,6 +160,7 @@ describe('simple site', () => {
|
|||
|
||||
expect(data).toEqual({
|
||||
id: 'lorem',
|
||||
isDocsHomePage: false,
|
||||
permalink: '/docs/lorem',
|
||||
source: path.join('@site', routeBasePath, source),
|
||||
title: 'lorem',
|
||||
|
|
@ -137,6 +191,7 @@ describe('simple site', () => {
|
|||
|
||||
expect(data).toEqual({
|
||||
id: 'lorem',
|
||||
isDocsHomePage: false,
|
||||
permalink: '/docs/lorem',
|
||||
source: path.join('@site', routeBasePath, source),
|
||||
title: 'lorem',
|
||||
|
|
@ -166,6 +221,7 @@ describe('simple site', () => {
|
|||
|
||||
expect(data).toEqual({
|
||||
id: 'ipsum',
|
||||
isDocsHomePage: false,
|
||||
permalink: '/docs/ipsum',
|
||||
source: path.join('@site', routeBasePath, source),
|
||||
title: 'ipsum',
|
||||
|
|
@ -214,6 +270,26 @@ describe('simple site', () => {
|
|||
`"Document slug cannot include \\"/\\"."`,
|
||||
);
|
||||
});
|
||||
|
||||
test('docs with slug on doc home', async () => {
|
||||
const badSiteDir = path.join(fixtureDir, 'bad-slug-on-doc-home-site');
|
||||
const options = {
|
||||
routeBasePath,
|
||||
homePageId: 'docWithSlug',
|
||||
};
|
||||
|
||||
await expect(
|
||||
processMetadata({
|
||||
source: 'docWithSlug.md',
|
||||
refDir: path.join(badSiteDir, 'docs'),
|
||||
context,
|
||||
options,
|
||||
env,
|
||||
}),
|
||||
).rejects.toThrowErrorMatchingInlineSnapshot(
|
||||
`"The docs homepage (homePageId=docWithSlug) is not allowed to have a frontmatter slug=docWithSlug.html => you have to chooser either homePageId or slug, not both"`,
|
||||
);
|
||||
});
|
||||
});
|
||||
|
||||
describe('versioned site', () => {
|
||||
|
|
@ -250,6 +326,7 @@ describe('versioned site', () => {
|
|||
|
||||
expect(dataA).toEqual({
|
||||
id: 'foo/bar',
|
||||
isDocsHomePage: false,
|
||||
permalink: '/docs/next/foo/barSlug',
|
||||
source: path.join('@site', routeBasePath, sourceA),
|
||||
title: 'bar',
|
||||
|
|
@ -258,6 +335,7 @@ describe('versioned site', () => {
|
|||
});
|
||||
expect(dataB).toEqual({
|
||||
id: 'hello',
|
||||
isDocsHomePage: false,
|
||||
permalink: '/docs/next/hello',
|
||||
source: path.join('@site', routeBasePath, sourceB),
|
||||
title: 'hello',
|
||||
|
|
@ -308,6 +386,7 @@ describe('versioned site', () => {
|
|||
|
||||
expect(dataA).toEqual({
|
||||
id: 'version-1.0.0/foo/bar',
|
||||
isDocsHomePage: false,
|
||||
permalink: '/docs/1.0.0/foo/barSlug',
|
||||
source: path.join('@site', path.relative(siteDir, versionedDir), sourceA),
|
||||
title: 'bar',
|
||||
|
|
@ -316,6 +395,7 @@ describe('versioned site', () => {
|
|||
});
|
||||
expect(dataB).toEqual({
|
||||
id: 'version-1.0.0/hello',
|
||||
isDocsHomePage: false,
|
||||
permalink: '/docs/1.0.0/hello',
|
||||
source: path.join('@site', path.relative(siteDir, versionedDir), sourceB),
|
||||
title: 'hello',
|
||||
|
|
@ -324,6 +404,7 @@ describe('versioned site', () => {
|
|||
});
|
||||
expect(dataC).toEqual({
|
||||
id: 'version-1.0.1/foo/bar',
|
||||
isDocsHomePage: false,
|
||||
permalink: '/docs/foo/bar',
|
||||
source: path.join('@site', path.relative(siteDir, versionedDir), sourceC),
|
||||
title: 'bar',
|
||||
|
|
@ -332,6 +413,7 @@ describe('versioned site', () => {
|
|||
});
|
||||
expect(dataD).toEqual({
|
||||
id: 'version-1.0.1/hello',
|
||||
isDocsHomePage: false,
|
||||
permalink: '/docs/hello',
|
||||
source: path.join('@site', path.relative(siteDir, versionedDir), sourceD),
|
||||
title: 'hello',
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue