feat(blog): author header social icons (#10222)

Co-authored-by: OzakIOne <[email protected]>
Co-authored-by: sebastien <[email protected]>
Co-authored-by: slorber <[email protected]>

packages/create-docusaurus/templates/shared/blog/authors.yml

@@ -9,9 +9,17 @@ yangshun:
   title: Front End Engineer @ Facebook
   url: https://github.com/yangshun
   image_url: https://github.com/yangshun.png
+  socials:
+    x: yangshunz
+    github: yangshun
 
 slorber:
   name: Sébastien Lorber
   title: Docusaurus maintainer
   url: https://sebastienlorber.com
   image_url: https://github.com/slorber.png
+  socials:
+    x: sebastienlorber
+    linkedin: sebastienlorber
+    github: slorber
+    newsletter: https://thisweekinreact.com

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

@@ -255,6 +255,52 @@ describe('getBlogPostAuthors', () => {
     ]);
   });
 
+  it('can normalize inline authors', () => {
+    expect(
+      getBlogPostAuthors({
+        frontMatter: {
+          authors: [
+            {
+              name: 'Seb1',
+              socials: {
+                x: 'https://x.com/sebastienlorber',
+                twitter: 'sebastienlorber',
+                github: 'slorber',
+              },
+            },
+            {
+              name: 'Seb2',
+              socials: {
+                x: 'sebastienlorber',
+                twitter: 'https://twitter.com/sebastienlorber',
+                github: 'https://github.com/slorber',
+              },
+            },
+          ],
+        },
+        authorsMap: {},
+        baseUrl: '/',
+      }),
+    ).toEqual([
+      {
+        name: 'Seb1',
+        socials: {
+          x: 'https://x.com/sebastienlorber',
+          twitter: 'https://twitter.com/sebastienlorber',
+          github: 'https://github.com/slorber',
+        },
+      },
+      {
+        name: 'Seb2',
+        socials: {
+          x: 'https://x.com/sebastienlorber',
+          twitter: 'https://twitter.com/sebastienlorber',
+          github: 'https://github.com/slorber',
+        },
+      },
+    ]);
+  });
+
   it('throw when using author key with no authorsMap', () => {
     expect(() =>
       getBlogPostAuthors({
@@ -412,6 +458,29 @@ describe('getAuthorsMap', () => {
       }),
     ).resolves.toBeUndefined();
   });
+
+  describe('getAuthorsMap returns normalized', () => {
+    it('socials', async () => {
+      const authorsMap = await getAuthorsMap({
+        contentPaths,
+        authorsMapPath: 'authors.yml',
+      });
+      expect(authorsMap.slorber.socials).toMatchInlineSnapshot(`
+        {
+          "stackoverflow": "https://stackoverflow.com/users/82609",
+          "twitter": "https://twitter.com/sebastienlorber",
+          "x": "https://x.com/sebastienlorber",
+        }
+      `);
+      expect(authorsMap.JMarcey.socials).toMatchInlineSnapshot(`
+        {
+          "stackoverflow": "https://stackoverflow.com/users/102705/Joel-Marcey",
+          "twitter": "https://twitter.com/JoelMarcey",
+          "x": "https://x.com/JoelMarcey",
+        }
+      `);
+    });
+  });
 });
 
 describe('validateAuthorsMap', () => {
@@ -529,3 +598,68 @@ describe('validateAuthorsMap', () => {
     );
   });
 });
+
+describe('authors socials', () => {
+  it('valid known author map socials', () => {
+    const authorsMap: AuthorsMap = {
+      ozaki: {
+        name: 'ozaki',
+        socials: {
+          twitter: 'ozakione',
+          github: 'ozakione',
+        },
+      },
+    };
+
+    expect(validateAuthorsMap(authorsMap)).toEqual(authorsMap);
+  });
+
+  it('throw socials that are not strings', () => {
+    const authorsMap: AuthorsMap = {
+      ozaki: {
+        name: 'ozaki',
+        socials: {
+          // @ts-expect-error: for tests
+          twitter: 42,
+        },
+      },
+    };
+
+    expect(() =>
+      validateAuthorsMap(authorsMap),
+    ).toThrowErrorMatchingInlineSnapshot(
+      `""ozaki.socials.twitter" must be a string"`,
+    );
+  });
+
+  it('throw socials that are objects', () => {
+    const authorsMap: AuthorsMap = {
+      ozaki: {
+        name: 'ozaki',
+        socials: {
+          // @ts-expect-error: for tests
+          twitter: {link: 'ozakione'},
+        },
+      },
+    };
+
+    expect(() =>
+      validateAuthorsMap(authorsMap),
+    ).toThrowErrorMatchingInlineSnapshot(
+      `""ozaki.socials.twitter" must be a string"`,
+    );
+  });
+
+  it('valid unknown author map socials', () => {
+    const authorsMap: AuthorsMap = {
+      ozaki: {
+        name: 'ozaki',
+        socials: {
+          random: 'ozakione',
+        },
+      },
+    };
+
+    expect(validateAuthorsMap(authorsMap)).toEqual(authorsMap);
+  });
+});

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

