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

package/lib/authors.d.ts

@@ -0,0 +1,20 @@
+/**
+ * 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 { BlogContentPaths } from './types';
+import type { Author, BlogPostFrontMatter } from '@docusaurus/plugin-content-blog';
+export declare type AuthorsMap = Record<string, Author>;
+export declare function validateAuthorsMap(content: unknown): AuthorsMap;
+export declare function getAuthorsMap(params: {
+    authorsMapPath: string;
+    contentPaths: BlogContentPaths;
+}): Promise<AuthorsMap | undefined>;
+declare type AuthorsParam = {
+    frontMatter: BlogPostFrontMatter;
+    authorsMap: AuthorsMap | undefined;
+};
+export declare function getBlogPostAuthors(params: AuthorsParam): Author[];
+export {};

package/lib/authors.js

@@ -0,0 +1,110 @@
+"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.getBlogPostAuthors = exports.getAuthorsMap = exports.validateAuthorsMap = void 0;
+const utils_1 = require("@docusaurus/utils");
+const utils_validation_1 = require("@docusaurus/utils-validation");
+const AuthorsMapSchema = utils_validation_1.Joi.object().pattern(utils_validation_1.Joi.string(), utils_validation_1.Joi.object({
+    name: utils_validation_1.Joi.string(),
+    url: utils_validation_1.URISchema,
+    imageURL: utils_validation_1.URISchema,
+    title: utils_validation_1.Joi.string(),
+    email: utils_validation_1.Joi.string(),
+})
+    .rename('image_url', 'imageURL')
+    .or('name', 'imageURL')
+    .unknown()
+    .required());
+function validateAuthorsMap(content) {
+    return utils_validation_1.Joi.attempt(content, AuthorsMapSchema);
+}
+exports.validateAuthorsMap = validateAuthorsMap;
+async function getAuthorsMap(params) {
+    return (0, utils_1.getDataFileData)({
+        filePath: params.authorsMapPath,
+        contentPaths: params.contentPaths,
+        fileType: 'authors map',
+    }, validateAuthorsMap);
+}
+exports.getAuthorsMap = getAuthorsMap;
+// Legacy v1/early-v2 front matter fields
+// We may want to deprecate those in favor of using only frontMatter.authors
+function getFrontMatterAuthorLegacy(frontMatter) {
+    const name = frontMatter.author;
+    const title = frontMatter.author_title ?? frontMatter.authorTitle;
+    const url = frontMatter.author_url ?? frontMatter.authorURL;
+    const imageURL = frontMatter.author_image_url ?? frontMatter.authorImageURL;
+    if (name || title || url || imageURL) {
+        return {
+            name,
+            title,
+            url,
+            imageURL,
+        };
+    }
+    return undefined;
+}
+function normalizeFrontMatterAuthors(frontMatterAuthors = []) {
+    function normalizeAuthor(authorInput) {
+        if (typeof authorInput === 'string') {
+            // Technically, we could allow users to provide an author's name here, but
+            // we only support keys, otherwise, a typo in a key would fallback to
+            // becoming a name and may end up unnoticed
+            return { key: authorInput };
+        }
+        return authorInput;
+    }
+    return Array.isArray(frontMatterAuthors)
+        ? frontMatterAuthors.map(normalizeAuthor)
+        : [normalizeAuthor(frontMatterAuthors)];
+}
+function getFrontMatterAuthors(params) {
+    const { authorsMap } = params;
+    const frontMatterAuthors = normalizeFrontMatterAuthors(params.frontMatter.authors);
+    function getAuthorsMapAuthor(key) {
+        if (key) {
+            if (!authorsMap || Object.keys(authorsMap).length === 0) {
+                throw new Error(`Can't reference blog post authors by a key (such as '${key}') because no authors map file could be loaded.
+Please double-check your blog plugin config (in particular 'authorsMapPath'), ensure the file exists at the configured path, is not empty, and is valid!`);
+            }
+            const author = authorsMap[key];
+            if (!author) {
+                throw Error(`Blog author with key "${key}" not found in the authors map file.
+Valid author keys are:
+${Object.keys(authorsMap)
+                    .map((validKey) => `- ${validKey}`)
+                    .join('\n')}`);
+            }
+            return author;
+        }
+        return undefined;
+    }
+    function toAuthor(frontMatterAuthor) {
+        return {
+            // Author def from authorsMap can be locally overridden by front matter
+            ...getAuthorsMapAuthor(frontMatterAuthor.key),
+            ...frontMatterAuthor,
+        };
+    }
+    return frontMatterAuthors.map(toAuthor);
+}
+function getBlogPostAuthors(params) {
+    const authorLegacy = getFrontMatterAuthorLegacy(params.frontMatter);
+    const authors = getFrontMatterAuthors(params);
+    if (authorLegacy) {
+        // Technically, we could allow mixing legacy/authors front matter, but do we
+        // really want to?
+        if (authors.length > 0) {
+            throw new Error(`To declare blog post authors, use the 'authors' front matter in priority.
+Don't mix 'authors' with other existing 'author_*' front matter. Choose one or the other, not both at the same time.`);
+        }
+        return [authorLegacy];
+    }
+    return authors;
+}
+exports.getBlogPostAuthors = getBlogPostAuthors;

package/lib/blogFrontMatter.d.ts

@@ -4,25 +4,5 @@
  * This source code is licensed under the MIT license found in the
  * LICENSE file in the root directory of this source tree.
  */
