@docusaurus/plugin-content-blog 0.0.0-5994 → 0.0.0-5995

package/lib/authors.js

@@ -9,8 +9,11 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.validateAuthorsMap = validateAuthorsMap;
 exports.getAuthorsMap = getAuthorsMap;
 exports.getBlogPostAuthors = getBlogPostAuthors;
+const tslib_1 = require("tslib");
+const _ = tslib_1.__importStar(require("lodash"));
 const utils_1 = require("@docusaurus/utils");
 const utils_validation_1 = require("@docusaurus/utils-validation");
+const authorsSocials_1 = require("./authorsSocials");
 const AuthorsMapSchema = utils_validation_1.Joi.object()
     .pattern(utils_validation_1.Joi.string(), utils_validation_1.Joi.object({
     name: utils_validation_1.Joi.string(),
@@ -18,6 +21,7 @@ const AuthorsMapSchema = utils_validation_1.Joi.object()
     imageURL: utils_validation_1.URISchema,
     title: utils_validation_1.Joi.string(),
     email: utils_validation_1.Joi.string(),
+    socials: authorsSocials_1.AuthorSocialsSchema,
 })
     .rename('image_url', 'imageURL')
     .or('name', 'imageURL')
@@ -37,12 +41,24 @@ function validateAuthorsMap(content) {
     }
     return value;
 }