@@ -0,0 +1,116 @@
+/**
+ * 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 {normalizeSocials} from '../authorsSocials';
+import type {AuthorSocials} from '@docusaurus/plugin-content-blog';
+
+describe('normalizeSocials', () => {
+  it('only username', () => {
+    const socials: AuthorSocials = {
+      twitter: 'ozakione',
+      linkedin: 'ozakione',
+      github: 'ozakione',
+      stackoverflow: 'ozakione',
+    };
+
+    expect(normalizeSocials(socials)).toMatchInlineSnapshot(`
+      {
+        "github": "https://github.com/ozakione",
+        "linkedin": "https://www.linkedin.com/in/ozakione/",
+        "stackoverflow": "https://stackoverflow.com/users/ozakione",
+        "twitter": "https://twitter.com/ozakione",
+      }
+    `);
+  });
+
+  it('only username - case insensitive', () => {
+    const socials: AuthorSocials = {
+      Twitter: 'ozakione',
+      linkedIn: 'ozakione',
+      gitHub: 'ozakione',
+      STACKoverflow: 'ozakione',
+    };
+
+    expect(normalizeSocials(socials)).toMatchInlineSnapshot(`
+      {
+        "github": "https://github.com/ozakione",
+        "linkedin": "https://www.linkedin.com/in/ozakione/",
+        "stackoverflow": "https://stackoverflow.com/users/ozakione",
+        "twitter": "https://twitter.com/ozakione",
+      }
+    `);
+  });
+
+  it('only links', () => {
+    const socials: AuthorSocials = {
+      twitter: 'https://x.com/ozakione',
+      linkedin: 'https://linkedin.com/ozakione',
+      github: 'https://github.com/ozakione',
+      stackoverflow: 'https://stackoverflow.com/ozakione',
+    };
+
+    expect(normalizeSocials(socials)).toEqual(socials);
+  });
+
+  it('mixed links', () => {
+    const socials: AuthorSocials = {
+      twitter: 'ozakione',
+      linkedin: 'ozakione',
+      github: 'https://github.com/ozakione',
+      stackoverflow: 'https://stackoverflow.com/ozakione',
+    };
+
+    expect(normalizeSocials(socials)).toMatchInlineSnapshot(`
+      {
+        "github": "https://github.com/ozakione",
+        "linkedin": "https://www.linkedin.com/in/ozakione/",
+        "stackoverflow": "https://stackoverflow.com/ozakione",
+        "twitter": "https://twitter.com/ozakione",
+      }
+    `);
+  });
+
+  it('one link', () => {
+    const socials: AuthorSocials = {
+      twitter: 'ozakione',
+    };
+
+    expect(normalizeSocials(socials)).toMatchInlineSnapshot(`
+      {
+        "twitter": "https://twitter.com/ozakione",
+      }
+    `);
+  });
+
+  it('rejects strings that do not look like username/userId/handle or fully-qualified URLs', () => {
+    const socials: AuthorSocials = {
+      twitter: '/ozakione/XYZ',
+    };
+
+    expect(() => normalizeSocials(socials)).toThrowErrorMatchingInlineSnapshot(`
+      "Author socials should be usernames/userIds/handles, or fully qualified HTTP(s) absolute URLs.
+      Social platform 'twitter' has illegal value '/ozakione/XYZ'"
+    `);
+  });
+
+  it('allow other form of urls', () => {
+    const socials: AuthorSocials = {
+      twitter: 'https://bit.ly/sebastienlorber-twitter',
+    };
+
+    expect(normalizeSocials(socials)).toEqual(socials);
+  });
+
+  it('allow unknown social platforms urls', () => {
+    const socials: AuthorSocials = {
+      twitch: 'https://www.twitch.tv/sebastienlorber',
+      newsletter: 'https://thisweekinreact.com',
+    };
+
+    expect(normalizeSocials(socials)).toEqual(socials);
+  });
+});