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

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/client/contexts.d.ts

@@ -0,0 +1,33 @@
+/**
+ * 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 ReactNode } from 'react';
+import type { PropBlogPostContent, BlogMetadata } from '@docusaurus/plugin-content-blog';
+export declare function useBlogMetadata(): BlogMetadata;
+/**
+ * The React context value returned by the `useBlogPost()` hook.
+ * It contains useful data related to the currently browsed blog post.
+ */
+export type BlogPostContextValue = Pick<PropBlogPostContent, 'metadata' | 'frontMatter' | 'assets' | 'toc'> & {
+    readonly isBlogPostPage: boolean;
+};
+/**
+ * This is a very thin layer around the `content` received from the MDX loader.
+ * It provides metadata about the blog post to the children tree.
+ */
+export declare function BlogPostProvider({ children, content, isBlogPostPage, }: {
+    children: ReactNode;
+    content: PropBlogPostContent;
+    isBlogPostPage?: boolean;
+}): JSX.Element;
+/**
+ * Returns the data of the currently browsed blog post. Gives access to
+ * front matter, metadata, TOC, etc.
+ * When swizzling a low-level component (e.g. the "Edit this page" link)
+ * and you need some extra metadata, you don't have to drill the props
+ * all the way through the component tree: simply use this hook instead.
+ */
+export declare function useBlogPost(): BlogPostContextValue;

package/lib/client/contexts.js

@@ -0,0 +1,54 @@
+/**
+ * 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 React, { useMemo, useContext } from 'react';
+import { ReactContextError } from '@docusaurus/theme-common/internal';
+import useRouteContext from '@docusaurus/useRouteContext';
+export function useBlogMetadata() {
+    const routeContext = useRouteContext();
+    const blogMetadata = routeContext?.data?.blogMetadata;
+    if (!blogMetadata) {
+        throw new Error("useBlogMetadata() can't be called on the current route because the blog metadata could not be found in route context");
+    }
+    return blogMetadata;
+}
+const Context = React.createContext(null);
+/**
+ * Note: we don't use `PropBlogPostContent` as context value on purpose.
+ * Metadata is currently stored inside the MDX component, but we may want to
+ * change that in the future.
+ */
+function useContextValue({ content, isBlogPostPage, }) {
+    return useMemo(() => ({
+        metadata: content.metadata,
+        frontMatter: content.frontMatter,
+        assets: content.assets,
+        toc: content.toc,
+        isBlogPostPage,
+    }), [content, isBlogPostPage]);
+}
+/**
+ * This is a very thin layer around the `content` received from the MDX loader.
+ * It provides metadata about the blog post to the children tree.
+ */
+export function BlogPostProvider({ children, content, isBlogPostPage = false, }) {
+    const contextValue = useContextValue({ content, isBlogPostPage });
+    return <Context.Provider value={contextValue}>{children}</Context.Provider>;
+}
+/**
+ * Returns the data of the currently browsed blog post. Gives access to
+ * front matter, metadata, TOC, etc.
+ * When swizzling a low-level component (e.g. the "Edit this page" link)
+ * and you need some extra metadata, you don't have to drill the props
+ * all the way through the component tree: simply use this hook instead.
+ */
+export function useBlogPost() {
+    const blogPost = useContext(Context);
+    if (blogPost === null) {
+        throw new ReactContextError('BlogPostProvider');
+    }
+    return blogPost;
+}

package/lib/client/index.d.ts

@@ -4,5 +4,6 @@
  * This source code is licensed under the MIT license found in the
  * LICENSE file in the root directory of this source tree.
  */
-import type { BlogMetadata } from '@docusaurus/plugin-content-blog';
-export declare function useBlogMetadata(): BlogMetadata;
+export { BlogPostProvider, type BlogPostContextValue, useBlogPost, useBlogMetadata, } from './contexts';
+export { useBlogListPageStructuredData, useBlogPostStructuredData, } from './structuredDataUtils';
+export { BlogSidebarItemList, groupBlogSidebarItemsByYear, useVisibleBlogSidebarItems, } from './sidebarUtils';

package/lib/client/index.js

@@ -4,12 +4,6 @@
  * This source code is licensed under the MIT license found in the
  * LICENSE file in the root directory of this source tree.
  */
