@docusaurus/plugin-content-blog 2.0.0-beta.6f366f4b4 → 2.0.0-beta.7

package/lib/blogFrontMatter.js

@@ -7,44 +7,56 @@
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.validateBlogPostFrontMatter = void 0;
-/* eslint-disable camelcase */
 const utils_validation_1 = require("@docusaurus/utils-validation");
-// NOTE: we don't add any default value on purpose here
-// We don't want default values to magically appear in doc metadatas and props
-// While the user did not provide those values explicitly
-// We use default values in code instead
-const BlogTagSchema = utils_validation_1.JoiFrontMatter.alternatives().try(utils_validation_1.JoiFrontMatter.string().required(), utils_validation_1.JoiFrontMatter.object({
-    label: utils_validation_1.JoiFrontMatter.string().required(),
-    permalink: utils_validation_1.JoiFrontMatter.string().required(),
-}));
+const BlogPostFrontMatterAuthorSchema = utils_validation_1.JoiFrontMatter.object({
+    key: utils_validation_1.JoiFrontMatter.string(),
+    name: utils_validation_1.JoiFrontMatter.string(),
+    title: utils_validation_1.JoiFrontMatter.string(),
+    url: utils_validation_1.URISchema,
+    imageURL: utils_validation_1.JoiFrontMatter.string(),
+})
+    .or('key', 'name')
+    .rename('image_url', 'imageURL', { alias: true });
+const FrontMatterAuthorErrorMessage = '{{#label}} does not look like a valid blog post author. Please use an author key or an author object (with a key and/or name).';
 const BlogFrontMatterSchema = utils_validation_1.JoiFrontMatter.object({
     id: utils_validation_1.JoiFrontMatter.string(),
     title: utils_validation_1.JoiFrontMatter.string().allow(''),
     description: utils_validation_1.JoiFrontMatter.string().allow(''),
-    tags: utils_validation_1.JoiFrontMatter.array().items(BlogTagSchema),
+    tags: utils_validation_1.FrontMatterTagsSchema,
     draft: utils_validation_1.JoiFrontMatter.boolean(),
     date: utils_validation_1.JoiFrontMatter.date().raw(),
+    // New multi-authors frontmatter:
+    authors: utils_validation_1.JoiFrontMatter.alternatives()
+        .try(utils_validation_1.JoiFrontMatter.string(), BlogPostFrontMatterAuthorSchema, utils_validation_1.JoiFrontMatter.array()
+        .items(utils_validation_1.JoiFrontMatter.string(), BlogPostFrontMatterAuthorSchema)
+        .messages({
+        'array.sparse': FrontMatterAuthorErrorMessage,
+        'array.includes': FrontMatterAuthorErrorMessage,
+    }))
+        .messages({
+        'alternatives.match': FrontMatterAuthorErrorMessage,
+    }),
+    // Legacy author frontmatter
     author: utils_validation_1.JoiFrontMatter.string(),
     author_title: utils_validation_1.JoiFrontMatter.string(),
     author_url: utils_validation_1.URISchema,
     author_image_url: utils_validation_1.URISchema,
-    slug: utils_validation_1.JoiFrontMatter.string(),
-    image: utils_validation_1.URISchema,
-    keywords: utils_validation_1.JoiFrontMatter.array().items(utils_validation_1.JoiFrontMatter.string().required()),
-    hide_table_of_contents: utils_validation_1.JoiFrontMatter.boolean(),
-    // TODO re-enable warnings later, our v1 blog posts use those older frontmatter fields
+    // TODO enable deprecation warnings later
     authorURL: utils_validation_1.URISchema,
     // .warning('deprecate.error', { alternative: '"author_url"'}),
     authorTitle: utils_validation_1.JoiFrontMatter.string(),
     // .warning('deprecate.error', { alternative: '"author_title"'}),
     authorImageURL: utils_validation_1.URISchema,
     // .warning('deprecate.error', { alternative: '"author_image_url"'}),
-})
-    .unknown()
-    .messages({
+    slug: utils_validation_1.JoiFrontMatter.string(),
+    image: utils_validation_1.URISchema,
+    keywords: utils_validation_1.JoiFrontMatter.array().items(utils_validation_1.JoiFrontMatter.string().required()),
+    hide_table_of_contents: utils_validation_1.JoiFrontMatter.boolean(),
+    ...utils_validation_1.FrontMatterTOCHeadingLevels,
+}).messages({
     'deprecate.error': '{#label} blog frontMatter field is deprecated. Please use {#alternative} instead.',
 });
 function validateBlogPostFrontMatter(frontMatter) {
-    return utils_validation_1.validateFrontMatter(frontMatter, BlogFrontMatterSchema);
+    return (0, utils_validation_1.validateFrontMatter)(frontMatter, BlogFrontMatterSchema);
 }
 exports.validateBlogPostFrontMatter = validateBlogPostFrontMatter;

