@docusaurus/plugin-content-blog 3.3.2 → 3.5.0

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

@@ -4,13 +4,18 @@
  * This source code is licensed under the MIT license found in the
  * LICENSE file in the root directory of this source tree.
  */
-/// <reference path="../src/plugin-content-blog.d.ts" />
-import type { DocusaurusConfig } from '@docusaurus/types';
+import type { BlogContentPaths } from './types';
+import type { DocusaurusConfig, HtmlTags, LoadContext } from '@docusaurus/types';
 import type { PluginOptions, BlogPost } from '@docusaurus/plugin-content-blog';
-export declare function createBlogFeedFiles({ blogPosts: allBlogPosts, options, siteConfig, outDir, locale, }: {
+export declare function createBlogFeedFiles({ blogPosts: allBlogPosts, options, siteConfig, outDir, locale, contentPaths, }: {
     blogPosts: BlogPost[];
     options: PluginOptions;
     siteConfig: DocusaurusConfig;
     outDir: string;
     locale: string;
+    contentPaths: BlogContentPaths;
 }): Promise<void>;
+export declare function createFeedHtmlHeadTags({ context, options, }: {
+    context: LoadContext;
+    options: PluginOptions;
+}): HtmlTags;

package/lib/feed.js

@@ -6,16 +6,17 @@
  * LICENSE file in the root directory of this source tree.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.createBlogFeedFiles = void 0;
+exports.createBlogFeedFiles = createBlogFeedFiles;
+exports.createFeedHtmlHeadTags = createFeedHtmlHeadTags;
 const tslib_1 = require("tslib");
 const path_1 = tslib_1.__importDefault(require("path"));
 const fs_extra_1 = tslib_1.__importDefault(require("fs-extra"));
-const logger_1 = tslib_1.__importDefault(require("@docusaurus/logger"));
 const feed_1 = require("feed");
 const srcset = tslib_1.__importStar(require("srcset"));
 const utils_1 = require("@docusaurus/utils");
 const utils_common_1 = require("@docusaurus/utils-common");
 const cheerio_1 = require("cheerio");
+const logger_1 = tslib_1.__importDefault(require("@docusaurus/logger"));
 async function generateBlogFeed({ blogPosts, options, siteConfig, outDir, locale, }) {
     if (!blogPosts.length) {
         return null;
@@ -105,25 +106,72 @@ async function defaultCreateFeedItems({ blogPosts, siteConfig, outDir, }) {
         return feedItem;
     }));
 }
-async function createBlogFeedFile({ feed, feedType, generatePath, }) {
-    const [feedContent, feedPath] = (() => {
-        switch (feedType) {
-            case 'rss':
-                return [feed.rss2(), 'rss.xml'];
-            case 'json':
-                return [feed.json1(), 'feed.json'];
-            case 'atom':
-                return [feed.atom1(), 'atom.xml'];
-            default:
-                throw new Error(`Feed type ${feedType} not supported.`);
-        }
-    })();
+async function resolveXsltFilePaths({ xsltFilePath, contentPaths, }) {
+    const xsltAbsolutePath = path_1.default.isAbsolute(xsltFilePath)
+        ? xsltFilePath
+        : (await (0, utils_1.getDataFilePath)({ filePath: xsltFilePath, contentPaths })) ??
+            path_1.default.resolve(contentPaths.contentPath, xsltFilePath);
+    if (!(await fs_extra_1.default.pathExists(xsltAbsolutePath))) {
+        throw new Error(logger_1.default.interpolate `Blog feed XSLT file not found at path=${path_1.default.relative(process.cwd(), xsltAbsolutePath)}`);
+    }
+    const parsedPath = path_1.default.parse(xsltAbsolutePath);
+    const cssAbsolutePath = path_1.default.resolve(parsedPath.dir, `${parsedPath.name}.css`);
+    if (!(await fs_extra_1.default.pathExists(xsltAbsolutePath))) {
+        throw new Error(logger_1.default.interpolate `Blog feed XSLT file was found at path=${path_1.default.relative(process.cwd(), xsltAbsolutePath)}
+But its expected co-located CSS file could not be found at path=${path_1.default.relative(process.cwd(), cssAbsolutePath)}
+If you want to provide a custom XSLT file, you must provide a CSS file with the exact same name.`);
+    }
+    return { xsltAbsolutePath, cssAbsolutePath };
+}
+async function generateXsltFiles({ xsltFilePath, generatePath, contentPaths, }) {
+    const { xsltAbsolutePath, cssAbsolutePath } = await resolveXsltFilePaths({
+        xsltFilePath,
+        contentPaths,
+    });
+    const xsltOutputPath = path_1.default.join(generatePath, path_1.default.basename(xsltAbsolutePath));
+    const cssOutputPath = path_1.default.join(generatePath, path_1.default.basename(cssAbsolutePath));
+    await fs_extra_1.default.copy(xsltAbsolutePath, xsltOutputPath);
+    await fs_extra_1.default.copy(cssAbsolutePath, cssOutputPath);
+}
+// This modifies the XML feed content to add a relative href to the XSLT file
+// Good enough for now: we probably don't need a full XML parser just for that
+// See also https://darekkay.com/blog/rss-styling/
+function injectXslt({ feedContent, xsltFilePath, }) {
+    return feedContent.replace('<?xml version="1.0" encoding="utf-8"?>', `<?xml version="1.0" encoding="utf-8"?><?xml-stylesheet type="text/xsl" href="${path_1.default.basename(xsltFilePath)}"?>`);
+}
+const FeedConfigs = {
+    rss: {
+        outputFileName: 'rss.xml',
+        getContent: (feed) => feed.rss2(),
+        getXsltFilePath: (xslt) => xslt.rss,
+    },
+    atom: {
+        outputFileName: 'atom.xml',
+        getContent: (feed) => feed.atom1(),
+        getXsltFilePath: (xslt) => xslt.atom,
+    },
+    json: {
+        outputFileName: 'feed.json',
+        getContent: (feed) => feed.json1(),
+        getXsltFilePath: () => null,
+    },
+};
+async function createBlogFeedFile({ feed, feedType, generatePath, feedOptions, contentPaths, }) {
     try {
-        await fs_extra_1.default.outputFile(path_1.default.join(generatePath, feedPath), feedContent);
+        const feedConfig = FeedConfigs[feedType];
+        let feedContent = feedConfig.getContent(feed);
+        const xsltFilePath = feedConfig.getXsltFilePath(feedOptions.xslt);
+        if (xsltFilePath) {
+            await generateXsltFiles({ xsltFilePath, contentPaths, generatePath });
+            feedContent = injectXslt({ feedContent, xsltFilePath });
+        }
+        const outputPath = path_1.default.join(generatePath, feedConfig.outputFileName);
+        await fs_extra_1.default.outputFile(outputPath, feedContent);
     }
     catch (err) {
-        logger_1.default.error(`Generating ${feedType} feed failed.`);
-        throw err;
+        throw new Error(`Generating ${feedType} feed failed.`, {
+            cause: err,
+        });
     }
 }
 function shouldBeInFeed(blogPost) {
@@ -131,7 +179,7 @@ function shouldBeInFeed(blogPost) {
         blogPost.metadata.frontMatter.unlisted;
     return !excluded;
 }
-async function createBlogFeedFiles({ blogPosts: allBlogPosts, options, siteConfig, outDir, locale, }) {
+async function createBlogFeedFiles({ blogPosts: allBlogPosts, options, siteConfig, outDir, locale, contentPaths, }) {
     const blogPosts = allBlogPosts.filter(shouldBeInFeed);
     const feed = await generateBlogFeed({
         blogPosts,
@@ -148,6 +196,49 @@ async function createBlogFeedFiles({ blogPosts: allBlogPosts, options, siteConfi
         feed,
         feedType,
         generatePath: path_1.default.join(outDir, options.routeBasePath),
+        feedOptions: options.feedOptions,
+        contentPaths,
     })));
 }
-exports.createBlogFeedFiles = createBlogFeedFiles;
+function createFeedHtmlHeadTags({ context, options, }) {
+    const feedTypes = options.feedOptions.type;
+    if (!feedTypes) {
+        return [];
+    }
+    const feedTitle = options.feedOptions.title ?? context.siteConfig.title;
+    const feedsConfig = {
+        rss: {
+            type: 'application/rss+xml',
+            path: 'rss.xml',
+            title: `${feedTitle} RSS Feed`,
+        },
+        atom: {
+            type: 'application/atom+xml',
+            path: 'atom.xml',
+            title: `${feedTitle} Atom Feed`,
+        },
+        json: {
+            type: 'application/json',
+            path: 'feed.json',
+            title: `${feedTitle} JSON Feed`,
+        },
+    };
+    const headTags = [];
+    feedTypes.forEach((feedType) => {
+        const { type, path: feedConfigPath, title: feedConfigTitle, } = feedsConfig[feedType];
+        headTags.push({
+            tagName: 'link',
+            attributes: {
+                rel: 'alternate',
+                type,
+                href: (0, utils_1.normalizeUrl)([
+                    context.siteConfig.baseUrl,
+                    options.routeBasePath,
+                    feedConfigPath,
+                ]),
+                title: feedConfigTitle,
+            },
+        });
+    });
+    return headTags;
+}

package/lib/frontMatter.d.ts

@@ -1,4 +1,3 @@
-/// <reference path="../src/plugin-content-blog.d.ts" />
 import type { BlogPostFrontMatter } from '@docusaurus/plugin-content-blog';
 export declare function validateBlogPostFrontMatter(frontMatter: {
     [key: string]: unknown;

package/lib/frontMatter.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.validateBlogPostFrontMatter = void 0;
+exports.validateBlogPostFrontMatter = validateBlogPostFrontMatter;
 /**
  * Copyright (c) Facebook, Inc. and its affiliates.
  *
@@ -8,12 +8,14 @@ exports.validateBlogPostFrontMatter = void 0;
  * 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 });
@@ -61,4 +63,3 @@ const BlogFrontMatterSchema = utils_validation_1.JoiFrontMatter.object({
 function validateBlogPostFrontMatter(frontMatter) {
     return (0, utils_validation_1.validateFrontMatter)(frontMatter, BlogFrontMatterSchema);
 }
-exports.validateBlogPostFrontMatter = validateBlogPostFrontMatter;

package/lib/index.d.ts

@@ -4,7 +4,6 @@
  * This source code is licensed under the MIT license found in the
  * LICENSE file in the root directory of this source tree.
  */
-/// <reference path="../src/plugin-content-blog.d.ts" />
 import type { LoadContext, Plugin } from '@docusaurus/types';
 import type { PluginOptions, BlogContent } from '@docusaurus/plugin-content-blog';
 export default function pluginContentBlog(context: LoadContext, options: PluginOptions): Promise<Plugin<BlogContent>>;