feat: blog posts support /YYYY/MM/DD/blog-post/index.md pattern + blog frontmatter can reference relative images (#5309)

* POC of blog post folder

* add parseBlogFileName with tests + refactor and extract processBlogSourceFile in separate method

* improve blog date pattern doc + link from content plugin guides to API ref docs

* Some FrontMatter fields should be able to reference relative image assets, converted to Webpack require calls and exposed as frontMatterAssets

* remove log

website/blog/2021-05-12-announcing-docusaurus-two-beta/index.md

@@ -3,17 +3,17 @@ title: Announcing Docusaurus 2 Beta
 author: Sébastien Lorber
 authorTitle: Docusaurus maintainer
 authorURL: https://sebastienlorber.com
-authorImageURL: https://github.com/slorber.png
+authorImageURL: ./img/author.jpeg
 authorTwitter: sebastienlorber
 tags: [release, beta]
-image: /img/blog/2021-05-12-announcing-docusaurus-two-beta/social-card.png
+image: ./img/social-card.png
 ---
 
 After a lengthy alpha stage in order to ensure feature parity and quality, we are excited to officially release the first **[Docusaurus 2 beta](https://github.com/facebook/docusaurus/releases/tag/v2.0.0-beta.0)**.
 
 With the announcement of this beta, the team is even more confident that Docusaurus 2 is **ready for mainstream adoption**!
 
-![Docusaurus beta party](/img/blog/2021-05-12-announcing-docusaurus-two-beta/image_cropped.png)
+![Docusaurus beta party](./img/image_cropped.png)
 
 <!--truncate-->
 
@@ -23,13 +23,13 @@ With the announcement of this beta, the team is even more confident that Docusau
 
 Docusaurus 2 is widely adopted and growing fast:
 
-[![Docusaurus growth](/img/blog/2021-05-12-announcing-docusaurus-two-beta/trend.png)](https://www.npmtrends.com/docusaurus-vs-@docusaurus/core)
+[![Docusaurus growth](./img/trend.png)](https://www.npmtrends.com/docusaurus-vs-@docusaurus/core)
 
 To get a fuller understanding of the quality of current Docusaurus 2 sites, our new [showcase](https://docusaurus.io/showcase) page allows you to filter Docusaurus sites by features, so you may get inspired by real-world production sites with a similar use-case as yours!
 
 Don't miss our [favorite](https://docusaurus.io/showcase?tags=favorite) sites; they all stand out with something unique:
 
-[![Docusaurus growth](/img/blog/2021-05-12-announcing-docusaurus-two-beta/favorites.png)](https://docusaurus.io/showcase?tags=favorite)
+[![Docusaurus growth](./img/favorites.png)](https://docusaurus.io/showcase?tags=favorite)
 
 ## Why was Docusaurus v2 in alpha for so long?
 

website/docs/api/plugins/plugin-content-blog.md

@@ -86,7 +86,7 @@ module.exports = {
         blogSidebarCount: 5,
         blogSidebarTitle: 'All our posts',
         routeBasePath: 'blog',
-        include: ['*.md', '*.mdx'],
+        include: ['**/*.{md,mdx}'],
         exclude: [
           '**/_*.{js,jsx,ts,tsx,md,mdx}',
           '**/_*/**',
@@ -132,7 +132,7 @@ Accepted fields:
 | `author_image_url` | `string` | `undefined` | The URL to the author's thumbnail image. |
 | `author_title` | `string` | `undefined` | 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 could be extracted from the file name, e.g, `2021-04-15-blog-post.mdx`. Otherwise, it is the Markdown file creation time. |
+| `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. |
 | `draft` | `boolean` | `false` | A boolean flag to indicate that the blog post is work-in-progress and therefore should not be published yet. However, draft blog posts will be displayed during development. |
 | `hide_table_of_contents` | `boolean` | `false` | Whether to hide the table of contents to the right. |

website/docs/blog.md

@@ -3,6 +3,14 @@ id: blog
 title: Blog
 ---
 
+The blog feature enables you to deploy in no time a full-featured blog.
+
+:::info
+
+Check the [Blog Plugin API Reference documentation](./api/plugins/plugin-content-blog.md) for an exhaustive list of options.
+
+:::
+
 ## Initial setup {#initial-setup}
 
 To setup your site's blog, start by creating a `blog` directory.
@@ -26,9 +34,9 @@ module.exports = {
 
 ## Adding posts {#adding-posts}
 
-To publish in the blog, create a file within the blog directory with a formatted name of `YYYY-MM-DD-my-blog-post-title.md`. The post date is extracted from the file name.
+To publish in the blog, create a Markdown file within the blog directory.
 
-For example, at `my-website/blog/2019-09-05-hello-docusaurus-v2.md`:
+For example, create a file at `my-website/blog/2019-09-05-hello-docusaurus-v2.md`:
 
 ```yml
 ---
@@ -51,6 +59,34 @@ This is my first post on Docusaurus 2.
 A whole bunch of exploration to follow.
 ```
 
+:::note
+
+Docusaurus will extract a `YYYY-MM-DD` date from a file/folder name such as `YYYY-MM-DD-my-blog-post-title.md`.
+
+This naming convention is optional, and you can provide the date as FrontMatter.
+
+<details>
+<summary>Example supported patterns</summary>
+
+- `2021-05-28-my-blog-post-title.md`
+- `2021-05-28-my-blog-post-title.mdx`
+- `2021-05-28-my-blog-post-title/index.md`
+- `2021-05-28/my-blog-post-title.md`
+- `2021/05/28/my-blog-post-title.md`
+- `2021/05-28-my-blog-post-title.md`
+- `2021/05/28/my-blog-post-title/index.md`
+- ...
+
+</details>
+
+:::
+
+:::tip
+
+Using a folder can be convenient to co-locate blog post images alongside the Markdown file.
+
+:::
+
 The only required field in the front matter is `title`; however, we provide options to add more metadata to your blog post, for example, author information. For all possible fields, see [the API documentation](api/plugins/plugin-content-blog.md#markdown-frontmatter).
 
 ## Blog list {#blog-list}

website/docs/guides/creating-pages.md

@@ -2,6 +2,7 @@
 id: creating-pages
 title: Creating Pages
 slug: /creating-pages
+sidebar_label: Pages
 ---
 
 In this section, we will learn about creating pages in Docusaurus.
@@ -18,6 +19,12 @@ Pages do not have sidebars, only [docs](./docs/docs-introduction.md) do.
 
 :::
 
+:::info
+
+Check the [Pages Plugin API Reference documentation](./../api/plugins/plugin-content-pages.md) for an exhaustive list of options.
+
+:::
+
 ## Add a React page {#add-a-react-page}
 
 Create a file `/src/pages/helloReact.js`:

website/docs/guides/docs/docs-introduction.md

@@ -7,6 +7,12 @@ slug: /docs-introduction
 
 The docs feature provides users with a way to organize Markdown files in a hierarchical format.
 
+:::info
+
+Check the [Docs Plugin API Reference documentation](./../../api/plugins/plugin-content-docs.md) for an exhaustive list of options.
+
+:::
+
 ## Document ID {#document-id}
 
 Every document has a unique `id`. By default, a document `id` is the name of the document (without the extension) relative to the root docs directory.