package/lib/blogUtils.d.ts

@@ -5,15 +5,23 @@
  * LICENSE file in the root directory of this source tree.
  */
 import { Feed } from 'feed';
-import { PluginOptions, BlogPost, BlogContentPaths, BlogMarkdownLoaderOptions } from './types';
+import { PluginOptions, BlogPost, BlogContentPaths, BlogMarkdownLoaderOptions, BlogTags } from './types';
 import { LoadContext } from '@docusaurus/types';
 export declare function truncate(fileString: string, truncateMarker: RegExp): string;
 export declare function getSourceToPermalink(blogPosts: BlogPost[]): Record<string, string>;
+export declare function getBlogTags(blogPosts: BlogPost[]): BlogTags;
+declare type ParsedBlogFileName = {
+    date: Date | undefined;
+    text: string;
+    slug: string;
+};
+export declare function parseBlogFileName(blogSourceRelative: string): ParsedBlogFileName;
 export declare function generateBlogFeed(contentPaths: BlogContentPaths, context: LoadContext, options: PluginOptions): Promise<Feed | null>;
-export declare function generateBlogPosts(contentPaths: BlogContentPaths, { siteConfig, siteDir, i18n }: LoadContext, options: PluginOptions): Promise<BlogPost[]>;
+export declare function generateBlogPosts(contentPaths: BlogContentPaths, context: LoadContext, options: PluginOptions): Promise<BlogPost[]>;
 export declare type LinkifyParams = {
     filePath: string;
     fileString: string;
 } & Pick<BlogMarkdownLoaderOptions, 'sourceToPermalink' | 'siteDir' | 'contentPaths' | 'onBrokenMarkdownLink'>;
 export declare function linkify({ filePath, contentPaths, fileString, siteDir, sourceToPermalink, onBrokenMarkdownLink, }: LinkifyParams): string;
 export declare function getContentPathList(contentPaths: BlogContentPaths): string[];
+export {};

package/lib/blogUtils.js

@@ -6,33 +6,55 @@
  * LICENSE file in the root directory of this source tree.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.getContentPathList = exports.linkify = exports.generateBlogPosts = exports.generateBlogFeed = exports.getSourceToPermalink = exports.truncate = void 0;
+exports.getContentPathList = exports.linkify = exports.generateBlogPosts = exports.generateBlogFeed = exports.parseBlogFileName = exports.getBlogTags = exports.getSourceToPermalink = exports.truncate = void 0;
 const tslib_1 = require("tslib");
-const fs_extra_1 = tslib_1.__importDefault(require("fs-extra"));
-const chalk_1 = tslib_1.__importDefault(require("chalk"));
-const path_1 = tslib_1.__importDefault(require("path"));
-const reading_time_1 = tslib_1.__importDefault(require("reading-time"));
+const fs_extra_1 = (0, tslib_1.__importDefault)(require("fs-extra"));
+const chalk_1 = (0, tslib_1.__importDefault)(require("chalk"));
+const path_1 = (0, tslib_1.__importDefault)(require("path"));
+const reading_time_1 = (0, tslib_1.__importDefault)(require("reading-time"));
 const feed_1 = require("feed");
 const lodash_1 = require("lodash");
 const utils_1 = require("@docusaurus/utils");
 const blogFrontMatter_1 = require("./blogFrontMatter");