+function normalizeAuthor(author) {
+    return {
+        ...author,
+        socials: author.socials ? (0, authorsSocials_1.normalizeSocials)(author.socials) : undefined,
+    };
+}
+function normalizeAuthorsMap(authorsMap) {
+    return _.mapValues(authorsMap, normalizeAuthor);
+}
 async function getAuthorsMap(params) {
-    return (0, utils_1.getDataFileData)({
+    const authorsMap = await (0, utils_1.getDataFileData)({
         filePath: params.authorsMapPath,
         contentPaths: params.contentPaths,
         fileType: 'authors map',
-    }, validateAuthorsMap);
+    }, 
+    // TODO annoying to test: tightly coupled FS reads + validation...
+    validateAuthorsMap);
+    return authorsMap ? normalizeAuthorsMap(authorsMap) : undefined;
 }
 function normalizeImageUrl({ imageURL, baseUrl, }) {
     return imageURL?.startsWith('/')
@@ -70,7 +86,7 @@ function getFrontMatterAuthorLegacy({ baseUrl, frontMatter, }) {
     return undefined;
 }
 function normalizeFrontMatterAuthors(frontMatterAuthors = []) {
-    function normalizeAuthor(authorInput) {
+    function normalizeFrontMatterAuthor(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
@@ -80,8 +96,8 @@ function normalizeFrontMatterAuthors(frontMatterAuthors = []) {
         return authorInput;
     }
     return Array.isArray(frontMatterAuthors)
-        ? frontMatterAuthors.map(normalizeAuthor)
-        : [normalizeAuthor(frontMatterAuthors)];
+        ? frontMatterAuthors.map(normalizeFrontMatterAuthor)
+        : [normalizeFrontMatterAuthor(frontMatterAuthors)];
 }
 function getFrontMatterAuthors(params) {
     const { authorsMap } = params;
@@ -105,11 +121,11 @@ ${Object.keys(authorsMap)
         return undefined;
     }
     function toAuthor(frontMatterAuthor) {
-        return {
+        return normalizeAuthor({
             // Author def from authorsMap can be locally overridden by front matter
             ...getAuthorsMapAuthor(frontMatterAuthor.key),
             ...frontMatterAuthor,
-        };
+        });
     }
     return frontMatterAuthors.map(toAuthor);
 }

package/lib/authorsSocials.d.ts

@@ -0,0 +1,10 @@
+/**
+ * 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 { Joi } from '@docusaurus/utils-validation';
+import type { AuthorSocials } from '@docusaurus/plugin-content-blog';
+export declare const AuthorSocialsSchema: Joi.ObjectSchema<AuthorSocials>;
+export declare const normalizeSocials: (socials: AuthorSocials) => AuthorSocials;

package/lib/authorsSocials.js

@@ -0,0 +1,48 @@
+"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.normalizeSocials = exports.AuthorSocialsSchema = void 0;
+const utils_validation_1 = require("@docusaurus/utils-validation");
+exports.AuthorSocialsSchema = utils_validation_1.Joi.object({
+    twitter: utils_validation_1.Joi.string(),
+    github: utils_validation_1.Joi.string(),
+    linkedin: utils_validation_1.Joi.string(),
+    // StackOverflow userIds like '82609' are parsed as numbers by Yaml
+    stackoverflow: utils_validation_1.Joi.alternatives()
+        .try(utils_validation_1.Joi.number(), utils_validation_1.Joi.string())
+        .custom((val) => String(val)),
+    x: utils_validation_1.Joi.string(),
+}).unknown();
+const PredefinedPlatformNormalizers = {
+    x: (handle) => `https://x.com/${handle}`,
+    twitter: (handle) => `https://twitter.com/${handle}`,
+    github: (handle) => `https://github.com/${handle}`,
+    linkedin: (handle) => `https://www.linkedin.com/in/${handle}/`,
+    stackoverflow: (userId) => `https://stackoverflow.com/users/${userId}`,
+};
+function normalizeSocialEntry([platform, value]) {
+    const normalizer = PredefinedPlatformNormalizers[platform.toLowerCase()];
+    const isAbsoluteUrl = value.startsWith('http://') || value.startsWith('https://');
+    if (isAbsoluteUrl) {
+        return [platform, value];
+    }
+    else if (value.includes('/')) {
+        throw new Error(`Author socials should be usernames/userIds/handles, or fully qualified HTTP(s) absolute URLs.
+Social platform '${platform}' has illegal value '${value}'`);
+    }
+    if (normalizer && !isAbsoluteUrl) {
+        const normalizedPlatform = platform.toLowerCase();
+        const normalizedValue = normalizer(value);
+        return [normalizedPlatform, normalizedValue];
+    }
+    return [platform, value];
+}
+const normalizeSocials = (socials) => {
+    return Object.fromEntries(Object.entries(socials).map(normalizeSocialEntry));
+};
+exports.normalizeSocials = normalizeSocials;

package/lib/frontMatter.js

@@ -8,12 +8,14 @@ exports.validateBlogPostFrontMatter = validateBlogPostFrontMatter;
  * LICENSE file in the root directory of this source tree.
  */
 const utils_validation_1 = require("@docusaurus/utils-validation");
+const authorsSocials_1 = require("./authorsSocials");
 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(),
+    socials: authorsSocials_1.AuthorSocialsSchema,
 })
     .or('key', 'name', 'imageURL')
     .rename('image_url', 'imageURL', { alias: true });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@docusaurus/plugin-content-blog",
-  "version": "0.0.0-5994",
+  "version": "0.0.0-5995",
   "description": "Blog plugin for Docusaurus.",
   "main": "lib/index.js",
   "types": "src/plugin-content-blog.d.ts",
@@ -31,13 +31,13 @@
   },
   "license": "MIT",
   "dependencies": {
-    "@docusaurus/core": "0.0.0-5994",
-    "@docusaurus/logger": "0.0.0-5994",
-    "@docusaurus/mdx-loader": "0.0.0-5994",
-    "@docusaurus/types": "0.0.0-5994",
-    "@docusaurus/utils": "0.0.0-5994",
-    "@docusaurus/utils-common": "0.0.0-5994",
-    "@docusaurus/utils-validation": "0.0.0-5994",
+    "@docusaurus/core": "0.0.0-5995",
+    "@docusaurus/logger": "0.0.0-5995",
+    "@docusaurus/mdx-loader": "0.0.0-5995",
+    "@docusaurus/types": "0.0.0-5995",
+    "@docusaurus/utils": "0.0.0-5995",
+    "@docusaurus/utils-common": "0.0.0-5995",
+    "@docusaurus/utils-validation": "0.0.0-5995",
     "cheerio": "^1.0.0-rc.12",
     "feed": "^4.2.2",
     "fs-extra": "^11.1.1",
@@ -59,5 +59,5 @@
   "devDependencies": {
     "@total-typescript/shoehorn": "^0.1.2"
   },
-  "gitHead": "4905b76b4b39c2f102bbc78d018933f57ea39b78"
+  "gitHead": "c12bf10b9832a94916891f384814d62c4f49fd34"
 }

