@azerion/bunosaurus-plugin-content-blog 0.0.0-stage → 4.0.0

package/lib/authorsProblems.js

@@ -0,0 +1,51 @@
+"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.reportAuthorsProblems = reportAuthorsProblems;
+exports.reportInlineAuthors = reportInlineAuthors;
+exports.reportDuplicateAuthors = reportDuplicateAuthors;
+const tslib_1 = require("tslib");
+const lodash_1 = tslib_1.__importDefault(require("lodash"));
+const logger_1 = tslib_1.__importDefault(require("@docusaurus/logger"));
+function reportAuthorsProblems(params) {
+    reportInlineAuthors(params);
+    reportDuplicateAuthors(params);
+}
+function reportInlineAuthors({ authors, blogSourceRelative, options: { onInlineAuthors, authorsMapPath }, }) {
+    if (onInlineAuthors === 'ignore') {
+        return;
+    }
+    const inlineAuthors = authors.filter((author) => !author.key);
+    if (inlineAuthors.length > 0) {
+        logger_1.default.report(onInlineAuthors)(logger_1.default.interpolate `Some blog authors used in path=${blogSourceRelative} are not defined in path=${authorsMapPath}:
+- ${inlineAuthors.map(authorToString).join('\n- ')}
+
+Note that we recommend to declare authors once in a path=${authorsMapPath} file and reference them by key in blog posts front matter to avoid author info duplication.
+But if you want to allow inline blog authors, you can disable this message by setting onInlineAuthors: 'ignore' in your blog plugin options.
+More info at url=${'https://docusaurus.io/docs/blog'}
+`);
+    }
+}
+function reportDuplicateAuthors({ authors, blogSourceRelative, }) {
+    const duplicateAuthors = (0, lodash_1.default)(authors)
+        // for now we only check for predefined authors duplicates
+        .filter((author) => !!author.key)
+        .groupBy((author) => author.key)
+        .pickBy((authorsByKey) => authorsByKey.length > 1)
+        // We only keep the "test" of all the duplicate groups
+        // The first author of a group is not really a duplicate...
+        .flatMap(([, ...rest]) => rest)
+        .value();
+    if (duplicateAuthors.length > 0) {
+        throw new Error(logger_1.default.interpolate `Duplicate blog post authors were found in blog post path=${blogSourceRelative} front matter:
+- ${duplicateAuthors.map(authorToString).join('\n- ')}`);
+    }
+}
+function authorToString(author) {
+    return JSON.stringify(author);
+}

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,68 @@
+"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(),
+    bluesky: utils_validation_1.Joi.string(),
+    instagram: utils_validation_1.Joi.string(),
+    threads: utils_validation_1.Joi.string(),
+    mastodon: utils_validation_1.Joi.string(),
+    twitch: utils_validation_1.Joi.string(),
+    youtube: utils_validation_1.Joi.string(),
+    email: 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}`,
+    bluesky: (handle) => `https://bsky.app/profile/${handle}`,
+    instagram: (handle) => `https://www.instagram.com/${handle}`,
+    threads: (handle) => `https://www.threads.net/@${handle}`,
+    mastodon: (handle) => `https://mastodon.social/@${handle}`, // can be in format user@other.server and it will redirect if needed
+    twitch: (handle) => `https://twitch.tv/${handle}`,
+    youtube: (handle) => `https://youtube.com/@${handle}`, // https://support.google.com/youtube/answer/6180214?hl=en
+    email: (email) => `mailto:${email}`,
+};
+function normalizeSocialEntry([platform, value]) {
+    if (typeof value !== 'string') {
+        throw new Error(`Author socials should be usernames/userIds/handles, or fully qualified HTTP(s) absolute URLs.
+Social platform '${platform}' has illegal value '${value}'`);
+    }
+    const isAbsoluteUrl = value.startsWith('http://') ||
+        value.startsWith('https://') ||
+        value.startsWith('mailto:');
+    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}'`);
+    }
+    const normalizer = PredefinedPlatformNormalizers[platform.toLowerCase()];
+    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/blogUtils.d.ts

