Skip to content

Commit

Permalink
feat(v2): allow home page for docs
Browse files Browse the repository at this point in the history
  • Loading branch information
@lex111
lex111 committed Apr 24, 2020
1 parent 0a2a037 commit eaf2d35
Show file tree
Hide file tree
Showing 12 changed files with 299 additions and 98 deletions.
72 changes: 54 additions & 18 deletions packages/docusaurus-plugin-content-docs/src/__tests__/__snapshots__/index.test.ts.snap
View file
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
// Jest Snapshot v1, https://goo.gl/fbAQLP

exports[`simple website content 1`] = `
exports[`simple website content 1 1`] = `
Object {
"docs": Array [
Object {
Expand Down Expand Up @@ -50,8 +50,17 @@ Object {
}
`;

exports[`simple website content 2`] = `
exports[`simple website content 1 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",
"modules": Object {
Expand All @@ -64,49 +73,76 @@ Array [
"component": "@theme/DocItem",
"exact": true,
"modules": Object {
"content": "@site/docs/foo/bar.md",
"content": "@site/docs/ipsum.md",
},
"path": "/docs/foo/bar",
"path": "/docs/ipsum",
},
Object {
"component": "@theme/DocItem",
"exact": true,
"modules": Object {
"content": "@site/docs/foo/baz.md",
"content": "@site/docs/lorem.md",
},
"path": "/docs/foo/baz",
"path": "/docs/lorem",
},
Object {
"component": "@theme/DocItem",
"exact": true,
"modules": Object {
"content": "@site/docs/hello.md",
"content": "@site/docs/foo/bar.md",
},
"path": "/docs/hello",
"path": "/docs/foo/bar",
},
Object {
"component": "@theme/DocItem",
"exact": true,
"modules": Object {
"content": "@site/docs/ipsum.md",
"content": "@site/docs/foo/baz.md",
},
"path": "/docs/ipsum",
"path": "/docs/foo/baz",
},
Object {
"component": "@theme/DocItem",
"exact": true,
"modules": Object {
"content": "@site/docs/lorem.md",
"content": "@site/docs/hello.md",
},
"path": "/docs/lorem",
"path": "/docs/hello",
},
],
},
]
`;

exports[`versioned website content 1`] = `
exports[`versioned website content 2 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",
"modules": Object {
Expand Down Expand Up @@ -196,7 +232,7 @@ Array [
]
`;

exports[`versioned website content: all sidebars 1`] = `
exports[`versioned website content 2: all sidebars 1`] = `
Object {
"docs": Array [
Object {
Expand Down Expand Up @@ -278,7 +314,7 @@ Object {
}
`;

exports[`versioned website content: base metadata for first version 1`] = `
exports[`versioned website content 2: base metadata for first version 1`] = `
Object {
"docsSidebars": Object {
"version-1.0.0/docs": Array [
Expand Down Expand Up @@ -320,7 +356,7 @@ Object {
}
`;

exports[`versioned website content: base metadata for latest version 1`] = `
exports[`versioned website content 2: base metadata for latest version 1`] = `
Object {
"docsSidebars": Object {
"version-1.0.1/docs": Array [
Expand Down Expand Up @@ -356,7 +392,7 @@ Object {
}
`;

exports[`versioned website content: base metadata for next version 1`] = `
exports[`versioned website content 2: base metadata for next version 1`] = `
Object {
"docsSidebars": Object {
"docs": Array [
Expand Down Expand Up @@ -392,7 +428,7 @@ Object {
}
`;

exports[`versioned website content: sidebars needed for each version 1`] = `
exports[`versioned website content 2: sidebars needed for each version 1`] = `
Object {
"1.0.0": Set {
"version-1.0.0/docs",
Expand Down
9 changes: 7 additions & 2 deletions packages/docusaurus-plugin-content-docs/src/__tests__/index.test.ts
View file
Original file line number Diff line number Diff line change
Expand Up @@ -93,6 +93,7 @@ describe('simple website', () => {
const plugin = pluginContentDocs(context, {
path: pluginPath,
sidebarPath,
homePageId: 'hello',
});
const pluginContentDir = path.join(context.generatedFilesDir, plugin.name);

Expand Down Expand Up @@ -148,7 +149,7 @@ describe('simple website', () => {
expect(errors.length).toBe(0);
});

test('content', async () => {
test('content 1', async () => {
const content = await plugin.loadContent();
const {
docsMetadata,
Expand Down Expand Up @@ -203,6 +204,9 @@ describe('simple website', () => {
expect(baseMetadata.docsSidebars).toEqual(docsSidebars);
expect(baseMetadata.permalinkToSidebar).toEqual(permalinkToSidebar);

// // Sort the route config like in src/server/plugins/index.ts for consistent snapshot ordering
// sortConfig(routeConfigs);

expect(routeConfigs).not.toEqual([]);
expect(routeConfigs).toMatchSnapshot();
});
Expand All @@ -216,6 +220,7 @@ describe('versioned website', () => {
const plugin = pluginContentDocs(context, {
routeBasePath,
sidebarPath,
homePageId: 'hello',
});
const env = loadEnv(siteDir);
const {docsDir: versionedDir} = env.versioning;
Expand Down Expand Up @@ -281,7 +286,7 @@ describe('versioned website', () => {
expect(isMatch('super/docs/hello.md', matchPattern)).toEqual(false);
});

test('content', async () => {
test('content 2', async () => {
const content = await plugin.loadContent();
const {
docsMetadata,
Expand Down
134 changes: 106 additions & 28 deletions packages/docusaurus-plugin-content-docs/src/index.ts
View file
Original file line number Diff line number Diff line change
Expand Up @@ -46,9 +46,12 @@ import {
import {Configuration} from 'webpack';
import {docsVersion} from './version';

const REVERSED_DOCS_HOME_PAGE_ID = '_index';

const DEFAULT_OPTIONS: PluginOptions = {
path: 'docs', // Path to data on filesystem, relative to site dir.
routeBasePath: 'docs', // URL Route.
homePageId: REVERSED_DOCS_HOME_PAGE_ID, // Document id for docs home page.
include: ['**/*.{md,mdx}'], // Extensions to include.
sidebarPath: '', // Path to sidebar configuration for showing a list of markdown pages.
docLayoutComponent: '@theme/DocPage',
Expand Down Expand Up @@ -289,28 +292,96 @@ export default function pluginContentDocs(
const aliasedSource = (source: string) =>
`~docs/${path.relative(dataDir, source)}`;

const createDocsBaseMetadata = (version?: string): DocsBaseMetadata => {
const {docsSidebars, permalinkToSidebar, versionToSidebars} = content;
const neededSidebars: Set<string> =
versionToSidebars[version!] || new Set();

return {
docsSidebars: version
? pick(docsSidebars, Array.from(neededSidebars))
: docsSidebars,
permalinkToSidebar: version
? pickBy(permalinkToSidebar, (sidebar) =>
neededSidebars.has(sidebar),
)
: permalinkToSidebar,
version,
};
};

const genRoutes = async (
metadataItems: Metadata[],
): Promise<RouteConfig[]> => {
const routes = await Promise.all(
metadataItems.map(async (metadataItem) => {
await 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 routes: RouteConfig[] = [];

await metadataItems.forEach(async (metadataItem, i) => {
const isDocsHomePage =
metadataItem.id.substr(metadataItem.id.indexOf('/') + 1) ===
options.homePageId;

if (isDocsHomePage) {
const homeDocsRoutePath =
routeBasePath === '' ? '/' : routeBasePath;
const versionDocsPathPrefix =
(metadataItem?.version === versioning.latestVersion
? ''
: metadataItem.version!) ?? '';

// To show the sidebar, get the sidebar key of available sibling item.
metadataItem.sidebar = (
metadataItems[i - 1] ?? metadataItems[i + 1]
).sidebar;
const docsBaseMetadata = createDocsBaseMetadata(
metadataItem.version!,
);
docsBaseMetadata.isHomePage = true;
docsBaseMetadata.homePagePath = normalizeUrl([
baseUrl,
homeDocsRoutePath,
versionDocsPathPrefix,
options.homePageId,
]);
const docsBaseMetadataPath = await createData(
`${docuHash(metadataItem.source)}-base.json`,
JSON.stringify(docsBaseMetadata, null, 2),
);

return {
// Add a route for docs home page.
addRoute({
path: normalizeUrl([
baseUrl,
homeDocsRoutePath,
versionDocsPathPrefix,
]),
component: docLayoutComponent,
exact: true,
modules: {
docsMetadata: aliasedSource(docsBaseMetadataPath),
content: metadataItem.source,
},
});
}

await 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),
);

// Do not create a route for a page created specifically for docs home page.
if (metadataItem.id !== REVERSED_DOCS_HOME_PAGE_ID) {
routes.push({
path: metadataItem.permalink,
component: docItemComponent,
exact: true,
modules: {
content: metadataItem.source,
},
};
}),
);
});
}
});

return routes.sort((a, b) =>
a.path > b.path ? 1 : b.path > a.path ? -1 : 0,
Expand Down Expand Up @@ -359,19 +430,7 @@ export default function pluginContentDocs(
isLatestVersion ? '' : version,
]);
const docsBaseRoute = normalizeUrl([docsBasePermalink, ':route']);
const neededSidebars: Set<string> =
content.versionToSidebars[version] || new Set();
const docsBaseMetadata: DocsBaseMetadata = {
docsSidebars: pick(
content.docsSidebars,
Array.from(neededSidebars),
),
permalinkToSidebar: pickBy(
content.permalinkToSidebar,
(sidebar) => neededSidebars.has(sidebar),
),
version,
};
const docsBaseMetadata = createDocsBaseMetadata(version);

// We want latest version route config to be placed last in the
// generated routeconfig. Otherwise, `/docs/next/foo` will match
Expand All @@ -386,16 +445,35 @@ export default function pluginContentDocs(
);
} else {
const routes = await genRoutes(Object.values(content.docsMetadata));
const docsBaseMetadata: DocsBaseMetadata = {
docsSidebars: content.docsSidebars,
permalinkToSidebar: content.permalinkToSidebar,
};
const docsBaseMetadata = createDocsBaseMetadata();

const docsBaseRoute = normalizeUrl([baseUrl, routeBasePath, ':route']);
return addBaseRoute(docsBaseRoute, docsBaseMetadata, routes);
}
},

async routesLoaded(routes) {
// console.log('LOL', routes);

const normalizedHomeDocsRoutePath = `/${options.routeBasePath}`;
const homeDocsRoutes = routes.filter(
(routeConfig) => routeConfig.path === normalizedHomeDocsRoutePath,
);

// Remove the route for docs home page if there is a page with the same path (i.e. docs).
if (homeDocsRoutes.length > 1) {
const docsHomePageRouteIndex = routes.findIndex(
(route) =>
route.component === options.docLayoutComponent &&
route.path === normalizedHomeDocsRoutePath,
);

console.log('INDEX', routes[docsHomePageRouteIndex!]);

delete routes[docsHomePageRouteIndex!];
}
},

configureWebpack(_config, isServer, utils) {
const {getBabelLoader, getCacheLoader} = utils;
const {rehypePlugins, remarkPlugins} = options;
Expand Down
Loading

0 comments on commit eaf2d35

Please sign in to comment.