feat: allow blog authors email (#6783)

.eslintrc.js

@@ -222,6 +222,7 @@ module.exports = {
     ],
     'react/jsx-filename-extension': OFF,
     'react/jsx-key': [ERROR, {checkFragmentShorthand: true}],
+    'react/jsx-no-useless-fragment': [ERROR, {allowExpressions: true}],
     'react/jsx-props-no-spreading': OFF,
     'react/no-array-index-key': OFF, // We build a static site, and nearly all components don't change.
     'react/no-unstable-nested-components': [WARNING, {allowAsProps: true}],

packages/docusaurus-plugin-content-blog/src/__tests__/__fixtures__/authorsMapFiles/authors.json

@@ -11,7 +11,8 @@
     "title": "Docusaurus maintainer",
     "url": "https://sebastienlorber.com",
     "image_url": "https://github.com/slorber.png",
-    "twitter": "sebastienlorber"
+    "twitter": "sebastienlorber",
+    "email": "lorber.sebastien@gmail.com"
   },
   "yangshun": {
     "name": "Yangshun Tay",

packages/docusaurus-plugin-content-blog/src/__tests__/__fixtures__/authorsMapFiles/authors.yml

@@ -12,6 +12,7 @@ slorber:
   url: https://sebastienlorber.com
   image_url: https://github.com/slorber.png
   twitter: sebastienlorber
+  email: lorber.sebastien@gmail.com
 
 yangshun:
   name: Yangshun Tay

packages/docusaurus-plugin-content-blog/src/__tests__/__fixtures__/website/blog/authors.yml

@@ -1,4 +1,5 @@
-
 slorber:
   name: Sébastien Lorber
   title: Docusaurus maintainer
+  email: lorber.sebastien@gmail.com
+  url: https://sebastienlorber.com

packages/docusaurus-plugin-content-blog/src/__tests__/__fixtures__/website/i18n/en/docusaurus-plugin-content-blog/authors.yml

@@ -1,5 +1,4 @@
-
-
 slorber:
   name: Sébastien Lorber (translated)
   title: Docusaurus maintainer (translated)
+  email: lorber.sebastien@gmail.com

packages/docusaurus-plugin-content-blog/src/__tests__/__snapshots__/feed.test.ts.snap

@@ -77,6 +77,7 @@ Array [
         </author>
         <author>
             <name>Sébastien Lorber (translated)</name>
+            <email>lorber.sebastien@gmail.com</email>
         </author>
     </entry>
 </feed>",
@@ -238,6 +239,7 @@ Array [
             <pubDate>Fri, 14 Dec 2018 00:00:00 GMT</pubDate>
             <description><![CDATA[Happy birthday! (translated)]]></description>
             <content:encoded><![CDATA[<p>Happy birthday!</p>]]></content:encoded>
+            <author>lorber.sebastien@gmail.com (Sébastien Lorber (translated))</author>
         </item>
     </channel>
 </rss>",

packages/docusaurus-plugin-content-blog/src/__tests__/index.test.ts

@@ -177,6 +177,7 @@ describe('loadBlog', () => {
           name: 'Yangshun Tay (translated)',
         },
         {
+          email: 'lorber.sebastien@gmail.com',
           key: 'slorber',
           name: 'Sébastien Lorber (translated)',
           title: 'Docusaurus maintainer (translated)',

packages/docusaurus-plugin-content-blog/src/authors.ts

@@ -24,6 +24,7 @@ const AuthorsMapSchema = Joi.object<AuthorsMap>().pattern(
     url: URISchema,
     imageURL: URISchema,
     title: Joi.string(),
+    email: Joi.string(),
   })
     .rename('image_url', 'imageURL')
     .or('name', 'imageURL')

packages/docusaurus-plugin-content-blog/src/feed.ts

@@ -57,9 +57,7 @@ async function generateBlogFeed({
   });
 
   function toFeedAuthor(author: Author): FeedAuthor {
-    // TODO ask author emails?
+    return {name: author.name, link: author.url, email: author.email};
-    // RSS feed requires email to render authors
-    return {name: author.name, link: author.url};
   }
 
   await mapAsyncSequential(blogPosts, async (post) => {

packages/docusaurus-plugin-content-blog/src/plugin-content-blog.d.ts

@@ -21,6 +21,7 @@ declare module '@docusaurus/plugin-content-blog' {
     imageURL?: string;
     url?: string;
     title?: string;
+    email?: string;
   }
 
   export type BlogPostFrontMatter = {

packages/docusaurus-theme-classic/src/theme/BlogPostAuthor/index.tsx

@@ -6,19 +6,29 @@
  */
 
 import React from 'react';
-import Link from '@docusaurus/Link';
+import Link, {type Props as LinkProps} from '@docusaurus/Link';
 import type {Props} from '@theme/BlogPostAuthor';
 
 import styles from './styles.module.css';
 
+function MaybeLink(props: LinkProps): JSX.Element {
+  if (props.href) {
+    return <Link {...props} />;
+  }
+  return <>{props.children}</>;
+}
+
 export default function BlogPostAuthor({author}: Props): JSX.Element {
-  const {name, title, url, imageURL} = author;
+  const {name, title, url, imageURL, email} = author;
+  const link = url || (email && `mailto:${email}`) || undefined;
   return (
     <div className="avatar margin-bottom--sm">
       {imageURL && (
-        <Link className="avatar__photo-link avatar__photo" href={url}>
+        <span className="avatar__photo-link avatar__photo">
+          <MaybeLink href={link}>
             <img className={styles.image} src={imageURL} alt={name} />
-        </Link>
+          </MaybeLink>
+        </span>
       )}
 
       {name && (
@@ -28,9 +38,9 @@ export default function BlogPostAuthor({author}: Props): JSX.Element {
           itemScope
           itemType="https://schema.org/Person">
           <div className="avatar__name">
-            <Link href={url} itemProp="url">
+            <MaybeLink href={link} itemProp="url">
               <span itemProp="name">{name}</span>
-            </Link>
+            </MaybeLink>
           </div>
           {title && (
             <small className="avatar__subtitle" itemProp="description">

website/_dogfooding/_blog tests/2021-09-13-dup-title.md

@@ -1,5 +1,13 @@
 ---
 tags: [paginated-tag]
+authors:
+  - name: Josh-Cena1
+  - name: Josh-Cena2
+    image_url: https://github.com/Josh-Cena.png
+  - name: Josh-Cena3
+    url: https://github.com/Josh-Cena
+  - name: Josh-Cena4
+    email: sidechen2003@gmail.com
 ---
 
 # Post with duplicate title

website/blog/authors.yml

@@ -3,6 +3,7 @@ JMarcey:
   title: Technical Lead & Developer Advocate at Facebook
   url: http://twitter.com/JoelMarcey
   image_url: https://github.com/JoelMarcey.png
+  email: jimarcey@gmail.com
   twitter: JoelMarcey
 
 slorber:
@@ -11,6 +12,7 @@ slorber:
   url: https://sebastienlorber.com
   image_url: https://github.com/slorber.png
   twitter: sebastienlorber
+  email: lorber.sebastien@gmail.com
 
 yangshun:
   name: Yangshun Tay
@@ -18,15 +20,18 @@ yangshun:
   url: https://github.com/yangshun
   image_url: https://github.com/yangshun.png
   twitter: yangshunz
+  email: tay.yang.shun@gmail.com
 
 lex111:
   name: Alexey Pyltsyn
   title: Open-source enthusiast
   url: https://github.com/lex111
   image_url: https://github.com/lex111.png
+  email: lex@php.net
 
 Josh-Cena:
   name: Joshua Chen
   title: Working hard on Docusaurus
   url: https://joshcena.com/
   image_url: https://github.com/josh-cena.png
+  email: sidachen2003@gmail.com

website/docs/blog.mdx

@@ -185,7 +185,7 @@ date: 2021-09-13T18:00
 
 ## Blog post authors {#blog-post-authors}
 
-Use the `authors` front matter field to declare blog post authors.
+Use the `authors` front matter field to declare blog post authors. An author should have at least a `name` or an `image_url`. Docusaurus uses information like `url`, `email`, and `title`, but any other information is allowed.
 
 ### Inline authors {#inline-authors}
 
@@ -202,6 +202,7 @@ authors:
   title: Co-creator of Docusaurus 1
   url: https://github.com/JoelMarcey
   image_url: https://github.com/JoelMarcey.png
+  email: jimarcey@gmail.com
 ---
 ```
 
@@ -215,6 +216,7 @@ authors:
     title: Co-creator of Docusaurus 1
     url: https://github.com/JoelMarcey
     image_url: https://github.com/JoelMarcey.png
+    email: jimarcey@gmail.com
   - name: Sébastien Lorber
     title: Docusaurus maintainer
     url: https://sebastienlorber.com
@@ -259,6 +261,7 @@ jmarcey:
   title: Co-creator of Docusaurus 1
   url: https://github.com/JoelMarcey
   image_url: https://github.com/JoelMarcey.png
+  email: jimarcey@gmail.com
 
 slorber:
   name: Sébastien Lorber
@@ -353,6 +356,12 @@ website/i18n/[locale]/docusaurus-plugin-content-blog/authors.yml
 
 An author, either declared through front matter or through the authors map, needs to have a name or an avatar, or both. If all authors of a post don't have names, Docusaurus will display their avatars compactly. See [this test post](/tests/blog/2022/01/20/image-only-authors) for the effect.
 
+:::caution Feed generation
+
+[RSS feeds](#feed) require the author's email to be set for the author to appear in the feed.
+
+:::
+
 ## Reading time {#reading-time}
 
 Docusaurus generates a reading time estimation for each blog post based on word count. We provide an option to customize this.