mirror of
https://github.com/facebook/docusaurus.git
synced 2025-05-30 09:27:04 +02:00
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
GitHub
parent
8779c8ff4a
commit
493225a3c6
79 changed files with 1871 additions and 285 deletions
|
|
@ -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 | 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' | 'atom' | '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
|
||||
│
|
||||
|
|
|
|||
|
|
@ -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>
|
||||
|
||||
:::
|
||||
|
||||
|
|
@ -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).
|
||||
|
||||
:::
|
||||
|
|
|
|||
|
|
@ -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)
|
||||
|
|
|
|||
|
|
@ -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}
|
||||
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue