feat(plugin-blog): multi-authors support + authors.yml global configuration (#5396)

* Complete function

Signed-off-by: Josh-Cena <sidachen2003@gmail.com>

* A lot of blank lines

Signed-off-by: Josh-Cena <sidachen2003@gmail.com>

* More lenient validation

Signed-off-by: Josh-Cena <sidachen2003@gmail.com>

* Remove or

Signed-off-by: Josh-Cena <sidachen2003@gmail.com>

* Simpler logic

Signed-off-by: Josh-Cena <sidachen2003@gmail.com>

* Expand docs

Signed-off-by: Josh-Cena <sidachen2003@gmail.com>

* Better docs

Signed-off-by: Josh-Cena <sidachen2003@gmail.com>

* Dogfood

Signed-off-by: Josh-Cena <sidachen2003@gmail.com>

* More writeup

Signed-off-by: Josh-Cena <sidachen2003@gmail.com>

* Polish

Signed-off-by: Josh-Cena <sidachen2003@gmail.com>

* Polish

Signed-off-by: Josh-Cena <sidachen2003@gmail.com>

* Move mergeAuthorMap to authors.ts

Signed-off-by: Josh-Cena <sidachen2003@gmail.com>

* Unbreak relative assets

* Update docs

* Clarify in docs

* simplify feed authors

* rename authorMap -> authorsMap

* mergeAuthorsMap -> getBlogPostAuthors

* website => 5 blog posts per page

* improve authors map file

* Extract new theme authors components + display in row

* add comment for meta array syntaxes

* blog => getPathsToWatch should watch authorsMap file

* remove useless v1 blog FBID frontmatter

* keep older frontmatter syntax for now

* revert blog frontmatter

* Better console message

* better blog authors frontmatter impl

* add multi authors to beta blog post + fix some authors margins

* fix React key

* Refactor: mdx loader should support a more flexible assets system (poc, not documented yet)

* better display of blog post authors: adapt layout to authors count + add line clamp

* smaller local image

* fix blog feed tests

* fix blog frontmatter tests + improve validation schema

* add more frontmatter tests

* add tests for getAuthorsMapFilePath

* tests for validateAuthorsMapFile

* add tests for readAuthorsMapFile

* test getAuthorsMap

* exhaustive tests for getBlogPostAuthors

* fix remaining tests

* missing blog plugin author tests

* fix windows tests

* improve blog multi-author's doc

* Use new format in init template

Signed-off-by: Josh-Cena <sidachen2003@gmail.com>

* Improve error message

Signed-off-by: Josh-Cena <sidachen2003@gmail.com>

* update feed snapshot

* blog authors: limit to 2 cols + fix margins for no authors

* minor doc improvements

* better init template blog posts, demonstrating Blog features

* replace the legacy blog author frontmatter in remaining places

* Prefer using clsx

Signed-off-by: Josh-Cena <sidachen2003@gmail.com>

* cleanup getColClassName

* remove blog author name/title line-clamping

Co-authored-by: slorber <lorber.sebastien@gmail.com>
This commit is contained in:
Joshua Chen 2021-08-26 18:21:58 +08:00 committed by GitHub
parent 8779c8ff4a
commit 493225a3c6
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
79 changed files with 1871 additions and 285 deletions

View file

@ -4,7 +4,7 @@ title: '📦 plugin-content-blog'
slug: '/api/plugins/@docusaurus/plugin-content-blog'
---
Provides the [Blog](blog.md) feature and is the default blog plugin for Docusaurus.
Provides the [Blog](blog.mdx) feature and is the default blog plugin for Docusaurus.
## Installation {#installation}
@ -28,7 +28,7 @@ Accepted fields:
| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `path` | `string` | `'blog'` | Path to data on filesystem relative to site dir. |
| `path` | `string` | `'blog'` | Path to the blog content directory on the filesystem, relative to site dir. |
| `editUrl` | <code>string &#124; EditUrlFunction</code> | `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` | `/<!--\s*(truncate)\s*-->/` | 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` | <code>'rss' &#124; 'atom' &#124; 'all'</code> (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/<locale>/docusaurus-plugin-content-blog
│ # translations for website/blog
├── authors.yml
├── first-blog-post.md
├── second-blog-post.md

View file

@ -3,6 +3,9 @@ id: blog
title: Blog
---
import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';
The blog feature enables you to deploy in no time a full-featured blog.
:::info
@ -36,17 +39,23 @@ module.exports = {
To publish in the blog, create a Markdown file within the blog directory.
For example, create a file at `my-website/blog/2019-09-05-hello-docusaurus-v2.md`:
For example, create a file at `website/blog/2019-09-05-hello-docusaurus-v2.md`:
```yml
```yml title="website/blog/2019-09-05-hello-docusaurus-v2.md"
---
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
tags: [hello, docusaurus-v2]
description: This is my first post on Docusaurus 2.
slug: welcome-docusaurus-v2
authors:
- name: Joel Marcey
title: Co-creator of Docusaurus 1
url: https://github.com/JoelMarcey
image_url: https://github.com/JoelMarcey.png
- name: Sébastien Lorber
title: Docusaurus maintainer
url: https://sebastienlorber.com
image_url: https://github.com/slorber.png
tags: [hello, docusaurus-v2]
image: https://i.imgur.com/mErPwqL.png
hide_table_of_contents: false
---
@ -158,9 +167,184 @@ module.exports = {
};
```
:::note
## Blog post authors {#blog-post-authors}
Because the sidebar title is hard-coded in the configuration file, it is currently untranslatable.
Use the `authors` FrontMatter field to declare blog post authors.
### Inline authors {#inline-authors}
Blog post authors can be declared directly inside the FrontMatter:
````mdx-code-block
<Tabs
defaultValue="single"
values={[
{label: 'Single author', value: 'single'},
{label: 'Multiple authors', value: 'multiple'},
]}>
<TabItem value="single">
```yml title="my-blog-post.md"
---
authors:
name: Joel Marcey
title: Co-creator of Docusaurus 1
url: https://github.com/JoelMarcey
image_url: https://github.com/JoelMarcey.png
---
```
</TabItem>
<TabItem value="multiple">
```yml title="my-blog-post.md"
---
authors:
- name: Joel Marcey
title: Co-creator of Docusaurus 1
url: https://github.com/JoelMarcey
image_url: https://github.com/JoelMarcey.png
- name: Sébastien Lorber
title: Docusaurus maintainer
url: https://sebastienlorber.com
image_url: https://github.com/slorber.png
---
```
</TabItem>
</Tabs>
````
:::tip
This option works best to get started, or for casual, irregular authors.
:::
:::info
Prefer usage of the `authors` FrontMatter, but the legacy `author_*` FrontMatter remains supported:
```yml title="my-blog-post.md"
---
author: Joel Marcey
author_title: Co-creator of Docusaurus 1
author_url: https://github.com/JoelMarcey
author_image_url: https://github.com/JoelMarcey.png
---
```
:::
### Global authors {#global-authors}
For regular blog post authors, it can be tedious to maintain authors information inlined in each blog post.
It is possible declare those authors globally in a configuration file:
```yml title="website/blog/authors.yml"
jmarcey:
name: Joel Marcey
title: Co-creator of Docusaurus 1
url: https://github.com/JoelMarcey
image_url: https://github.com/JoelMarcey.png
slorber:
name: Sébastien Lorber
title: Docusaurus maintainer
url: https://sebastienlorber.com
image_url: https://github.com/slorber.png
```
:::tip
Use the `authorsMapPath` plugin option to configure the path. JSON is also supported.
:::
In blog posts FrontMatter, you can reference the authors declared in the global configuration file:
````mdx-code-block
<Tabs
defaultValue="single"
values={[
{label: 'Single author', value: 'single'},
{label: 'Multiple authors', value: 'multiple'},
]}>
<TabItem value="single">
```yml title="my-blog-post.md"
---
authors: jmarcey
---
```
</TabItem>
<TabItem value="multiple">
```yml title="my-blog-post.md"
---
authors: [jmarcey, slorber]
---
```
</TabItem>
</Tabs>
````
:::info
The `authors` system is very flexible and can suit more advanced use-case:
<details>
<summary>Mix inline authors and global authors</summary>
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
---
```
</details>
<details>
<summary>Local override of global authors</summary>
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
---
```
</details>
<details>
<summary>Localize the author's configuration file</summary>
The configuration file can be localized, just create a localized copy of it at:
```bash
website/i18n/<locale>/docusaurus-plugin-content-blog/authors.yml
```
</details>
:::

View file

@ -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).
:::

View file

@ -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)

View file

@ -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}