+const authors_1 = require("./authors");
 function truncate(fileString, truncateMarker) {
     return fileString.split(truncateMarker, 1).shift();
 }
 exports.truncate = truncate;
 function getSourceToPermalink(blogPosts) {
-    return lodash_1.mapValues(lodash_1.keyBy(blogPosts, (item) => item.metadata.source), (v) => v.metadata.permalink);
+    return (0, lodash_1.mapValues)((0, lodash_1.keyBy)(blogPosts, (item) => item.metadata.source), (v) => v.metadata.permalink);
 }
 exports.getSourceToPermalink = getSourceToPermalink;
-// YYYY-MM-DD-{name}.mdx?
-// Prefer named capture, but older Node versions do not support it.
-const DATE_FILENAME_PATTERN = /^(\d{4}-\d{1,2}-\d{1,2})-?(.*?).mdx?$/;
-function toUrl({ date, link }) {
-    return `${date
-        .toISOString()
-        .substring(0, '2019-01-01'.length)
-        .replace(/-/g, '/')}/${link}`;
+function getBlogTags(blogPosts) {
+    const groups = (0, utils_1.groupTaggedItems)(blogPosts, (blogPost) => blogPost.metadata.tags);
+    return (0, lodash_1.mapValues)(groups, (group) => {
+        return {
+            name: group.tag.label,
+            items: group.items.map((item) => item.id),
+            permalink: group.tag.permalink,
+        };
+    });
+}
+exports.getBlogTags = getBlogTags;
+const DATE_FILENAME_REGEX = /^(?<date>\d{4}[-/]\d{1,2}[-/]\d{1,2})[-/]?(?<text>.*?)(\/index)?.mdx?$/;
+function parseBlogFileName(blogSourceRelative) {
+    const dateFilenameMatch = blogSourceRelative.match(DATE_FILENAME_REGEX);
+    if (dateFilenameMatch) {
+        const dateString = dateFilenameMatch.groups.date;
+        const text = dateFilenameMatch.groups.text;
+        // Always treat dates as UTC by adding the `Z`
+        const date = new Date(`${dateString}Z`);
+        const slugDate = dateString.replace(/-/g, '/');
+        const slug = `/${slugDate}/${text}`;
+        return { date, text, slug };
+    }
+    else {
+        const text = blogSourceRelative.replace(/(\/index)?\.mdx?$/, '');
+        const slug = `/${text}`;
+        return { date: undefined, text, slug };
+    }
 }
+exports.parseBlogFileName = parseBlogFileName;
 function formatBlogPostDate(locale, date) {
     try {
         return new Intl.DateTimeFormat(locale, {
@@ -57,7 +79,7 @@ async function generateBlogFeed(contentPaths, context, options) {
     }
     const { feedOptions, routeBasePath } = options;
     const { url: siteUrl, baseUrl, title, favicon } = siteConfig;
-    const blogBaseUrl = utils_1.normalizeUrl([siteUrl, baseUrl, routeBasePath]);
+    const blogBaseUrl = (0, utils_1.normalizeUrl)([siteUrl, baseUrl, routeBasePath]);
     const updated = (blogPosts[0] && blogPosts[0].metadata.date) ||
         new Date('2015-10-25T16:29:00.000-07:00');
     const feed = new feed_1.Feed({
@@ -67,126 +89,146 @@ async function generateBlogFeed(contentPaths, context, options) {
         language: feedOptions.language,
         link: blogBaseUrl,
         description: feedOptions.description || `${siteConfig.title} Blog`,
-        favicon: favicon ? utils_1.normalizeUrl([siteUrl, baseUrl, favicon]) : undefined,
+        favicon: favicon ? (0, utils_1.normalizeUrl)([siteUrl, baseUrl, favicon]) : undefined,
         copyright: feedOptions.copyright,
     });
+    function toFeedAuthor(author) {
+        // TODO ask author emails?
+        // RSS feed requires email to render authors
+        return { name: author.name, link: author.url };
+    }
     blogPosts.forEach((post) => {
-        const { id, metadata: { title: metadataTitle, permalink, date, description }, } = post;
+        const { id, metadata: { title: metadataTitle, permalink, date, description, authors }, } = post;
         feed.addItem({
             title: metadataTitle,
             id,
-            link: utils_1.normalizeUrl([siteUrl, permalink]),
+            link: (0, utils_1.normalizeUrl)([siteUrl, permalink]),
             date,
             description,
+            content: (0, utils_1.mdxToHtml)(post.content),
+            author: authors.map(toFeedAuthor),
         });
     });
     return feed;
 }
 exports.generateBlogFeed = generateBlogFeed;
-async function generateBlogPosts(contentPaths, { siteConfig, siteDir, i18n }, options) {
-    const { include, exclude, routeBasePath, truncateMarker, showReadingTime, editUrl, } = options;
-    if (!fs_extra_1.default.existsSync(contentPaths.contentPath)) {
-        return [];
-    }
-    const { baseUrl = '' } = siteConfig;
-    const blogSourceFiles = await utils_1.Globby(include, {
-        cwd: contentPaths.contentPath,
-        ignore: exclude,
+async function parseBlogPostMarkdownFile(blogSourceAbsolute) {
+    const result = await (0, utils_1.parseMarkdownFile)(blogSourceAbsolute, {
+        removeContentTitle: true,
     });
-    const blogPosts = [];
-    async function processBlogSourceFile(blogSourceFile) {
-        var _a, _b, _c, _d, _e, _f;
-        // Lookup in localized folder in priority
-        const blogDirPath = await utils_1.getFolderContainingFile(getContentPathList(contentPaths), blogSourceFile);
-        const source = path_1.default.join(blogDirPath, blogSourceFile);
-        const { frontMatter: unsafeFrontMatter, content, contentTitle, excerpt, } = await utils_1.parseMarkdownFile(source, { removeContentTitle: true });
-        const frontMatter = blogFrontMatter_1.validateBlogPostFrontMatter(unsafeFrontMatter);
-        const aliasedSource = utils_1.aliasedSitePath(source, siteDir);
-        const blogFileName = path_1.default.basename(blogSourceFile);
-        if (frontMatter.draft && process.env.NODE_ENV === 'production') {
-            return;
-        }
-        if (frontMatter.id) {
-            console.warn(chalk_1.default.yellow(`"id" header option is deprecated in ${blogFileName} file. Please use "slug" option instead.`));
-        }
-        let date;
-        // Extract date and title from filename.
-        const dateFilenameMatch = blogFileName.match(DATE_FILENAME_PATTERN);
-        let linkName = blogFileName.replace(/\.mdx?$/, '');
-        if (dateFilenameMatch) {
-            const [, dateString, name] = dateFilenameMatch;
-            // Always treat dates as UTC by adding the `Z`
-            date = new Date(`${dateString}Z`);
-            linkName = name;
-        }
+    return {
+        ...result,
+        frontMatter: (0, blogFrontMatter_1.validateBlogPostFrontMatter)(result.frontMatter),
+    };
+}
+async function processBlogSourceFile(blogSourceRelative, contentPaths, context, options, authorsMap) {
+    var _a, _b, _c, _d, _e;
+    const { siteConfig: { baseUrl }, siteDir, i18n, } = context;
+    const { routeBasePath, tagsBasePath: tagsRouteBasePath, truncateMarker, showReadingTime, editUrl, } = options;
+    // Lookup in localized folder in priority
+    const blogDirPath = await (0, utils_1.getFolderContainingFile)(getContentPathList(contentPaths), blogSourceRelative);
+    const blogSourceAbsolute = path_1.default.join(blogDirPath, blogSourceRelative);
+    const { frontMatter, content, contentTitle, excerpt } = await parseBlogPostMarkdownFile(blogSourceAbsolute);
+    const aliasedSource = (0, utils_1.aliasedSitePath)(blogSourceAbsolute, siteDir);
+    if (frontMatter.draft && process.env.NODE_ENV === 'production') {
+        return undefined;
+    }
+    if (frontMatter.id) {
+        console.warn(chalk_1.default.yellow(`"id" header option is deprecated in ${blogSourceRelative} file. Please use "slug" option instead.`));
+    }
+    const parsedBlogFileName = parseBlogFileName(blogSourceRelative);
+    async function getDate() {
         // Prefer user-defined date.
         if (frontMatter.date) {
-            date = frontMatter.date;
+            return new Date(frontMatter.date);
         }
-        // Use file create time for blog.
-        date = date !== null && date !== void 0 ? date : (await fs_extra_1.default.stat(source)).birthtime;
-        const formattedDate = formatBlogPostDate(i18n.currentLocale, date);
-        const title = (_b = (_a = frontMatter.title) !== null && _a !== void 0 ? _a : contentTitle) !== null && _b !== void 0 ? _b : linkName;
-        const description = (_d = (_c = frontMatter.description) !== null && _c !== void 0 ? _c : excerpt) !== null && _d !== void 0 ? _d : '';
-        const slug = frontMatter.slug ||
-            (dateFilenameMatch ? toUrl({ date, link: linkName }) : linkName);
-        const permalink = utils_1.normalizeUrl([baseUrl, routeBasePath, slug]);
-        function getBlogEditUrl() {
-            const blogPathRelative = path_1.default.relative(blogDirPath, path_1.default.resolve(source));
-            if (typeof editUrl === 'function') {
-                return editUrl({
-                    blogDirPath: utils_1.posixPath(path_1.default.relative(siteDir, blogDirPath)),
-                    blogPath: utils_1.posixPath(blogPathRelative),
-                    permalink,
-                    locale: i18n.currentLocale,
-                });
-            }
-            else if (typeof editUrl === 'string') {
-                const isLocalized = blogDirPath === contentPaths.contentPathLocalized;
-                const fileContentPath = isLocalized && options.editLocalizedFiles
-                    ? contentPaths.contentPathLocalized
-                    : contentPaths.contentPath;
-                const contentPathEditUrl = utils_1.normalizeUrl([
-                    editUrl,
-                    utils_1.posixPath(path_1.default.relative(siteDir, fileContentPath)),
-                ]);
-                return utils_1.getEditUrl(blogPathRelative, contentPathEditUrl);
-            }
-            else {
-                return undefined;
-            }
+        else if (parsedBlogFileName.date) {
+            return parsedBlogFileName.date;
         }
-        blogPosts.push({
-            id: (_e = frontMatter.slug) !== null && _e !== void 0 ? _e : title,
-            metadata: {
+        // Fallback to file create time
+        return (await fs_extra_1.default.stat(blogSourceAbsolute)).birthtime;
+    }
+    const date = await getDate();
+    const formattedDate = formatBlogPostDate(i18n.currentLocale, date);
+    const title = (_b = (_a = frontMatter.title) !== null && _a !== void 0 ? _a : contentTitle) !== null && _b !== void 0 ? _b : parsedBlogFileName.text;
+    const description = (_d = (_c = frontMatter.description) !== null && _c !== void 0 ? _c : excerpt) !== null && _d !== void 0 ? _d : '';
+    const slug = frontMatter.slug || parsedBlogFileName.slug;
+    const permalink = (0, utils_1.normalizeUrl)([baseUrl, routeBasePath, slug]);
+    function getBlogEditUrl() {
+        const blogPathRelative = path_1.default.relative(blogDirPath, path_1.default.resolve(blogSourceAbsolute));
+        if (typeof editUrl === 'function') {
+            return editUrl({
+                blogDirPath: (0, utils_1.posixPath)(path_1.default.relative(siteDir, blogDirPath)),
+                blogPath: (0, utils_1.posixPath)(blogPathRelative),
                 permalink,
-                editUrl: getBlogEditUrl(),
-                source: aliasedSource,
-                title,
-                description,
-                date,
-                formattedDate,
-                tags: (_f = frontMatter.tags) !== null && _f !== void 0 ? _f : [],
-                readingTime: showReadingTime ? reading_time_1.default(content).minutes : undefined,
-                truncated: (truncateMarker === null || truncateMarker === void 0 ? void 0 : truncateMarker.test(content)) || false,
-            },
-        });
+                locale: i18n.currentLocale,
+            });
+        }
+        else if (typeof editUrl === 'string') {
+            const isLocalized = blogDirPath === contentPaths.contentPathLocalized;
+            const fileContentPath = isLocalized && options.editLocalizedFiles
+                ? contentPaths.contentPathLocalized
+                : contentPaths.contentPath;
+            const contentPathEditUrl = (0, utils_1.normalizeUrl)([
+                editUrl,
+                (0, utils_1.posixPath)(path_1.default.relative(siteDir, fileContentPath)),
+            ]);
+            return (0, utils_1.getEditUrl)(blogPathRelative, contentPathEditUrl);
+        }
+        return undefined;
     }
-    await Promise.all(blogSourceFiles.map(async (blogSourceFile) => {
+    const tagsBasePath = (0, utils_1.normalizeUrl)([
+        baseUrl,
+        routeBasePath,
+        tagsRouteBasePath,
+    ]);
+    const authors = (0, authors_1.getBlogPostAuthors)({ authorsMap, frontMatter });
+    return {
+        id: (_e = frontMatter.slug) !== null && _e !== void 0 ? _e : title,
+        metadata: {
+            permalink,
+            editUrl: getBlogEditUrl(),
+            source: aliasedSource,
+            title,
+            description,
+            date,
+            formattedDate,
+            tags: (0, utils_1.normalizeFrontMatterTags)(tagsBasePath, frontMatter.tags),
+            readingTime: showReadingTime ? (0, reading_time_1.default)(content).minutes : undefined,
+            truncated: (truncateMarker === null || truncateMarker === void 0 ? void 0 : truncateMarker.test(content)) || false,
+            authors,
+        },
+        content,
+    };
+}
+async function generateBlogPosts(contentPaths, context, options) {
+    const { include, exclude } = options;
+    if (!fs_extra_1.default.existsSync(contentPaths.contentPath)) {
+        return [];
+    }
+    const blogSourceFiles = await (0, utils_1.Globby)(include, {
+        cwd: contentPaths.contentPath,
+        ignore: exclude,
+    });
+    const authorsMap = await (0, authors_1.getAuthorsMap)({
+        contentPaths,
+        authorsMapPath: options.authorsMapPath,
+    });
+    const blogPosts = (0, lodash_1.compact)(await Promise.all(blogSourceFiles.map(async (blogSourceFile) => {
         try {
-            return await processBlogSourceFile(blogSourceFile);
+            return await processBlogSourceFile(blogSourceFile, contentPaths, context, options, authorsMap);
         }
         catch (e) {
             console.error(chalk_1.default.red(`Processing of blog source file failed for path "${blogSourceFile}"`));
             throw e;
         }
-    }));
+    })));
     blogPosts.sort((a, b) => b.metadata.date.getTime() - a.metadata.date.getTime());
     return blogPosts;
 }
 exports.generateBlogPosts = generateBlogPosts;
 function linkify({ filePath, contentPaths, fileString, siteDir, sourceToPermalink, onBrokenMarkdownLink, }) {
-    const { newContent, brokenMarkdownLinks } = utils_1.replaceMarkdownLinks({
+    const { newContent, brokenMarkdownLinks } = (0, utils_1.replaceMarkdownLinks)({
         siteDir,
         fileString,
         filePath,