3pp-mirror/docusaurus
1
0
Fork 0
mirror of https://github.com/facebook/docusaurus.git synced 2025-05-13 17:17:28 +02:00
Code Issues Projects Releases Packages Wiki Activity

feat(v2): markdown pages (#3158)

Browse source 
* markdown pages POC

* add remark admonition, mdx provider, yarn2npm...

* pluginContentPages md/mdx tests

* pluginContentPages md/mdx tests

* add relative file path test link to showcase link problem

* fix Markdown pages issues after merge

* fix broken links found in markdown pages

* fix tests

* factorize common validation in @docusaurus/utils-validation

* add some documentation

* add using plugins doc

* minor md pages fixes
This commit is contained in:
Sébastien Lorber 2020-07-31 16:04:56 +02:00 • committed by GitHub
parent 53b28d2bb2
commit 7cceee7e38
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
30 changed files with 570 additions and 93 deletions
Download patch file Download diff file Expand all files Collapse all files

14
packages/docusaurus-plugin-content-pages/src/__tests__/__fixtures__/website/docusaurus.config.js Normal file
View file

@ -0,0 +1,14 @@
/**
* Copyright (c) Facebook, Inc. and its affiliates.
*
* This source code is licensed under the MIT license found in the
* LICENSE file in the root directory of this source tree.
*/
module.exports = {
title: 'My Site',
tagline: 'The tagline of my site',
url: 'https://your-docusaurus-test-site.com',
baseUrl: '/',
favicon: 'img/favicon.ico',
};

2
packages/docusaurus-plugin-content-pages/src/__tests__/__fixtures__/website/src/pages/hello/index.md Normal file
View file

@ -0,0 +1,2 @@
Markdown index page

5
packages/docusaurus-plugin-content-pages/src/__tests__/__fixtures__/website/src/pages/hello/mdxPage.mdx Normal file
View file

@ -0,0 +1,5 @@
---
title: mdx page
description: my mdx page
---
MDX page

25
packages/docusaurus-plugin-content-pages/src/__tests__/index.test.ts
View file

@ -6,23 +6,15 @@
*/
import path from 'path';
import {loadContext} from '@docusaurus/core/lib/server';
import pluginContentPages from '../index';
import {LoadContext} from '@docusaurus/types';
import normalizePluginOptions from './pluginOptionSchema.test';
describe('docusaurus-plugin-content-pages', () => {
test('simple pages', async () => {
const siteDir = path.join(__dirname, '__fixtures__', 'website');
const siteConfig = {
title: 'Hello',
baseUrl: '/',
url: 'https://docusaurus.io',
};
const context = {
siteDir,
siteConfig,
} as LoadContext;
const context = loadContext(siteDir);
const pluginPath = 'src/pages';
const plugin = pluginContentPages(
context,
@ -34,14 +26,27 @@ describe('docusaurus-plugin-content-pages', () => {
expect(pagesMetadatas).toEqual([
{
type: 'jsx',
permalink: '/',
source: path.join('@site', pluginPath, 'index.js'),
},
{
type: 'jsx',
permalink: '/typescript',
source: path.join('@site', pluginPath, 'typescript.tsx'),
},
{
type: 'mdx',
permalink: '/hello/',
source: path.join('@site', pluginPath, 'hello', 'index.md'),
},
{
type: 'mdx',
permalink: '/hello/mdxPage',
source: path.join('@site', pluginPath, 'hello', 'mdxPage.mdx'),
},
{
type: 'jsx',
permalink: '/hello/world',
source: path.join('@site', pluginPath, 'hello', 'world.js'),
},

20
packages/docusaurus-plugin-content-pages/src/__tests__/pluginOptionSchema.test.ts
View file

@ -6,8 +6,11 @@
*/
import {PluginOptionSchema, DEFAULT_OPTIONS} from '../pluginOptionSchema';
import {PluginOptions} from '../types';
export default function normalizePluginOptions(options) {
export default function normalizePluginOptions(
options: Partial<PluginOptions>,
) {
const {value, error} = PluginOptionSchema.validate(options, {
convert: false,
});
@ -19,29 +22,30 @@ export default function normalizePluginOptions(options) {
}
describe('normalizePagesPluginOptions', () => {
test('should return default options for undefined user options', async () => {
const {value} = await PluginOptionSchema.validate({});
test('should return default options for undefined user options', () => {
const value = normalizePluginOptions({});
expect(value).toEqual(DEFAULT_OPTIONS);
});
test('should fill in default options for partially defined user options', async () => {
const {value} = await PluginOptionSchema.validate({path: 'src/pages'});
test('should fill in default options for partially defined user options', () => {
const value = normalizePluginOptions({path: 'src/pages'});
expect(value).toEqual(DEFAULT_OPTIONS);
});
test('should accept correctly defined user options', async () => {
test('should accept correctly defined user options', () => {
const userOptions = {
path: 'src/my-pages',
routeBasePath: 'my-pages',
include: ['**/*.{js,jsx,ts,tsx}'],
};
const {value} = await PluginOptionSchema.validate(userOptions);
expect(value).toEqual(userOptions);
const value = normalizePluginOptions(userOptions);
expect(value).toEqual({...DEFAULT_OPTIONS, ...userOptions});
});
test('should reject bad path inputs', () => {
expect(() => {
normalizePluginOptions({
// @ts-expect-error: bad attribute
path: 42,
});
}).toThrowErrorMatchingInlineSnapshot(`"\\"path\\" must be a string"`);

156
packages/docusaurus-plugin-content-pages/src/index.ts
View file

@ -8,23 +8,46 @@
import globby from 'globby';
import fs from 'fs';
import path from 'path';
import {encodePath, fileToPath, aliasedSitePath} from '@docusaurus/utils';
import {
encodePath,
fileToPath,
aliasedSitePath,
docuHash,
} from '@docusaurus/utils';
import {
LoadContext,
Plugin,
OptionValidationContext,
ValidationResult,
ConfigureWebpackUtils,
} from '@docusaurus/types';
import {PluginOptions, LoadedContent} from './types';
import {Configuration, Loader} from 'webpack';
import admonitions from 'remark-admonitions';
import {PluginOptionSchema} from './pluginOptionSchema';
import {ValidationError} from '@hapi/joi';
import {PluginOptions, LoadedContent, Metadata} from './types';
const isMarkdownSource = (source: string) =>
source.endsWith('.md') || source.endsWith('.mdx');
export default function pluginContentPages(
context: LoadContext,
options: PluginOptions,
): Plugin<LoadedContent | null, typeof PluginOptionSchema> {
const contentPath = path.resolve(context.siteDir, options.path);
if (options.admonitions) {
options.remarkPlugins = options.remarkPlugins.concat([
[admonitions, options.admonitions || {}],
]);
}
const {siteConfig, siteDir, generatedFilesDir} = context;
const contentPath = path.resolve(siteDir, options.path);
const dataDir = path.join(
generatedFilesDir,
'docusaurus-plugin-content-pages',
);
return {
name: 'docusaurus-plugin-content-pages',
@ -35,9 +58,18 @@ export default function pluginContentPages(
return [...globPattern];
},
getClientModules() {
const modules = [];
if (options.admonitions) {
modules.push(require.resolve('remark-admonitions/styles/infima.css'));
}
return modules;
},
async loadContent() {
const {include} = options;
const {siteConfig, siteDir} = context;
const pagesDir = contentPath;
if (!fs.existsSync(pagesDir)) {
@ -49,16 +81,27 @@ export default function pluginContentPages(
cwd: pagesDir,
});
return pagesFiles.map((relativeSource) => {
function toMetadata(relativeSource: string): Metadata {
const source = path.join(pagesDir, relativeSource);
const aliasedSource = aliasedSitePath(source, siteDir);
const pathName = encodePath(fileToPath(relativeSource));
// Default Language.
return {
permalink: pathName.replace(/^\//, baseUrl || ''),
source: aliasedSource,
};
});
const permalink = pathName.replace(/^\//, baseUrl || '');
if (isMarkdownSource(relativeSource)) {
return {
type: 'mdx',
permalink,
source: aliasedSource,
};
} else {
return {
type: 'jsx',
permalink,
source: aliasedSource,
};
}
}
return pagesFiles.map(toMetadata);
},
async contentLoaded({content, actions}) {
@ -66,22 +109,89 @@ export default function pluginContentPages(
return;
}
const {addRoute} = actions;
const {addRoute, createData} = actions;
await Promise.all(
content.map(async (metadataItem) => {
const {permalink, source} = metadataItem;
addRoute({
path: permalink,
component: source,
exact: true,
modules: {
config: `@generated/docusaurus.config`,
},
});
content.map(async (metadata) => {
const {permalink, source} = metadata;
if (metadata.type === 'mdx') {
await createData(
// Note that this created data path must be in sync with
// metadataPath provided to mdx-loader.
`${docuHash(metadata.source)}.json`,
JSON.stringify(metadata, null, 2),
);
addRoute({
path: permalink,
component: options.mdxPageComponent,
exact: true,
modules: {
content: source,
},
});
} else {
addRoute({
path: permalink,
component: source,
exact: true,
modules: {
config: `@generated/docusaurus.config`,
},
});
}
}),
);
},
configureWebpack(
_config: Configuration,
isServer: boolean,
{getBabelLoader, getCacheLoader}: ConfigureWebpackUtils,
) {
const {rehypePlugins, remarkPlugins} = options;
return {
resolve: {
alias: {
'~pages': dataDir,
},
},
module: {
rules: [
{
test: /(\.mdx?)$/,
include: [contentPath],
use: [
getCacheLoader(isServer),
getBabelLoader(isServer),
{
loader: require.resolve('@docusaurus/mdx-loader'),
options: {
remarkPlugins,
rehypePlugins,
// Note that metadataPath must be the same/in-sync as
// the path from createData for each MDX.
metadataPath: (mdxPath: string) => {
const aliasedSource = aliasedSitePath(mdxPath, siteDir);
return path.join(
dataDir,
`${docuHash(aliasedSource)}.json`,
);
},
},
},
{
loader: path.resolve(__dirname, './markdownLoader.js'),
options: {
// siteDir,
// contentPath,
},
},
].filter(Boolean) as Loader[],
},
],
},
};
},
};
}

22
packages/docusaurus-plugin-content-pages/src/markdownLoader.ts Normal file
View file

@ -0,0 +1,22 @@
/**
* Copyright (c) Facebook, Inc. and its affiliates.
*
* This source code is licensed under the MIT license found in the
* LICENSE file in the root directory of this source tree.
*/
import {loader} from 'webpack';
// import {getOptions} from 'loader-utils';
const markdownLoader: loader.Loader = function (fileString) {
const callback = this.async();
// const options = getOptions(this);
// TODO provide additinal md processing here? like interlinking pages?
// fileString = linkify(fileString)
return callback && callback(null, fileString);
};
export default markdownLoader;

15
packages/docusaurus-plugin-content-pages/src/pluginOptionSchema.ts
View file

@ -6,15 +6,28 @@
*/
import * as Joi from '@hapi/joi';
import {PluginOptions} from './types';
import {
RemarkPluginsSchema,
RehypePluginsSchema,
AdmonitionsSchema,
} from '@docusaurus/utils-validation';
export const DEFAULT_OPTIONS: PluginOptions = {
path: 'src/pages', // Path to data on filesystem, relative to site dir.
routeBasePath: '', // URL Route.
include: ['**/*.{js,jsx,ts,tsx}'], // Extensions to include.
include: ['**/*.{js,jsx,ts,tsx,md,mdx}'], // Extensions to include.
mdxPageComponent: '@theme/MDXPage',
remarkPlugins: [],
rehypePlugins: [],
admonitions: {},
};
export const PluginOptionSchema = Joi.object({
path: Joi.string().default(DEFAULT_OPTIONS.path),
routeBasePath: Joi.string().default(DEFAULT_OPTIONS.routeBasePath),
include: Joi.array().items(Joi.string()).default(DEFAULT_OPTIONS.include),
mdxPageComponent: Joi.string().default(DEFAULT_OPTIONS.mdxPageComponent),
remarkPlugins: RemarkPluginsSchema.default(DEFAULT_OPTIONS.remarkPlugins),
rehypePlugins: RehypePluginsSchema.default(DEFAULT_OPTIONS.rehypePlugins),
admonitions: AdmonitionsSchema.default(DEFAULT_OPTIONS.admonitions),
});

17
packages/docusaurus-plugin-content-pages/src/types.ts
View file

@ -9,11 +9,24 @@ export interface PluginOptions {
path: string;
routeBasePath: string;
include: string[];
mdxPageComponent: string;
remarkPlugins: ([Function, object] | Function)[];
rehypePlugins: string[];
admonitions: any;
}
export interface Metadata {
export type JSXPageMetadata = {
type: 'jsx';
permalink: string;
source: string;
}
};
export type MDXPageMetadata = {
type: 'mdx';
permalink: string;
source: string;
};
export type Metadata = JSXPageMetadata | MDXPageMetadata;
export type LoadedContent = Metadata[];