@@ -0,0 +1,50 @@
+/**
+ * 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 { TagsFile } from '@docusaurus/utils';
+import type { LoadContext, VcsConfig } from '@docusaurus/types';
+import type { AuthorsMap, PluginOptions, BlogPost, BlogTags, BlogPaginated } from '@docusaurus/plugin-content-blog';
+import type { BlogContentPaths } from './types';
+export declare function truncate(fileString: string, truncateMarker: RegExp): string;
+export declare function reportUntruncatedBlogPosts({ blogPosts, onUntruncatedBlogPosts, }: {
+    blogPosts: BlogPost[];
+    onUntruncatedBlogPosts: PluginOptions['onUntruncatedBlogPosts'];
+}): void;
+export declare function paginateBlogPosts({ blogPosts, basePageUrl, blogTitle, blogDescription, postsPerPageOption, pageBasePath, }: {
+    blogPosts: BlogPost[];
+    basePageUrl: string;
+    blogTitle: string;
+    blogDescription: string;
+    postsPerPageOption: number | 'ALL';
+    pageBasePath: string;
+}): BlogPaginated[];
+export declare function shouldBeListed(blogPost: BlogPost): boolean;
+export declare function getBlogTags({ blogPosts, ...params }: {
+    blogPosts: BlogPost[];
+    blogTitle: string;
+    blogDescription: string;
+    postsPerPageOption: number | 'ALL';
+    pageBasePath: string;
+}): BlogTags;
+type ParsedBlogFileName = {
+    date: Date | undefined;
+    text: string;
+    slug: string;
+};
+export declare function parseBlogFileName(blogSourceRelative: string): ParsedBlogFileName;
+export declare function parseFrontMatterDate(date: string | Date): Date;
+export declare function getBlogPostDate({ frontMatterDate, filenameDate, filePath, vcs, }: {
+    frontMatterDate?: string | Date;
+    filenameDate?: Date;
+    filePath: string;
+    vcs: VcsConfig;
+}): Promise<Date>;
+export declare function generateBlogPosts(contentPaths: BlogContentPaths, context: LoadContext, options: PluginOptions, tagsFile: TagsFile | null, authorsMap?: AuthorsMap): Promise<BlogPost[]>;
+export declare function applyProcessBlogPosts({ blogPosts, processBlogPosts, }: {
+    blogPosts: BlogPost[];
+    processBlogPosts: PluginOptions['processBlogPosts'];
+}): Promise<BlogPost[]>;
+export {};

package/lib/blogUtils.js

@@ -0,0 +1,296 @@
+"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.truncate = truncate;
+exports.reportUntruncatedBlogPosts = reportUntruncatedBlogPosts;
+exports.paginateBlogPosts = paginateBlogPosts;
+exports.shouldBeListed = shouldBeListed;
+exports.getBlogTags = getBlogTags;
+exports.parseBlogFileName = parseBlogFileName;
+exports.parseFrontMatterDate = parseFrontMatterDate;
+exports.getBlogPostDate = getBlogPostDate;
+exports.generateBlogPosts = generateBlogPosts;
+exports.applyProcessBlogPosts = applyProcessBlogPosts;
+const tslib_1 = require("tslib");
+const node_path_1 = tslib_1.__importDefault(require("node:path"));
+const lodash_1 = tslib_1.__importDefault(require("lodash"));
+const logger_1 = tslib_1.__importDefault(require("@docusaurus/logger"));
+const utils_1 = require("@docusaurus/utils");
+const glob_1 = require("@docusaurus/glob");
+const fs_1 = require("@docusaurus/fs");
+const frontMatter_1 = require("./frontMatter");
+const authors_1 = require("./authors");
+const authorsProblems_1 = require("./authorsProblems");
+const readingTime_1 = require("./readingTime");
+function truncate(fileString, truncateMarker) {
+    return fileString.split(truncateMarker, 1).shift();
+}
+function reportUntruncatedBlogPosts({ blogPosts, onUntruncatedBlogPosts, }) {
+    const untruncatedBlogPosts = blogPosts.filter((p) => !p.metadata.hasTruncateMarker);
+    if (onUntruncatedBlogPosts !== 'ignore' && untruncatedBlogPosts.length > 0) {
+        const message = logger_1.default.interpolate `Docusaurus found blog posts without truncation markers:
+- ${untruncatedBlogPosts
+            .map((p) => logger_1.default.path((0, utils_1.aliasedSitePathToRelativePath)(p.metadata.source)))
+            .join('\n- ')}
+
+We recommend using truncation markers (code=${`<!-- truncate -->`} or code=${`{/* truncate */}`}) in blog posts to create shorter previews on blog paginated lists.
+Tip: turn this security off with the code=${`onUntruncatedBlogPosts: 'ignore'`} blog plugin option.`;
+        logger_1.default.report(onUntruncatedBlogPosts)(message);
+    }
+}
+function paginateBlogPosts({ blogPosts, basePageUrl, blogTitle, blogDescription, postsPerPageOption, pageBasePath, }) {
+    const totalCount = blogPosts.length;
+    const postsPerPage = postsPerPageOption === 'ALL' ? totalCount : postsPerPageOption;
+    const numberOfPages = Math.max(1, Math.ceil(totalCount / postsPerPage));
+    const pages = [];
+    function permalink(page) {
+        return page > 0
+            ? (0, utils_1.normalizeUrl)([basePageUrl, pageBasePath, `${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) : undefined,
+                nextPage: page < numberOfPages - 1 ? permalink(page + 1) : undefined,
+                blogDescription,
+                blogTitle,
+            },
+        });
+    }
+    return pages;
+}
+function shouldBeListed(blogPost) {
+    return !blogPost.metadata.unlisted;
+}
+function getBlogTags({ blogPosts, ...params }) {
+    const groups = (0, utils_1.groupTaggedItems)(blogPosts, (blogPost) => blogPost.metadata.tags);
+    return lodash_1.default.mapValues(groups, ({ tag, items: tagBlogPosts }) => {
+        const tagVisibility = (0, utils_1.getTagVisibility)({
+            items: tagBlogPosts,
+            isUnlisted: (item) => item.metadata.unlisted,
+        });
+        return {
+            inline: tag.inline,
+            label: tag.label,
+            permalink: tag.permalink,
+            description: tag.description,
+            items: tagVisibility.listedItems.map((item) => item.id),
+            pages: paginateBlogPosts({
+                blogPosts: tagVisibility.listedItems,
+                basePageUrl: tag.permalink,
+                ...params,
+            }),
+            unlisted: tagVisibility.unlisted,
+        };
+    });
+}
+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: text, slug };
+    }
+    const text = blogSourceRelative.replace(/(?:\/index)?\.mdx?$/, '');
+    const slug = `/${text}`;
+    return { date: undefined, text, slug };
+}
+function parseFrontMatterDate(date) {
+    if (typeof date === 'string') {
+        const dateString = date.trim();
+        // Detect a timezone suffix in the time portion, not the date's day/year.
+        // YAML timestamps allow tabs and short offsets; also accept ISO +/-HHMM.
+        // https://yaml.org/type/timestamp.html
+        // This detects a timezone, not date validity (already checked by Joi).
+        const hasTimeZone = /[t \t]\d.*(?:z|[+-]\d{1,2}(?::?\d{2})?)$/i.test(dateString);
+        // Treat dates without an explicit timezone as UTC.
+        return new Date(hasTimeZone ? dateString : `${dateString}Z`);
+    }
+    // Custom front matter parsers can still return Date objects.
+    return date;
+}
+async function getBlogPostDate({ frontMatterDate, filenameDate, filePath, vcs, }) {
+    // Prefer front matter, then the filename, then the file creation date.
+    if (frontMatterDate) {
+        return parseFrontMatterDate(frontMatterDate);
+    }
+    else if (filenameDate) {
+        return filenameDate;
+    }
+    const result = await vcs.getFileCreationInfo(filePath);
+    if (result == null) {
+        return (await fs_1.fs.stat(filePath)).birthtime;
+    }
+    return new Date(result.timestamp);
+}
+async function parseBlogPostMarkdownFile({ filePath, parseFrontMatter, }) {
+    const fileContent = await fs_1.fs.readFile(filePath, 'utf-8');
+    try {
+        const result = await (0, utils_1.parseMarkdownFile)({
+            filePath,
+            fileContent,
+            parseFrontMatter,
+            removeContentTitle: true,
+        });
+        return {
+            ...result,
+            frontMatter: (0, frontMatter_1.validateBlogPostFrontMatter)(result.frontMatter),
+        };
+    }
+    catch (err) {
+        logger_1.default.error `Error while parsing blog post file path=${filePath}.`;
+        throw err;
+    }
+}
+const defaultReadingTime = ({ content, locale, options }) => (0, readingTime_1.calculateReadingTime)(content, locale, options);
+async function processBlogSourceFile(blogSourceRelative, contentPaths, context, options, tagsFile, authorsMap) {
+    const { siteConfig: { baseUrl, markdown: { parseFrontMatter }, vcs, }, 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 = node_path_1.default.join(blogDirPath, blogSourceRelative);
+    const { frontMatter, content, contentTitle, excerpt } = await parseBlogPostMarkdownFile({
+        filePath: blogSourceAbsolute,
+        parseFrontMatter,
+    });
+    const aliasedSource = (0, utils_1.aliasedSitePath)(blogSourceAbsolute, siteDir);
+    const lastUpdate = await (0, utils_1.readLastUpdateData)(blogSourceAbsolute, options, frontMatter.last_update, vcs);
+    const draft = (0, utils_1.isDraft)({ frontMatter });
+    const unlisted = (0, utils_1.isUnlisted)({ frontMatter });
+    if (draft) {
+        return undefined;
+    }
+    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);
+    const date = await getBlogPostDate({
+        frontMatterDate: frontMatter.date,
+        filenameDate: parsedBlogFileName.date,
+        filePath: blogSourceAbsolute,
+        vcs,
+    });
+    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 = node_path_1.default.relative(blogDirPath, node_path_1.default.resolve(blogSourceAbsolute));
+        if (typeof editUrl === 'function') {
+            return editUrl({
+                blogDirPath: (0, utils_1.posixPath)(node_path_1.default.relative(siteDir, blogDirPath)),
+                blogPath: (0, 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.contentPathLocalized
+                : contentPaths.contentPath;
+            const contentPathEditUrl = (0, utils_1.normalizeUrl)([
+                editUrl,
+                (0, utils_1.posixPath)(node_path_1.default.relative(siteDir, fileContentPath)),
+            ]);
+            return (0, utils_1.getEditUrl)(blogPathRelative, contentPathEditUrl);
+        }
+        return undefined;
+    }
+    const tagsBaseRoutePath = (0, utils_1.normalizeUrl)([
+        baseUrl,
+        routeBasePath,
+        tagsRouteBasePath,
+    ]);
+    const authors = (0, authors_1.getBlogPostAuthors)({ authorsMap, frontMatter, baseUrl });
+    (0, authorsProblems_1.reportAuthorsProblems)({
+        authors,
+        blogSourceRelative,
+        options,
+    });
+    const tags = (0, utils_1.normalizeTags)({
+        options,
+        source: blogSourceRelative,
+        frontMatterTags: frontMatter.tags,
+        tagsBaseRoutePath,
+        tagsFile,
+    });
+    return {
+        id: slug,
+        metadata: {
+            permalink,
+            editUrl: getBlogEditUrl(),
+            source: aliasedSource,
+            title,
+            description,
+            date,
+            tags,
+            readingTime: showReadingTime
+                ? options.readingTime({
+                    content,
+                    frontMatter,
+                    defaultReadingTime,
+                    locale: i18n.currentLocale,
+                })
+                : undefined,
+            hasTruncateMarker: truncateMarker.test(content),
+            authors,
+            frontMatter,
+            unlisted,
+            lastUpdatedAt: lastUpdate.lastUpdatedAt,
+            lastUpdatedBy: lastUpdate.lastUpdatedBy,
+        },
+        content,
+    };
+}
+async function generateBlogPosts(contentPaths, context, options, tagsFile, authorsMap) {
+    const { include, exclude } = options;
+    if (!(await (0, fs_1.pathExists)(contentPaths.contentPath))) {
+        return [];
+    }
+    const blogSourceFiles = await (0, glob_1.glob)(include, {
+        cwd: contentPaths.contentPath,
+        ignore: exclude,
+    });
+    async function doProcessBlogSourceFile(blogSourceFile) {
+        try {
+            return await processBlogSourceFile(blogSourceFile, contentPaths, context, options, tagsFile, authorsMap);
+        }
+        catch (err) {
+            throw new Error(`Processing of blog source file path=${blogSourceFile} failed.`, { cause: err });
+        }
+    }
+    const blogPosts = (await Promise.all(blogSourceFiles.map(doProcessBlogSourceFile))).filter(Boolean);
+    blogPosts.sort((a, b) => b.metadata.date.getTime() - a.metadata.date.getTime());
+    if (options.sortPosts === 'ascending') {
+        return blogPosts.reverse();
+    }
+    return blogPosts;
+}
+async function applyProcessBlogPosts({ blogPosts, processBlogPosts, }) {
+    const processedBlogPosts = await processBlogPosts({ blogPosts });
+    if (Array.isArray(processedBlogPosts)) {
+        return processedBlogPosts;
+    }
+    return blogPosts;
+}

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;
+}): ReactNode;
+/**
+ * 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';
+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 value={contextValue}>{children}</Context>;
+}
+/**
+ * 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

@@ -0,0 +1,9 @@
+/**
+ * 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/lib/client/index.js

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