-import useRouteContext from '@docusaurus/useRouteContext';
-export function useBlogMetadata() {
-    const routeContext = useRouteContext();
-    const blogMetadata = routeContext?.data?.blogMetadata;
-    if (!blogMetadata) {
-        throw new Error("useBlogMetadata() can't be called on the current route because the blog metadata could not be found in route context");
-    }
-    return blogMetadata;
-}
+export { BlogPostProvider, useBlogPost, useBlogMetadata, } from './contexts';
+export { useBlogListPageStructuredData, useBlogPostStructuredData, } from './structuredDataUtils';
+export { BlogSidebarItemList, groupBlogSidebarItemsByYear, useVisibleBlogSidebarItems, } from './sidebarUtils';

package/lib/client/sidebarUtils.d.ts

@@ -0,0 +1,21 @@
+/**
+ * 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 ReactNode } from 'react';
+import type { BlogSidebarItem } from '@docusaurus/plugin-content-blog';
+/**
+ * Return the visible blog sidebar items to display.
+ * Unlisted items are filtered.
+ */
+export declare function useVisibleBlogSidebarItems(items: BlogSidebarItem[]): BlogSidebarItem[];
+export declare function groupBlogSidebarItemsByYear(items: BlogSidebarItem[]): [string, BlogSidebarItem[]][];
+export declare function BlogSidebarItemList({ items, ulClassName, liClassName, linkClassName, linkActiveClassName, }: {
+    items: BlogSidebarItem[];
+    ulClassName?: string;
+    liClassName?: string;
+    linkClassName?: string;
+    linkActiveClassName?: string;
+}): ReactNode;

package/lib/client/sidebarUtils.js

@@ -0,0 +1,49 @@
+/**
+ * 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 React, { useMemo } from 'react';
+import { useLocation } from '@docusaurus/router';
+import Link from '@docusaurus/Link';
+import { groupBy } from '@docusaurus/theme-common';
+import { isSamePath } from '@docusaurus/theme-common/internal';
+function isVisible(item, pathname) {
+    if (item.unlisted && !isSamePath(item.permalink, pathname)) {
+        return false;
+    }
+    return true;
+}
+/**
+ * Return the visible blog sidebar items to display.
+ * Unlisted items are filtered.
+ */
+export function useVisibleBlogSidebarItems(items) {
+    const { pathname } = useLocation();
+    return useMemo(() => items.filter((item) => isVisible(item, pathname)), [items, pathname]);
+}
+export function groupBlogSidebarItemsByYear(items) {
+    const groupedByYear = groupBy(items, (item) => {
+        return `${new Date(item.date).getFullYear()}`;
+    });
+    // "as" is safe here
+    // see https://github.com/microsoft/TypeScript/pull/56805#issuecomment-2196526425
+    const entries = Object.entries(groupedByYear);
+    // We have to use entries because of https://x.com/sebastienlorber/status/1806371668614369486
+    // Objects with string/number keys are automatically sorted asc...
+    // Even if keys are strings like "2024"
+    // We want descending order for years
+    // Alternative: using Map.groupBy (not affected by this "reordering")
+    entries.reverse();
+    return entries;
+}
+export function BlogSidebarItemList({ items, ulClassName, liClassName, linkClassName, linkActiveClassName, }) {
+    return (<ul className={ulClassName}>
+      {items.map((item) => (<li key={item.permalink} className={liClassName}>
+          <Link isNavLink to={item.permalink} className={linkClassName} activeClassName={linkActiveClassName}>
+            {item.title}
+          </Link>
+        </li>))}
+    </ul>);
+}

package/lib/client/sidebarUtils.test.d.ts

@@ -0,0 +1,7 @@
+/**
+ * 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.
+ */
+export {};

package/lib/client/sidebarUtils.test.js