package/src/authors.ts

@@ -5,8 +5,10 @@
  * LICENSE file in the root directory of this source tree.
  */
 
+import * as _ from 'lodash';
 import {getDataFileData, normalizeUrl} from '@docusaurus/utils';
 import {Joi, URISchema} from '@docusaurus/utils-validation';
+import {AuthorSocialsSchema, normalizeSocials} from './authorsSocials';
 import type {BlogContentPaths} from './types';
 import type {
   Author,
@@ -20,12 +22,13 @@ export type AuthorsMap = {[authorKey: string]: Author};
 const AuthorsMapSchema = Joi.object<AuthorsMap>()
   .pattern(
     Joi.string(),
-    Joi.object({
+    Joi.object<Author>({
       name: Joi.string(),
       url: URISchema,
       imageURL: URISchema,
       title: Joi.string(),
       email: Joi.string(),
+      socials: AuthorSocialsSchema,
     })
       .rename('image_url', 'imageURL')
       .or('name', 'imageURL')
@@ -51,18 +54,32 @@ export function validateAuthorsMap(content: unknown): AuthorsMap {
   return value;
 }
 
+function normalizeAuthor(author: Author): Author {
+  return {
+    ...author,
+    socials: author.socials ? normalizeSocials(author.socials) : undefined,
+  };
+}
+
+function normalizeAuthorsMap(authorsMap: AuthorsMap): AuthorsMap {
+  return _.mapValues(authorsMap, normalizeAuthor);
+}
+
 export async function getAuthorsMap(params: {
   authorsMapPath: string;
   contentPaths: BlogContentPaths;
 }): Promise<AuthorsMap | undefined> {
-  return getDataFileData(
+  const authorsMap = await getDataFileData(
     {
       filePath: params.authorsMapPath,
       contentPaths: params.contentPaths,
       fileType: 'authors map',
     },
+    // TODO annoying to test: tightly coupled FS reads + validation...
     validateAuthorsMap,
   );
+
+  return authorsMap ? normalizeAuthorsMap(authorsMap) : undefined;
 }
 
 type AuthorsParam = {
@@ -115,7 +132,7 @@ function getFrontMatterAuthorLegacy({
 function normalizeFrontMatterAuthors(
   frontMatterAuthors: BlogPostFrontMatterAuthors = [],
 ): BlogPostFrontMatterAuthor[] {
-  function normalizeAuthor(
+  function normalizeFrontMatterAuthor(
     authorInput: string | Author,
   ): BlogPostFrontMatterAuthor {
     if (typeof authorInput === 'string') {
@@ -128,8 +145,8 @@ function normalizeFrontMatterAuthors(
   }
 
   return Array.isArray(frontMatterAuthors)
-    ? frontMatterAuthors.map(normalizeAuthor)
-    : [normalizeAuthor(frontMatterAuthors)];
+    ? frontMatterAuthors.map(normalizeFrontMatterAuthor)
+    : [normalizeFrontMatterAuthor(frontMatterAuthors)];
 }
 
 function getFrontMatterAuthors(params: AuthorsParam): Author[] {
@@ -158,11 +175,11 @@ ${Object.keys(authorsMap)
   }
 
   function toAuthor(frontMatterAuthor: BlogPostFrontMatterAuthor): Author {
-    return {
+    return normalizeAuthor({
       // Author def from authorsMap can be locally overridden by front matter
       ...getAuthorsMapAuthor(frontMatterAuthor.key),
       ...frontMatterAuthor,
-    };
+    });
   }
 
   return frontMatterAuthors.map(toAuthor);

package/src/authorsSocials.ts

@@ -0,0 +1,64 @@
+/**
+ * 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 {Joi} from '@docusaurus/utils-validation';
+
+import type {
+  AuthorSocials,
+  SocialPlatformKey,
+} from '@docusaurus/plugin-content-blog';
+
+export const AuthorSocialsSchema = Joi.object<AuthorSocials>({
+  twitter: Joi.string(),
+  github: Joi.string(),
+  linkedin: Joi.string(),
+  // StackOverflow userIds like '82609' are parsed as numbers by Yaml
+  stackoverflow: Joi.alternatives()
+    .try(Joi.number(), Joi.string())
+    .custom((val) => String(val)),
+  x: Joi.string(),
+}).unknown();
+
+type PredefinedPlatformNormalizer = (value: string) => string;
+
+const PredefinedPlatformNormalizers: Record<
+  SocialPlatformKey | string,
+  PredefinedPlatformNormalizer
+> = {
+  x: (handle: string) => `https://x.com/${handle}`,
+  twitter: (handle: string) => `https://twitter.com/${handle}`,
+  github: (handle: string) => `https://github.com/${handle}`,
+  linkedin: (handle: string) => `https://www.linkedin.com/in/${handle}/`,
+  stackoverflow: (userId: string) =>
+    `https://stackoverflow.com/users/${userId}`,
+};
+
+type SocialEntry = [string, string];
+
+function normalizeSocialEntry([platform, value]: SocialEntry): SocialEntry {
+  const normalizer = PredefinedPlatformNormalizers[platform.toLowerCase()];
+  const isAbsoluteUrl =
+    value.startsWith('http://') || value.startsWith('https://');
+  if (isAbsoluteUrl) {
+    return [platform, value];
+  } else if (value.includes('/')) {
+    throw new Error(
+      `Author socials should be usernames/userIds/handles, or fully qualified HTTP(s) absolute URLs.
+Social platform '${platform}' has illegal value '${value}'`,
+    );
+  }
+  if (normalizer && !isAbsoluteUrl) {
+    const normalizedPlatform = platform.toLowerCase();
+    const normalizedValue = normalizer(value);
+    return [normalizedPlatform as SocialPlatformKey, normalizedValue];
+  }
+  return [platform, value];
+}
+
+export const normalizeSocials = (socials: AuthorSocials): AuthorSocials => {
+  return Object.fromEntries(Object.entries(socials).map(normalizeSocialEntry));
+};

package/src/frontMatter.ts

@@ -13,6 +13,7 @@ import {
   URISchema,
   validateFrontMatter,
 } from '@docusaurus/utils-validation';
+import {AuthorSocialsSchema} from './authorsSocials';
 import type {BlogPostFrontMatter} from '@docusaurus/plugin-content-blog';
 
 const BlogPostFrontMatterAuthorSchema = Joi.object({
@@ -21,6 +22,7 @@ const BlogPostFrontMatterAuthorSchema = Joi.object({
   title: Joi.string(),
   url: URISchema,
   imageURL: Joi.string(),
+  socials: AuthorSocialsSchema,
 })
   .or('key', 'name', 'imageURL')
   .rename('image_url', 'imageURL', {alias: true});

package/src/plugin-content-blog.d.ts

@@ -43,6 +43,29 @@ yarn workspace v1.22.19image` is a collocated image path, this entry will be the
     authorsImageUrls: (string | undefined)[];
   };
 
+  /**
+   * Note we don't pre-define all possible platforms
+   * Users can add their own custom platforms if needed
+   */
+  export type SocialPlatformKey =
+    | 'twitter'
+    | 'github'
+    | 'linkedin'
+    | 'stackoverflow'
+    | 'x';
+
+  /**
+   * Social platforms of the author.
+   * The record value is usually the fully qualified link of the social profile.
+   * For pre-defined platforms, it's possible to pass a handle instead
+   */
+  export type AuthorSocials = Partial<Record<SocialPlatformKey, string>> & {
+    /**
+     * Unknown keys are allowed: users can pass additional social platforms
+     */
+    [customAuthorSocialPlatform: string]: string;
+  };
+
   export type Author = {
     key?: string; // TODO temporary, need refactor
 
@@ -69,11 +92,15 @@ yarn workspace v1.22.19image` is a collocated image path, this entry will be the
      * to generate a fallback `mailto:` URL.
      */
     email?: string;
+    /**
+     * Social platforms of the author
+     * Usually displayed as a list of social icon links.
+     */
+    socials?: AuthorSocials;
     /**
      * Unknown keys are allowed, so that we can pass custom fields to authors,
-     * e.g., `twitter`.
      */
-    [key: string]: unknown;
+    [customAuthorAttribute: string]: unknown;
   };
 
   /**