-import { Tag } from './types';
-export declare type BlogPostFrontMatter = {
-    id?: string;
-    title?: string;
-    description?: string;
-    tags?: (string | Tag)[];
-    slug?: string;
-    draft?: boolean;
-    date?: Date;
-    author?: string;
-    author_title?: string;
-    author_url?: string;
-    author_image_url?: string;
-    image?: string;
-    keywords?: string[];
-    hide_table_of_contents?: boolean;
-    /** @deprecated */
-    authorTitle?: string;
-    authorURL?: string;
-    authorImageURL?: string;
-};
+import type { BlogPostFrontMatter } from '@docusaurus/plugin-content-blog';
 export declare function validateBlogPostFrontMatter(frontMatter: Record<string, unknown>): BlogPostFrontMatter;

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', 'imageURL')
+    .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 front matter:
+    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 front matter
     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

@@ -4,16 +4,34 @@
  * This source code is licensed under the MIT license found in the
  * LICENSE file in the root directory of this source tree.
  */
-import { Feed } from 'feed';
-import { PluginOptions, BlogPost, BlogContentPaths, BlogMarkdownLoaderOptions } from './types';
-import { LoadContext } from '@docusaurus/types';
+import type { BlogPost, BlogContentPaths, BlogMarkdownLoaderOptions, BlogTags, BlogPaginated } from './types';
+import type { LoadContext } from '@docusaurus/types';
+import type { PluginOptions } from '@docusaurus/plugin-content-blog';
 export declare function truncate(fileString: string, truncateMarker: RegExp): string;
 export declare function getSourceToPermalink(blogPosts: BlogPost[]): Record<string, string>;
-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 paginateBlogPosts({ blogPosts, basePageUrl, blogTitle, blogDescription, postsPerPageOption, }: {
+    blogPosts: BlogPost[];
+    basePageUrl: string;
+    blogTitle: string;
+    blogDescription: string;
+    postsPerPageOption: number | 'ALL';
+}): BlogPaginated[];
+export declare function getBlogTags({ blogPosts, ...params }: {
+    blogPosts: BlogPost[];
+    blogTitle: string;
+    blogDescription: string;
+    postsPerPageOption: number | 'ALL';
+}): BlogTags;
+declare type ParsedBlogFileName = {
+    date: Date | undefined;
+    text: string;
+    slug: string;
+};
+export declare function parseBlogFileName(blogSourceRelative: string): ParsedBlogFileName;
+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 {};