@@ -0,0 +1,43 @@
+/**
+ * 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 { groupBlogSidebarItemsByYear } from './sidebarUtils';
+describe('groupBlogSidebarItemsByYear', () => {
+    const post1 = {
+        title: 'post1',
+        permalink: '/post1',
+        date: '2024-10-03',
+        unlisted: false,
+    };
+    const post2 = {
+        title: 'post2',
+        permalink: '/post2',
+        date: '2024-05-02',
+        unlisted: false,
+    };
+    const post3 = {
+        title: 'post3',
+        permalink: '/post3',
+        date: '2022-11-18',
+        unlisted: false,
+    };
+    it('can group items by year', () => {
+        const items = [post1, post2, post3];
+        const entries = groupBlogSidebarItemsByYear(items);
+        expect(entries).toEqual([
+            ['2024', [post1, post2]],
+            ['2022', [post3]],
+        ]);
+    });
+    it('always returns result in descending chronological order', () => {
+        const items = [post3, post1, post2];
+        const entries = groupBlogSidebarItemsByYear(items);
+        expect(entries).toEqual([
+            ['2024', [post1, post2]],
+            ['2022', [post3]],
+        ]);
+    });
+});

package/lib/client/structuredDataUtils.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 type { Props as BlogListPageStructuredDataProps } from '@theme/BlogListPage/StructuredData';
+import type { Blog, BlogPosting, WithContext } from 'schema-dts';
+export declare function useBlogListPageStructuredData(props: BlogListPageStructuredDataProps): WithContext<Blog>;
+export declare function useBlogPostStructuredData(): WithContext<BlogPosting>;

package/lib/client/structuredDataUtils.js

@@ -0,0 +1,122 @@
+/**
+ * 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 { useBaseUrlUtils } from '@docusaurus/useBaseUrl';
+import useDocusaurusContext from '@docusaurus/useDocusaurusContext';
+import { useBlogMetadata } from '@docusaurus/plugin-content-blog/client';
+import { useBlogPost } from './contexts';
+const convertDate = (dateMs) => new Date(dateMs).toISOString();
+function getBlogPost(blogPostContent, siteConfig, withBaseUrl) {
+    const { assets, frontMatter, metadata } = blogPostContent;
+    const { date, title, description, lastUpdatedAt } = metadata;
+    const image = assets.image ?? frontMatter.image;
+    const keywords = frontMatter.keywords ?? [];
+    const blogUrl = `${siteConfig.url}${metadata.permalink}`;
+    const dateModified = lastUpdatedAt ? convertDate(lastUpdatedAt) : undefined;
+    return {
+        '@type': 'BlogPosting',
+        '@id': blogUrl,
+        mainEntityOfPage: blogUrl,
+        url: blogUrl,
+        headline: title,
+        name: title,
+        description,
+        datePublished: date,
+        ...(dateModified ? { dateModified } : {}),
+        ...getAuthor(metadata.authors),
+        ...getImage(image, withBaseUrl, title),
+        ...(keywords ? { keywords } : {}),
+    };
+}
+function getAuthor(authors) {
+    const authorsStructuredData = authors.map(createPersonStructuredData);
+    return {
+        author: authorsStructuredData.length === 1
+            ? authorsStructuredData[0]
+            : authorsStructuredData,
+    };
+}
+function getImage(image, withBaseUrl, title) {
+    return image
+        ? {
+            image: createImageStructuredData({
+                imageUrl: withBaseUrl(image, { absolute: true }),
+                caption: `title image for the blog post: ${title}`,
+            }),
+        }
+        : {};
+}
+export function useBlogListPageStructuredData(props) {
+    const { siteConfig } = useDocusaurusContext();
+    const { withBaseUrl } = useBaseUrlUtils();
+    const { metadata: { blogDescription, blogTitle, permalink }, } = props;
+    const url = `${siteConfig.url}${permalink}`;
+    // details on structured data support: https://schema.org/Blog
+    return {
+        '@context': 'https://schema.org',
+        '@type': 'Blog',
+        '@id': url,
+        mainEntityOfPage: url,
+        headline: blogTitle,
+        description: blogDescription,
+        blogPost: props.items.map((blogItem) => getBlogPost(blogItem.content, siteConfig, withBaseUrl)),
+    };
+}
+export function useBlogPostStructuredData() {
+    const blogMetadata = useBlogMetadata();
+    const { assets, metadata } = useBlogPost();
+    const { siteConfig } = useDocusaurusContext();
+    const { withBaseUrl } = useBaseUrlUtils();
+    const { date, title, description, frontMatter, lastUpdatedAt } = metadata;
+    const image = assets.image ?? frontMatter.image;
+    const keywords = frontMatter.keywords ?? [];
+    const dateModified = lastUpdatedAt ? convertDate(lastUpdatedAt) : undefined;
+    const url = `${siteConfig.url}${metadata.permalink}`;
+    // details on structured data support: https://schema.org/BlogPosting
+    // BlogPosting is one of the structured data types that Google explicitly
+    // supports: https://developers.google.com/search/docs/appearance/structured-data/article#structured-data-type-definitions
+    return {
+        '@context': 'https://schema.org',
+        '@type': 'BlogPosting',
+        '@id': url,
+        mainEntityOfPage: url,
+        url,
+        headline: title,
+        name: title,
+        description,
+        datePublished: date,
+        ...(dateModified ? { dateModified } : {}),
+        ...getAuthor(metadata.authors),
+        ...getImage(image, withBaseUrl, title),
+        ...(keywords ? { keywords } : {}),
+        isPartOf: {
+            '@type': 'Blog',
+            '@id': `${siteConfig.url}${blogMetadata.blogBasePath}`,
+            name: blogMetadata.blogTitle,
+        },
+    };
+}
+/** @returns A {@link https://schema.org/Person} constructed from the {@link Author} */
+function createPersonStructuredData(author) {
+    return {
+        '@type': 'Person',
+        ...(author.name ? { name: author.name } : {}),
+        ...(author.title ? { description: author.title } : {}),
+        ...(author.url ? { url: author.url } : {}),
+        ...(author.email ? { email: author.email } : {}),
+        ...(author.imageURL ? { image: author.imageURL } : {}),
+    };
+}
+/** @returns A {@link https://schema.org/ImageObject} */
+function createImageStructuredData({ imageUrl, caption, }) {
+    return {
+        '@type': 'ImageObject',
+        '@id': imageUrl,
+        url: imageUrl,
+        contentUrl: imageUrl,
+        caption,
+    };
+}

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-6000",
   "description": "Blog plugin for Docusaurus.",
   "main": "lib/index.js",
   "types": "src/plugin-content-blog.d.ts",
