@docusaurus/plugin-content-blog 2.0.0-beta.15a2b59f9 → 2.0.0-beta.17

package/lib/blogUtils.js

@@ -6,34 +6,83 @@
  * 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.linkify = exports.generateBlogPosts = exports.parseBlogFileName = exports.getBlogTags = exports.paginateBlogPosts = exports.getSourceToPermalink = exports.truncate = void 0;
 const tslib_1 = require("tslib");
 const fs_extra_1 = tslib_1.__importDefault(require("fs-extra"));
-const globby_1 = tslib_1.__importDefault(require("globby"));
-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 feed_1 = require("feed");
-const lodash_1 = require("lodash");
+const lodash_1 = tslib_1.__importDefault(require("lodash"));
 const utils_1 = require("@docusaurus/utils");
 const blogFrontMatter_1 = require("./blogFrontMatter");
+const authors_1 = require("./authors");
+const logger_1 = tslib_1.__importDefault(require("@docusaurus/logger"));
 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 Object.fromEntries(blogPosts.map(({ metadata: { source, permalink } }) => [source, 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 paginateBlogPosts({ blogPosts, basePageUrl, blogTitle, blogDescription, postsPerPageOption, }) {
+    const totalCount = blogPosts.length;
+    const postsPerPage = postsPerPageOption === 'ALL' ? totalCount : postsPerPageOption;
+    const numberOfPages = Math.ceil(totalCount / postsPerPage);
+    const pages = [];
+    function permalink(page) {
+        return page > 0 ? `${basePageUrl}/page/${page + 1}` : basePageUrl;
+    }
+    for (let page = 0; page < numberOfPages; page += 1) {
+        pages.push({
+            items: blogPosts
+                .slice(page * postsPerPage, (page + 1) * postsPerPage)
+                .map((item) => item.id),
+            metadata: {
+                permalink: permalink(page),
+                page: page + 1,
+                postsPerPage,
+                totalPages: numberOfPages,
+                totalCount,
+                previousPage: page !== 0 ? permalink(page - 1) : null,
+                nextPage: page < numberOfPages - 1 ? permalink(page + 1) : null,
+                blogDescription,
+                blogTitle,
+            },
+        });
+    }
+    return pages;
+}
+exports.paginateBlogPosts = paginateBlogPosts;
+function getBlogTags({ blogPosts, ...params }) {
+    const groups = (0, utils_1.groupTaggedItems)(blogPosts, (blogPost) => blogPost.metadata.tags);
+    return lodash_1.default.mapValues(groups, ({ tag, items: tagBlogPosts }) => ({
+        name: tag.label,
+        items: tagBlogPosts.map((item) => item.id),
+        permalink: tag.permalink,
+        pages: paginateBlogPosts({
+            blogPosts: tagBlogPosts,
+            basePageUrl: tag.permalink,
+            ...params,
+        }),
+    }));
+}
+exports.getBlogTags = getBlogTags;
+const DATE_FILENAME_REGEX = /^(?<folder>.*)(?<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 { folder, text, date: dateString } = dateFilenameMatch.groups;
+        // Always treat dates as UTC by adding the `Z`
+        const date = new Date(`${dateString}Z`);
+        const slugDate = dateString.replace(/-/g, '/');
+        const slug = `/${slugDate}/${folder}${text}`;
+        return { date, text, slug };
+    }
+    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, {
@@ -43,150 +92,159 @@ function formatBlogPostDate(locale, date) {
             timeZone: 'UTC',
         }).format(date);
     }
-    catch (e) {
-        throw new Error(`Can't format blog post date "${date}"`);
+    catch (err) {
+        logger_1.default.error `Can't format blog post date "${String(date)}"`;
+        throw err;
     }
 }
-async function generateBlogFeed(contentPaths, context, options) {
-    if (!options.feedOptions) {
-        throw new Error('Invalid options: "feedOptions" is not expected to be null.');
+async function parseBlogPostMarkdownFile(blogSourceAbsolute) {
+    const markdownString = await fs_extra_1.default.readFile(blogSourceAbsolute, 'utf-8');
+    try {
+        const result = (0, utils_1.parseMarkdownString)(markdownString, {
+            removeContentTitle: true,
+        });
+        return {
+            ...result,
+            frontMatter: (0, blogFrontMatter_1.validateBlogPostFrontMatter)(result.frontMatter),
+        };
     }
-    const { siteConfig } = context;
-    const blogPosts = await generateBlogPosts(contentPaths, context, options);
-    if (!blogPosts.length) {
-        return null;
+    catch (err) {
+        logger_1.default.error `Error while parsing blog post file path=${blogSourceAbsolute}.`;
+        throw err;
     }
-    const { feedOptions, routeBasePath } = options;
-    const { url: siteUrl, baseUrl, title, favicon } = siteConfig;
-    const blogBaseUrl = 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({
-        id: blogBaseUrl,
-        title: feedOptions.title || `${title} Blog`,
-        updated,
-        language: feedOptions.language,
-        link: blogBaseUrl,
-        description: feedOptions.description || `${siteConfig.title} Blog`,
-        favicon: favicon ? utils_1.normalizeUrl([siteUrl, baseUrl, favicon]) : undefined,
-        copyright: feedOptions.copyright,
-    });
-    blogPosts.forEach((post) => {
-        const { id, metadata: { title: metadataTitle, permalink, date, description }, } = post;
-        feed.addItem({
-            title: metadataTitle,
-            id,
-            link: utils_1.normalizeUrl([siteUrl, permalink]),
-            date,
-            description,
-        });
-    });
-    return feed;
 }
-exports.generateBlogFeed = generateBlogFeed;
-async function generateBlogPosts(contentPaths, { siteConfig, siteDir, i18n }, options) {
-    const { include, routeBasePath, truncateMarker, showReadingTime, editUrl, } = options;
-    if (!fs_extra_1.default.existsSync(contentPaths.contentPath)) {
-        return [];
+const defaultReadingTime = ({ content, options }) => (0, reading_time_1.default)(content, options).minutes;
+async function processBlogSourceFile(blogSourceRelative, contentPaths, context, options, authorsMap) {
+    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)((0, utils_1.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;
     }
-    const { baseUrl = '' } = siteConfig;
-    const blogSourceFiles = await globby_1.default(include, {
-        cwd: contentPaths.contentPath,
-    });
-    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;
-        }
+    if (frontMatter.id) {
+        logger_1.default.warn `name=${'id'} header option is deprecated in path=${blogSourceRelative} file. Please use name=${'slug'} option instead.`;
+    }
+    const parsedBlogFileName = parseBlogFileName(blogSourceRelative);
+    async function getDate() {
         // Prefer user-defined date.
         if (frontMatter.date) {
-            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;
+            if (typeof frontMatter.date === 'string') {
+                // Always treat dates as UTC by adding the `Z`
+                return new Date(`${frontMatter.date}Z`);
             }
+            // YAML only converts YYYY-MM-DD to dates and leaves others as strings.
+            return frontMatter.date;
         }
-        blogPosts.push({
-            id: (_e = frontMatter.slug) !== null && _e !== void 0 ? _e : title,
-            metadata: {
+        else if (parsedBlogFileName.date) {
+            return parsedBlogFileName.date;
+        }
+        try {
+            const result = (0, utils_1.getFileCommitDate)(blogSourceAbsolute, {
+                age: 'oldest',
+                includeAuthor: false,
+            });
+            return result.date;
+        }
+        catch (err) {
+            logger_1.default.error(err);
+            return (await fs_extra_1.default.stat(blogSourceAbsolute)).birthtime;
+        }
+    }
+    const date = await getDate();
+    const formattedDate = formatBlogPostDate(i18n.currentLocale, date);
+    const title = frontMatter.title ?? contentTitle ?? parsedBlogFileName.text;
+    const description = frontMatter.description ?? excerpt ?? '';
+    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: slug,
+        metadata: {
+            permalink,
+            editUrl: getBlogEditUrl(),
+            source: aliasedSource,
+            title,
+            description,
+            date,
+            formattedDate,
+            tags: (0, utils_1.normalizeFrontMatterTags)(tagsBasePath, frontMatter.tags),
+            readingTime: showReadingTime
+                ? options.readingTime({
+                    content,
+                    frontMatter,
+                    defaultReadingTime,
+                })
+                : undefined,
+            truncated: truncateMarker?.test(content) || false,
+            authors,
+            frontMatter,
+        },
+        content,
+    };
+}
+async function generateBlogPosts(contentPaths, context, options) {
+    const { include, exclude } = options;
+    if (!(await fs_extra_1.default.pathExists(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 = (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;
+        catch (err) {
+            logger_1.default.error `Processing of blog source file path=${blogSourceFile} failed.`;
+            throw err;
         }
-    }));
+    }))).filter(Boolean);
     blogPosts.sort((a, b) => b.metadata.date.getTime() - a.metadata.date.getTime());
+    if (options.sortPosts === 'ascending') {
+        return blogPosts.reverse();
+    }
     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,
@@ -197,8 +255,3 @@ function linkify({ filePath, contentPaths, fileString, siteDir, sourceToPermalin
     return newContent;
 }
 exports.linkify = linkify;
-// Order matters: we look in priority in localized folder
-function getContentPathList(contentPaths) {
-    return [contentPaths.contentPathLocalized, contentPaths.contentPath];
-}
-exports.getContentPathList = getContentPathList;

package/lib/feed.d.ts

@@ -0,0 +1,15 @@
+/**
+ * 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 type { BlogPost } from './types';
+import type { DocusaurusConfig } from '@docusaurus/types';
+import type { PluginOptions } from '@docusaurus/plugin-content-blog';
+export declare function createBlogFeedFiles({ blogPosts, options, siteConfig, outDir, }: {
+    blogPosts: BlogPost[];
+    options: PluginOptions;
+    siteConfig: DocusaurusConfig;
+    outDir: string;
+}): Promise<void>;

package/lib/feed.js

@@ -0,0 +1,99 @@
+"use strict";
+/**
+ * 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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createBlogFeedFiles = void 0;
+const tslib_1 = require("tslib");
+const feed_1 = require("feed");
+const utils_1 = require("@docusaurus/utils");
+const cheerio_1 = tslib_1.__importDefault(require("cheerio"));
+const path_1 = tslib_1.__importDefault(require("path"));
+const fs_extra_1 = tslib_1.__importDefault(require("fs-extra"));
+const utils_common_1 = require("@docusaurus/utils-common");
+async function generateBlogFeed({ blogPosts, options, siteConfig, outDir, }) {
+    if (!blogPosts.length) {
+        return null;
+    }
+    const { feedOptions, routeBasePath } = options;
+    const { url: siteUrl, baseUrl, title, favicon } = siteConfig;
+    const blogBaseUrl = (0, utils_1.normalizeUrl)([siteUrl, baseUrl, routeBasePath]);
+    const updated = blogPosts[0] && blogPosts[0].metadata.date;
+    const feed = new feed_1.Feed({
+        id: blogBaseUrl,
+        title: feedOptions.title || `${title} Blog`,
+        updated,
+        language: feedOptions.language,
+        link: blogBaseUrl,
+        description: feedOptions.description || `${siteConfig.title} Blog`,
+        favicon: favicon ? (0, utils_1.normalizeUrl)([siteUrl, baseUrl, favicon]) : undefined,
+        copyright: feedOptions.copyright,
+    });
+    function toFeedAuthor(author) {
+        return { name: author.name, link: author.url, email: author.email };
+    }
+    await (0, utils_1.mapAsyncSequential)(blogPosts, async (post) => {
+        const { id, metadata: { title: metadataTitle, permalink, date, description, authors, tags, }, } = post;
+        const content = await (0, utils_1.readOutputHTMLFile)(permalink.replace(siteConfig.baseUrl, ''), outDir, siteConfig.trailingSlash);
+        const $ = cheerio_1.default.load(content);
+        const feedItem = {
+            title: metadataTitle,
+            id,
+            link: (0, utils_1.normalizeUrl)([siteUrl, permalink]),
+            date,
+            description,
+            // Atom feed demands the "term", while other feeds use "name"
+            category: tags.map((tag) => ({ name: tag.label, term: tag.label })),
+            content: $(`#${utils_common_1.blogPostContainerID}`).html(),
+        };
+        // json1() method takes the first item of authors array
+        // it causes an error when authors array is empty
+        const feedItemAuthors = authors.map(toFeedAuthor);
+        if (feedItemAuthors.length > 0) {
+            feedItem.author = feedItemAuthors;
+        }
+        feed.addItem(feedItem);
+    });
+    return feed;
+}
+async function createBlogFeedFile({ feed, feedType, generatePath, }) {
+    const [feedContent, feedPath] = (() => {
+        switch (feedType) {
+            case 'rss':
+                return [feed.rss2(), 'rss.xml'];
+            case 'json':
+                return [feed.json1(), 'feed.json'];
+            case 'atom':
+                return [feed.atom1(), 'atom.xml'];
+            default:
+                throw new Error(`Feed type ${feedType} not supported.`);
+        }
+    })();
+    try {
+        await fs_extra_1.default.outputFile((0, utils_1.posixPath)(path_1.default.join(generatePath, feedPath)), feedContent);
+    }
+    catch (err) {
+        throw new Error(`Generating ${feedType} feed failed: ${err}.`);
+    }
+}
+async function createBlogFeedFiles({ blogPosts, options, siteConfig, outDir, }) {
+    const feed = await generateBlogFeed({
+        blogPosts,
+        options,
+        siteConfig,
+        outDir,
+    });
+    const feedTypes = options.feedOptions.type;
+    if (!feed || !feedTypes) {
+        return;
+    }
+    await Promise.all(feedTypes.map((feedType) => createBlogFeedFile({
+        feed,
+        feedType,
+        generatePath: path_1.default.join(outDir, options.routeBasePath),
+    })));
+}
+exports.createBlogFeedFiles = createBlogFeedFiles;

package/lib/index.d.ts

@@ -4,7 +4,8 @@
  * This source code is licensed under the MIT license found in the
  * LICENSE file in the root directory of this source tree.
  */
-import { PluginOptions, BlogContent } from './types';
-import { LoadContext, Plugin, OptionValidationContext, ValidationResult } from '@docusaurus/types';
-export default function pluginContentBlog(context: LoadContext, options: PluginOptions): Plugin<BlogContent>;
+import type { BlogContent } from './types';
+import type { LoadContext, Plugin, OptionValidationContext, ValidationResult } from '@docusaurus/types';
+import type { PluginOptions } from '@docusaurus/plugin-content-blog';
+export default function pluginContentBlog(context: LoadContext, options: PluginOptions): Promise<Plugin<BlogContent>>;
 export declare function validateOptions({ validate, options, }: OptionValidationContext<PluginOptions>): ValidationResult<PluginOptions>;