{authorImageURL && (
- 
+
)}
{author && (
- - + {author}
diff --git a/packages/docusaurus-theme-classic/src/theme/BlogListPage/index.tsx b/packages/docusaurus-theme-classic/src/theme/BlogListPage/index.tsx index 27d61f3186..2179aeaca3 100644 --- a/packages/docusaurus-theme-classic/src/theme/BlogListPage/index.tsx +++ b/packages/docusaurus-theme-classic/src/theme/BlogListPage/index.tsx @@ -38,7 +38,7 @@ function BlogListPage(props: Props): JSX.Element {
+ {imageURL && (
+
+ 
+
+ )}
+
+ {
+ // Note: only legacy author frontmatter allow empty name (not frontMatter.authors)
+ name && (
+
+ );
+}
+
+export default BlogPostAuthor;
diff --git a/packages/docusaurus-theme-classic/src/theme/BlogPostAuthor/styles.module.css b/packages/docusaurus-theme-classic/src/theme/BlogPostAuthor/styles.module.css
new file mode 100644
index 0000000000..aae60add2d
--- /dev/null
+++ b/packages/docusaurus-theme-classic/src/theme/BlogPostAuthor/styles.module.css
@@ -0,0 +1,12 @@
+/**
+ * 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.
+ */
+
+.image {
+ width: 100%;
+ height: 100%;
+ object-fit: cover;
+}
diff --git a/packages/docusaurus-theme-classic/src/theme/BlogPostAuthors/index.tsx b/packages/docusaurus-theme-classic/src/theme/BlogPostAuthors/index.tsx
new file mode 100644
index 0000000000..0b091c1416
--- /dev/null
+++ b/packages/docusaurus-theme-classic/src/theme/BlogPostAuthors/index.tsx
@@ -0,0 +1,55 @@
+/**
+ * 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 from 'react';
+import clsx from 'clsx';
+import type {Props} from '@theme/BlogPostAuthors';
+import BlogPostAuthor from '@theme/BlogPostAuthor';
+
+function getAuthorsPerLine(authorsCount: number): 1 | 2 {
+ switch (authorsCount) {
+ case 0:
+ case 1:
+ return 1;
+ default:
+ return 2;
+ }
+}
+
+function getColClassName(authorsCount: number): string {
+ switch (getAuthorsPerLine(authorsCount)) {
+ case 1:
+ return 'col--12';
+ case 2:
+ return 'col--6';
+ default:
+ throw Error('unexpected');
+ }
+}
+
+// Component responsible for the authors layout
+export default function BlogPostAuthors({authors, assets}: Props): JSX.Element {
+ const authorsCount = authors.length;
+ if (authorsCount === 0) {
+ return <>;
+ }
+ return (
+
+
+ )
+ }
+
+
+ {name}
+
+
+ {title && (
+
+ {title}
+
+ )}
+
+ {authors.map((author, idx) => (
+
+ );
+}
diff --git a/packages/docusaurus-theme-classic/src/theme/BlogPostItem/index.tsx b/packages/docusaurus-theme-classic/src/theme/BlogPostItem/index.tsx
index b8062a37c7..ae45640ef7 100644
--- a/packages/docusaurus-theme-classic/src/theme/BlogPostItem/index.tsx
+++ b/packages/docusaurus-theme-classic/src/theme/BlogPostItem/index.tsx
@@ -18,6 +18,7 @@ import type {Props} from '@theme/BlogPostItem';
import styles from './styles.module.css';
import TagsListInline from '@theme/TagsListInline';
+import BlogPostAuthors from '@theme/BlogPostAuthors';
// Very simple pluralization: probably good enough for now
function useReadingTimePlural() {
@@ -45,7 +46,7 @@ function BlogPostItem(props: Props): JSX.Element {
const {
children,
frontMatter,
- frontMatterAssets,
+ assets,
metadata,
truncated,
isBlogPostPage = false,
@@ -58,18 +59,10 @@ function BlogPostItem(props: Props): JSX.Element {
readingTime,
title,
editUrl,
+ authors,
} = metadata;
- const {author} = frontMatter;
- const image = frontMatterAssets.image ?? frontMatter.image;
-
- const authorURL = frontMatter.author_url || frontMatter.authorURL;
- const authorTitle = frontMatter.author_title || frontMatter.authorTitle;
- const authorImageURL =
- frontMatterAssets.author_image_url ||
- frontMatterAssets.authorImageURL ||
- frontMatter.author_image_url ||
- frontMatter.authorImageURL;
+ const image = assets.image ?? frontMatter.image;
const renderPostHeader = () => {
const TitleHeading = isBlogPostPage ? 'h1' : 'h2';
@@ -90,39 +83,14 @@ function BlogPostItem(props: Props): JSX.Element {
{formattedDate}
- {readingTime && (
+ {typeof readingTime !== 'undefined' && (
<>
{' · '}
{readingTimePlural(readingTime)}
)}
+
+ ))}
+
- {authorImageURL && (
-
-
-
- )}
- {author && (
-
+
-
- )}
-
-
- {author}
-
-
-
- {authorTitle && (
-
- {authorTitle}
-
- )}
- string | EditUrlFunction | `undefined` | Base URL to edit your site. The final URL is computed by `editUrl + relativeDocPath`. Using a function allows more nuanced control for each file. Omitting this variable entirely will disable edit links. |
| `editLocalizedFiles` | `boolean` | `false` | The edit URL will target the localized file, instead of the original unlocalized file. Ignored when `editUrl` is a function. |
| `blogTitle` | `string` | `'Blog'` | Blog page title for better SEO. |
@@ -49,6 +49,7 @@ Accepted fields:
| `beforeDefaultRehypePlugins` | `any[]` | `[]` | Custom Rehype plugins passed to MDX before the default Docusaurus Rehype plugins. |
| `truncateMarker` | `string` | `//` | Truncate marker, can be a regex or string. |
| `showReadingTime` | `boolean` | `true` | Show estimated reading time for the blog post. |
+| `authorsMapPath` | `string` | `'authors.yml'` | Path to the authors map file, relative to the blog content directory specified with `path`. Can also be a `json` file. |
| `feedOptions` | _See below_ | `{type: ['rss', 'atom']}` | Blog feed. If undefined, no rss feed will be generated. |
| `feedOptions.type` | 'rss' | 'atom' | 'all' (or array of multiple options) | **Required** | Type of feed to be generated. |
| `feedOptions.title` | `string` | `siteConfig.title` | Title of the feed. |
@@ -174,10 +175,11 @@ Accepted fields:
| Name | Type | Default | Description |
| --- | --- | --- | --- |
-| `author` | `string` | `undefined` | The author name to be displayed. |
-| `author_url` | `string` | `undefined` | The URL that the author's name will be linked to. This could be a GitHub, Twitter, Facebook profile URL, etc. |
-| `author_image_url` | `string` | `undefined` | The URL to the author's thumbnail image. |
-| `author_title` | `string` | `undefined` | A description of the author. |
+| `authors` | `Authors` | `undefined` | List of blog post authors (or unique author). Read the [`authors` guide](../../blog.mdx#blog-post-authors) for more explanations. Prefer `authors` over the `author_*` FrontMatter fields, even for single author blog posts. |
+| `author` | `string` | `undefined` | ⚠️ Prefer using `authors`. The blog post author's name. |
+| `author_url` | `string` | `undefined` | ⚠️ Prefer using `authors`. The URL that the author's name will be linked to. This could be a GitHub, Twitter, Facebook profile URL, etc. |
+| `author_image_url` | `string` | `undefined` | ⚠️ Prefer using `authors`. The URL to the author's thumbnail image. |
+| `author_title` | `string` | `undefined` | ⚠️ Prefer using `authors`. A description of the author. |
| `title` | `string` | Markdown title | The blog post title. |
| `date` | `string` | File name or file creation time | The blog post creation date. If not specified, this can be extracted from the file or folder name, e.g, `2021-04-15-blog-post.mdx`, `2021-04-15-blog-post/index.mdx`, `2021/04/15/blog-post.mdx`. Otherwise, it is the Markdown file creation time. |
| `tags` | `Tag[]` | `undefined` | A list of strings or objects of two string fields `label` and `permalink` to tag to your post. |
@@ -192,6 +194,20 @@ Accepted fields:
```typescript
type Tag = string | {label: string; permalink: string};
+
+// An author key references an author from the global plugin authors.yml file
+type AuthorKey = string;
+
+type Author = {
+ key?: AuthorKey;
+ name: string;
+ title?: string;
+ url?: string;
+ image_url?: string;
+};
+
+// The FrontMatter authors field allows various possible shapes
+type Authors = AuthorKey | Author | (AuthorKey | Author)[];
```
Example:
@@ -199,10 +215,13 @@ Example:
```yml
---
title: Welcome Docusaurus v2
-author: Joel Marcey
-author_title: Co-creator of Docusaurus 1
-author_url: https://github.com/JoelMarcey
-author_image_url: https://graph.facebook.com/611217057/picture/?height=200&width=200
+authors:
+ - slorber
+ - yangshun
+ - name: Joel Marcey
+ title: Co-creator of Docusaurus 1
+ url: https://github.com/JoelMarcey
+ image_url: https://github.com/JoelMarcey.png
tags: [hello, docusaurus-v2]
description: This is my first post on Docusaurus 2.
image: https://i.imgur.com/mErPwqL.png
@@ -228,6 +247,7 @@ Read the [i18n introduction](../../i18n/i18n-introduction.md) first.
website/i18n/
+
+
+Mix inline authors and global authors
+ +You can use global authors most of the time, and still use inline authors: + +```yml title="my-blog-post.md" +--- +authors: + - jmarcey + - slorber + - name: Inline Author name + title: Inline Author Title + url: https://github.com/inlineAuthor + image_url: https://github.com/inlineAuthor +--- + +``` + +
+
+
+Local override of global authors
+ +You can customize the global author's data on per-blog-post basis + +```yml title="my-blog-post.md" +--- +authors: + - key: jmarcey + title: Joel Marcey's new title + - key: slorber + name: Sébastien Lorber's new name +--- + +``` + +
+ /docusaurus-plugin-content-blog/authors.yml
+```
+
+
:::
diff --git a/website/docs/guides/docs/docs-introduction.md b/website/docs/guides/docs/docs-introduction.md
index b2cd257e91..0612e7b089 100644
--- a/website/docs/guides/docs/docs-introduction.md
+++ b/website/docs/guides/docs/docs-introduction.md
@@ -81,6 +81,6 @@ You should delete the existing homepage at `./src/pages/index.js`, or else there
:::tip
-There's also a "blog-only mode" for those who only want to use the blog feature of Docusaurus 2. You can use the same method detailed above. Follow the setup instructions on [Blog-only mode](../../blog.md#blog-only-mode).
+There's also a "blog-only mode" for those who only want to use the blog feature of Docusaurus 2. You can use the same method detailed above. Follow the setup instructions on [Blog-only mode](../../blog.mdx#blog-only-mode).
:::
diff --git a/website/docs/installation.md b/website/docs/installation.md
index 8e99c39d00..c632bc83e6 100644
--- a/website/docs/installation.md
+++ b/website/docs/installation.md
@@ -90,7 +90,7 @@ my-website
### Project structure rundown {#project-structure-rundown}
-- `/blog/` - Contains the blog Markdown files. You can delete the directory if you do not want/need a blog. More details can be found in the [blog guide](blog.md)
+- `/blog/` - Contains the blog Markdown files. You can delete the directory if you do not want/need a blog. More details can be found in the [blog guide](blog.mdx)
- `/docs/` - Contains the Markdown files for the docs. Customize the order of the docs sidebar in `sidebars.js`. More details can be found in the [docs guide](./guides/docs/docs-markdown-features.mdx)
- `/src/` - Non-documentation files like pages or custom React components. You don't have to strictly put your non-documentation files in here but putting them under a centralized directory makes it easier to specify in case you need to do some sort of linting/processing
- `/src/pages` - Any files within this directory will be converted into a website page. More details can be found in the [pages guide](guides/creating-pages.md)
diff --git a/website/docs/migration/migration-manual.md b/website/docs/migration/migration-manual.md
index 5c477cf38e..e915c815e6 100644
--- a/website/docs/migration/migration-manual.md
+++ b/website/docs/migration/migration-manual.md
@@ -576,7 +576,7 @@ Refer to the [multi-language support code blocks](../guides/markdown-features/ma
The Docusaurus front matter fields for the blog have been changed from camelCase to snake_case to be consistent with the docs.
-The fields `authorFBID` and `authorTwitter` have been deprecated. They are only used for generating the profile image of the author which can be done via the `author_image_url` field.
+The fields `authorFBID` and `authorTwitter` have been deprecated. They are only used for generating the profile image of the author which can be done via the `authors` field.
## Deployment {#deployment}
diff --git a/website/docusaurus.config.js b/website/docusaurus.config.js
index fcd2e81eec..4c3a7a462e 100644
--- a/website/docusaurus.config.js
+++ b/website/docusaurus.config.js
@@ -270,7 +270,7 @@ const TwitterSvg =
}
return `https://github.com/facebook/docusaurus/edit/main/website/${blogDirPath}/${blogPath}`;
},
- postsPerPage: 3,
+ postsPerPage: 5,
feedOptions: {
type: 'all',
copyright: `Copyright © ${new Date().getFullYear()} Facebook, Inc.`,