@@ -31,13 +31,14 @@
   },
   "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-6000",
+    "@docusaurus/logger": "0.0.0-6000",
+    "@docusaurus/mdx-loader": "0.0.0-6000",
+    "@docusaurus/theme-common": "0.0.0-6000",
+    "@docusaurus/types": "0.0.0-6000",
+    "@docusaurus/utils": "0.0.0-6000",
+    "@docusaurus/utils-common": "0.0.0-6000",
+    "@docusaurus/utils-validation": "0.0.0-6000",
     "cheerio": "^1.0.0-rc.12",
     "feed": "^4.2.2",
     "fs-extra": "^11.1.1",
@@ -59,5 +60,5 @@
   "devDependencies": {
     "@total-typescript/shoehorn": "^0.1.2"
   },
-  "gitHead": "4905b76b4b39c2f102bbc78d018933f57ea39b78"
+  "gitHead": "10f44ae468ae6751fa53eb8af6441265f0e5075c"
 }

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/client/contexts.tsx

@@ -0,0 +1,95 @@
+/**
+ * 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 React, {useMemo, type ReactNode, useContext} from 'react';
+import {ReactContextError} from '@docusaurus/theme-common/internal';
+import useRouteContext from '@docusaurus/useRouteContext';
+
+import type {
+  PropBlogPostContent,
+  BlogMetadata,
+} from '@docusaurus/plugin-content-blog';
+
+export function useBlogMetadata(): BlogMetadata {
+  const routeContext = useRouteContext();
+  const blogMetadata = routeContext?.data?.blogMetadata;
+  if (!blogMetadata) {
+    throw new Error(
+      "useBlogMetadata() can't be called on the current route because the blog metadata could not be found in route context",
+    );
+  }
+  return blogMetadata as BlogMetadata;
+}
+
+/**
+ * The React context value returned by the `useBlogPost()` hook.
+ * It contains useful data related to the currently browsed blog post.
+ */
+export type BlogPostContextValue = Pick<
+  PropBlogPostContent,
+  'metadata' | 'frontMatter' | 'assets' | 'toc'
+> & {
+  readonly isBlogPostPage: boolean;
+};
+
+const Context = React.createContext<BlogPostContextValue | null>(null);
+
+/**
+ * Note: we don't use `PropBlogPostContent` as context value on purpose.
+ * Metadata is currently stored inside the MDX component, but we may want to
+ * change that in the future.
+ */
+function useContextValue({
+  content,
+  isBlogPostPage,
+}: {
+  content: PropBlogPostContent;
+  isBlogPostPage: boolean;
+}): BlogPostContextValue {
+  return useMemo(
+    () => ({
+      metadata: content.metadata,
+      frontMatter: content.frontMatter,
+      assets: content.assets,
+      toc: content.toc,
+      isBlogPostPage,
+    }),
+    [content, isBlogPostPage],
+  );
+}
+
+/**
+ * This is a very thin layer around the `content` received from the MDX loader.
+ * It provides metadata about the blog post to the children tree.
+ */
+export function BlogPostProvider({
+  children,
+  content,
+  isBlogPostPage = false,
+}: {
+  children: ReactNode;
+  content: PropBlogPostContent;
+  isBlogPostPage?: boolean;
+}): JSX.Element {
+  const contextValue = useContextValue({content, isBlogPostPage});
+  return <Context.Provider value={contextValue}>{children}</Context.Provider>;
+}
+
+/**
+ * Returns the data of the currently browsed blog post. Gives access to
+ * front matter, metadata, TOC, etc.
+ * When swizzling a low-level component (e.g. the "Edit this page" link)
+ * and you need some extra metadata, you don't have to drill the props
+ * all the way through the component tree: simply use this hook instead.
+ */
+export function useBlogPost(): BlogPostContextValue {
+  const blogPost = useContext(Context);
+  if (blogPost === null) {
+    throw new ReactContextError('BlogPostProvider');
+  }
+  return blogPost;
+}

package/src/client/index.tsx

@@ -0,0 +1,24 @@
+/**
+ * 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.
+ */
+
+export {
+  BlogPostProvider,
+  type BlogPostContextValue,
+  useBlogPost,
+  useBlogMetadata,
+} from './contexts';
+
+export {
+  useBlogListPageStructuredData,
+  useBlogPostStructuredData,
+} from './structuredDataUtils';
+
+export {
+  BlogSidebarItemList,
+  groupBlogSidebarItemsByYear,
+  useVisibleBlogSidebarItems,
+} from './sidebarUtils';

package/src/client/sidebarUtils.test.ts

@@ -0,0 +1,52 @@
+/**
+ * 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 {groupBlogSidebarItemsByYear} from './sidebarUtils';
+import type {BlogSidebarItem} from '@docusaurus/plugin-content-blog';
+
+describe('groupBlogSidebarItemsByYear', () => {
+  const post1: BlogSidebarItem = {
+    title: 'post1',
+    permalink: '/post1',
+    date: '2024-10-03',
+    unlisted: false,
+  };
+
+  const post2: BlogSidebarItem = {
+    title: 'post2',
+    permalink: '/post2',
+    date: '2024-05-02',
+    unlisted: false,
+  };
+
+  const post3: BlogSidebarItem = {
+    title: 'post3',
+    permalink: '/post3',
+    date: '2022-11-18',
+    unlisted: false,
+  };
+
+  it('can group items by year', () => {
+    const items: BlogSidebarItem[] = [post1, post2, post3];
+    const entries = groupBlogSidebarItemsByYear(items);
+
+    expect(entries).toEqual([
+      ['2024', [post1, post2]],
+      ['2022', [post3]],
+    ]);
+  });
+
+  it('always returns result in descending chronological order', () => {
+    const items: BlogSidebarItem[] = [post3, post1, post2];
+    const entries = groupBlogSidebarItemsByYear(items);
+
+    expect(entries).toEqual([
+      ['2024', [post1, post2]],
+      ['2022', [post3]],
+    ]);
+  });
+});

package/src/client/sidebarUtils.tsx

@@ -0,0 +1,85 @@
+/**
+ * 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 React, {type ReactNode, useMemo} from 'react';
+import {useLocation} from '@docusaurus/router';
+import Link from '@docusaurus/Link';
+import {groupBy} from '@docusaurus/theme-common';
+import {isSamePath} from '@docusaurus/theme-common/internal';
+import type {BlogSidebarItem} from '@docusaurus/plugin-content-blog';
+
+function isVisible(item: BlogSidebarItem, pathname: string): boolean {
+  if (item.unlisted && !isSamePath(item.permalink, pathname)) {
+    return false;
+  }
+  return true;
+}
+
+/**
+ * Return the visible blog sidebar items to display.
+ * Unlisted items are filtered.
+ */
+export function useVisibleBlogSidebarItems(
+  items: BlogSidebarItem[],
+): BlogSidebarItem[] {
+  const {pathname} = useLocation();
+  return useMemo(
+    () => items.filter((item) => isVisible(item, pathname)),
+    [items, pathname],
+  );
+}
+
+export function groupBlogSidebarItemsByYear(
+  items: BlogSidebarItem[],
+): [string, BlogSidebarItem[]][] {
+  const groupedByYear = groupBy(items, (item) => {
+    return `${new Date(item.date).getFullYear()}`;
+  });
+  // "as" is safe here
+  // see https://github.com/microsoft/TypeScript/pull/56805#issuecomment-2196526425
+  const entries = Object.entries(groupedByYear) as [
+    string,
+    BlogSidebarItem[],
+  ][];
+  // We have to use entries because of https://x.com/sebastienlorber/status/1806371668614369486
+  // Objects with string/number keys are automatically sorted asc...
+  // Even if keys are strings like "2024"
+  // We want descending order for years
+  // Alternative: using Map.groupBy (not affected by this "reordering")
+  entries.reverse();
+  return entries;
+}
+
+export function BlogSidebarItemList({
+  items,
+  ulClassName,
+  liClassName,
+  linkClassName,
+  linkActiveClassName,
+}: {
+  items: BlogSidebarItem[];
+  ulClassName?: string;
+  liClassName?: string;
+  linkClassName?: string;
+  linkActiveClassName?: string;
+}): ReactNode {
+  return (
+    <ul className={ulClassName}>
+      {items.map((item) => (
+        <li key={item.permalink} className={liClassName}>
+          <Link
+            isNavLink
+            to={item.permalink}
+            className={linkClassName}
+            activeClassName={linkActiveClassName}>
+            {item.title}
+          </Link>
+        </li>
+      ))}
+    </ul>
+  );
+}

package/src/client/structuredDataUtils.ts

@@ -0,0 +1,178 @@
+/**
+ * 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 {useBaseUrlUtils, type BaseUrlUtils} from '@docusaurus/useBaseUrl';
+import useDocusaurusContext from '@docusaurus/useDocusaurusContext';
+import {useBlogMetadata} from '@docusaurus/plugin-content-blog/client';
+import type {Props as BlogListPageStructuredDataProps} from '@theme/BlogListPage/StructuredData';
+import {useBlogPost} from './contexts';
+
+import type {
+  Blog,
+  BlogPosting,
+  WithContext,
+  Person,
+  ImageObject,
+} from 'schema-dts';
+import type {
+  Author,
+  PropBlogPostContent,
+} from '@docusaurus/plugin-content-blog';
+import type {DocusaurusConfig} from '@docusaurus/types';
+
+const convertDate = (dateMs: number) => new Date(dateMs).toISOString();
+
+function getBlogPost(
+  blogPostContent: PropBlogPostContent,
+  siteConfig: DocusaurusConfig,
+  withBaseUrl: BaseUrlUtils['withBaseUrl'],
+): BlogPosting {
+  const {assets, frontMatter, metadata} = blogPostContent;
+  const {date, title, description, lastUpdatedAt} = metadata;
+
+  const image = assets.image ?? frontMatter.image;
+  const keywords = frontMatter.keywords ?? [];
+
+  const blogUrl = `${siteConfig.url}${metadata.permalink}`;
+
+  const dateModified = lastUpdatedAt ? convertDate(lastUpdatedAt) : undefined;
+
+  return {
+    '@type': 'BlogPosting',
+    '@id': blogUrl,
+    mainEntityOfPage: blogUrl,
+    url: blogUrl,
+    headline: title,
+    name: title,
+    description,
+    datePublished: date,
+    ...(dateModified ? {dateModified} : {}),
+    ...getAuthor(metadata.authors),
+    ...getImage(image, withBaseUrl, title),
+    ...(keywords ? {keywords} : {}),
+  };
+}
+
+function getAuthor(authors: Author[]) {
+  const authorsStructuredData = authors.map(createPersonStructuredData);
+  return {
+    author:
+      authorsStructuredData.length === 1
+        ? authorsStructuredData[0]
+        : authorsStructuredData,
+  };
+}
+
+function getImage(
+  image: string | undefined,
+  withBaseUrl: BaseUrlUtils['withBaseUrl'],
+  title: string,
+) {
+  return image
+    ? {
+        image: createImageStructuredData({
+          imageUrl: withBaseUrl(image, {absolute: true}),
+          caption: `title image for the blog post: ${title}`,
+        }),
+      }
+    : {};
+}
+
+export function useBlogListPageStructuredData(
+  props: BlogListPageStructuredDataProps,
+): WithContext<Blog> {
+  const {siteConfig} = useDocusaurusContext();
+  const {withBaseUrl} = useBaseUrlUtils();
+
+  const {
+    metadata: {blogDescription, blogTitle, permalink},
+  } = props;
+
+  const url = `${siteConfig.url}${permalink}`;
+
+  // details on structured data support: https://schema.org/Blog
+  return {
+    '@context': 'https://schema.org',
+    '@type': 'Blog',
+    '@id': url,
+    mainEntityOfPage: url,
+    headline: blogTitle,
+    description: blogDescription,
+    blogPost: props.items.map((blogItem) =>
+      getBlogPost(blogItem.content, siteConfig, withBaseUrl),
+    ),
+  };
+}
+
+export function useBlogPostStructuredData(): WithContext<BlogPosting> {
+  const blogMetadata = useBlogMetadata();
+  const {assets, metadata} = useBlogPost();
+  const {siteConfig} = useDocusaurusContext();
+  const {withBaseUrl} = useBaseUrlUtils();
+
+  const {date, title, description, frontMatter, lastUpdatedAt} = metadata;
+
+  const image = assets.image ?? frontMatter.image;
+  const keywords = frontMatter.keywords ?? [];
+
+  const dateModified = lastUpdatedAt ? convertDate(lastUpdatedAt) : undefined;
+
+  const url = `${siteConfig.url}${metadata.permalink}`;
+
+  // details on structured data support: https://schema.org/BlogPosting
+  // BlogPosting is one of the structured data types that Google explicitly
+  // supports: https://developers.google.com/search/docs/appearance/structured-data/article#structured-data-type-definitions
+  return {
+    '@context': 'https://schema.org',
+    '@type': 'BlogPosting',
+    '@id': url,
+    mainEntityOfPage: url,
+    url,
+    headline: title,
+    name: title,
+    description,
+    datePublished: date,
+    ...(dateModified ? {dateModified} : {}),
+    ...getAuthor(metadata.authors),
+    ...getImage(image, withBaseUrl, title),
+    ...(keywords ? {keywords} : {}),
+    isPartOf: {
+      '@type': 'Blog',
+      '@id': `${siteConfig.url}${blogMetadata.blogBasePath}`,
+      name: blogMetadata.blogTitle,
+    },
+  };
+}
+
+/** @returns A {@link https://schema.org/Person} constructed from the {@link Author} */
+function createPersonStructuredData(author: Author): Person {
+  return {
+    '@type': 'Person',
+    ...(author.name ? {name: author.name} : {}),
+    ...(author.title ? {description: author.title} : {}),
+    ...(author.url ? {url: author.url} : {}),
+    ...(author.email ? {email: author.email} : {}),
+    ...(author.imageURL ? {image: author.imageURL} : {}),
+  };
+}
+
+/** @returns A {@link https://schema.org/ImageObject} */
+function createImageStructuredData({
+  imageUrl,
+  caption,
+}: {
+  imageUrl: string;
+  caption: string;
+}): ImageObject {
+  return {
+    '@type': 'ImageObject',
+    '@id': imageUrl,
+    url: imageUrl,
+    contentUrl: imageUrl,
+    caption,
+  };
+}

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;
   };
 
   /**

package/src/client/index.ts

@@ -1,20 +0,0 @@
-/**
- * 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 useRouteContext from '@docusaurus/useRouteContext';
-import type {BlogMetadata} from '@docusaurus/plugin-content-blog';
-
-export function useBlogMetadata(): BlogMetadata {
-  const routeContext = useRouteContext();
-  const blogMetadata = routeContext?.data?.blogMetadata;
-  if (!blogMetadata) {
-    throw new Error(
-      "useBlogMetadata() can't be called on the current route because the blog metadata could not be found in route context",
-    );
-  }
-  return blogMetadata as BlogMetadata;
-}