feat(v2): blog slug frontmatter (#3284)

docs/guides-blog.md

@@ -34,6 +34,24 @@ authorTwitter: JoelMarcey
 Lorem Ipsum...
 ```
 
+Adding slug will override the url of the blog post.
+
+For example:
+
+```yml
+---
+slug: introducing-docusaurus
+title: Introducing Docusaurus
+author: Joel Marcey
+authorURL: http://twitter.com/JoelMarcey
+authorFBID: 611217057
+authorTwitter: JoelMarcey
+---
+Lorem Ipsum...
+```
+
+Will be available at `https://website/blog/introducing-docusaurus`
+
 ## Header Options
 
 The only required field is `title`; however, we provide options to add author information to your blog post as well along with other options.
@@ -43,6 +61,7 @@ The only required field is `title`; however, we provide options to add author in
 - `authorFBID` - The Facebook profile ID that is used to fetch the profile picture.
 - `authorImageURL` - The URL to the author's image. (Note: If you use both `authorFBID` and `authorImageURL`, `authorFBID` will take precedence. Don't include `authorFBID` if you want `authorImageURL` to appear.)
 - `title` - The blog post title.
+- `slug` - The blog post url slug. Example: `/blog/my-test-slug`. When not specified, the blog url slug will be extracted from the file name.
 - `unlisted` - The post will be accessible by directly visiting the URL but will not show up in the sidebar in the final build; during local development, the post will still be listed. Useful in situations where you want to share a WIP post with others for feedback.
 
 ## Summary Truncation

packages/docusaurus-init/templates/bootstrap/blog/2019-05-28-hola.md

@@ -1,5 +1,5 @@
 ---
-id: hola
+slug: hola
 title: Hola
 author: Gao Wei
 author_title: Docusaurus Core Team

packages/docusaurus-init/templates/bootstrap/blog/2019-05-29-hello-world.md

@@ -1,5 +1,5 @@
 ---
-id: hello-world
+slug: hello-world
 title: Hello
 author: Endilie Yacop Sucipto
 author_title: Maintainer of Docusaurus

packages/docusaurus-init/templates/bootstrap/blog/2019-05-30-welcome.md

@@ -1,5 +1,5 @@
 ---
-id: welcome
+slug: welcome
 title: Welcome
 author: Yangshun Tay
 author_title: Front End Engineer @ Facebook

packages/docusaurus-init/templates/classic/blog/2019-05-28-hola.md

@@ -1,5 +1,5 @@
 ---
-id: hola
+slug: hola
 title: Hola
 author: Gao Wei
 author_title: Docusaurus Core Team

packages/docusaurus-init/templates/classic/blog/2019-05-29-hello-world.md

@@ -1,5 +1,5 @@
 ---
-id: hello-world
+slug: hello-world
 title: Hello
 author: Endilie Yacop Sucipto
 author_title: Maintainer of Docusaurus

packages/docusaurus-init/templates/classic/blog/2019-05-30-welcome.md

@@ -1,5 +1,5 @@
 ---
-id: welcome
+slug: welcome
 title: Welcome
 author: Yangshun Tay
 author_title: Front End Engineer @ Facebook

packages/docusaurus-init/templates/facebook/blog/2019-05-28-hola.md

@@ -1,5 +1,5 @@
 ---
-id: hola
+slug: hola
 title: Hola
 author: Gao Wei
 author_title: Docusaurus Core Team

packages/docusaurus-init/templates/facebook/blog/2019-05-29-hello-world.md

@@ -1,5 +1,5 @@
 ---
-id: hello-world
+slug: hello-world
 title: Hello
 author: Endilie Yacop Sucipto
 author_title: Maintainer of Docusaurus

packages/docusaurus-init/templates/facebook/blog/2019-05-30-welcome.md

@@ -1,5 +1,5 @@
 ---
-id: welcome
+slug: welcome
 title: Welcome
 author: Yangshun Tay
 author_title: Front End Engineer @ Facebook

packages/docusaurus-plugin-content-blog/package.json

@@ -23,6 +23,7 @@
     "@docusaurus/utils-validation": "^2.0.0-alpha.61",
     "@hapi/joi": "^17.1.1",
     "feed": "^4.1.0",
+    "chalk": "^3.0.0",
     "fs-extra": "^8.1.0",
     "globby": "^10.0.1",
     "loader-utils": "^1.2.3",

packages/docusaurus-plugin-content-blog/src/__tests__/__fixtures__/website/blog/complex-slug.md

@@ -0,0 +1,7 @@
+---
+slug: /hey/my super path/héllô
+title: Complex Slug
+date: 2020-08-16
+---
+
+complex url slug

packages/docusaurus-plugin-content-blog/src/__tests__/__fixtures__/website/blog/simple-slug.md

@@ -0,0 +1,7 @@
+---
+slug: /simple/slug
+title: Simple Slug
+date: 2020-08-16
+---
+
+simple url slug

packages/docusaurus-plugin-content-blog/src/__tests__/__snapshots__/generateBlogFeed.test.ts.snap

@@ -28,14 +28,14 @@ exports[`blogFeed atom shows feed item for each post 1`] = `
     <entry>
         <title type=\\"html\\"><![CDATA[draft]]></title>
         <id>draft</id>
-        <link href=\\"https://docusaurus.io/blog/2020/02/27/draft\\"/>
+        <link href=\\"https://docusaurus.io/blog/draft\\"/>
         <updated>2020-02-27T00:00:00.000Z</updated>
         <summary type=\\"html\\"><![CDATA[this post should not be published yet]]></summary>
     </entry>
     <entry>
         <title type=\\"html\\"><![CDATA[date-matter]]></title>
         <id>date-matter</id>
-        <link href=\\"https://docusaurus.io/blog/2019/01/01/date-matter\\"/>
+        <link href=\\"https://docusaurus.io/blog/date-matter\\"/>
         <updated>2019-01-01T00:00:00.000Z</updated>
         <summary type=\\"html\\"><![CDATA[date inside front matter]]></summary>
     </entry>
@@ -77,14 +77,14 @@ exports[`blogFeed rss shows feed item for each post 1`] = `
         <copyright>Copyright</copyright>
         <item>
             <title><![CDATA[draft]]></title>
-            <link>https://docusaurus.io/blog/2020/02/27/draft</link>
+            <link>https://docusaurus.io/blog/draft</link>
             <guid>draft</guid>
             <pubDate>Thu, 27 Feb 2020 00:00:00 GMT</pubDate>
             <description><![CDATA[this post should not be published yet]]></description>
         </item>
         <item>
             <title><![CDATA[date-matter]]></title>
-            <link>https://docusaurus.io/blog/2019/01/01/date-matter</link>
+            <link>https://docusaurus.io/blog/date-matter</link>
             <guid>date-matter</guid>
             <pubDate>Tue, 01 Jan 2019 00:00:00 GMT</pubDate>
             <description><![CDATA[date inside front matter]]></description>

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

@@ -53,10 +53,6 @@ describe('loadBlog', () => {
     const noDateSourceBirthTime = (
       await fs.stat(noDateSource.replace('@site', siteDir))
     ).birthtime;
-    const noDatePermalink = `/blog/${noDateSourceBirthTime
-      .toISOString()
-      .substr(0, '2019-01-01'.length)
-      .replace(/-/g, '/')}/no date`;
 
     expect({
       ...blogPosts.find((v) => v.metadata.title === 'date-matter').metadata,
@@ -64,7 +60,7 @@ describe('loadBlog', () => {
     }).toEqual({
       editUrl:
         'https://github.com/facebook/docusaurus/edit/master/website-1x/blog/date-matter.md',
-      permalink: '/blog/2019/01/01/date-matter',
+      permalink: '/blog/date-matter',
       readingTime: 0.02,
       source: path.join('@site', pluginPath, 'date-matter.md'),
       title: 'date-matter',
@@ -97,7 +93,7 @@ describe('loadBlog', () => {
       date: new Date('2018-12-14'),
       tags: [],
       prevItem: {
-        permalink: '/blog/2019/01/01/date-matter',
+        permalink: '/blog/date-matter',
         title: 'date-matter',
       },
       truncated: false,
@@ -109,7 +105,7 @@ describe('loadBlog', () => {
     }).toEqual({
       editUrl:
         'https://github.com/facebook/docusaurus/edit/master/website-1x/blog/no date.md',
-      permalink: noDatePermalink,
+      permalink: '/blog/no date',
       readingTime: 0.01,
       source: noDateSource,
       title: 'no date',
@@ -118,9 +114,51 @@ describe('loadBlog', () => {
       tags: [],
       prevItem: undefined,
       nextItem: {
-        permalink: '/blog/2020/02/27/draft',
+        permalink: '/blog/hey/my super path/héllô',
+        title: 'Complex Slug',
+      },
+      truncated: false,
+    });
+
+    expect({
+      ...blogPosts.find((v) => v.metadata.title === 'Complex Slug').metadata,
+      ...{prevItem: undefined},
+    }).toEqual({
+      editUrl:
+        'https://github.com/facebook/docusaurus/edit/master/website-1x/blog/complex-slug.md',
+      permalink: '/blog/hey/my super path/héllô',
+      readingTime: 0.015,
+      source: path.join('@site', pluginPath, 'complex-slug.md'),
+      title: 'Complex Slug',
+      description: `complex url slug`,
+      prevItem: undefined,
+      nextItem: {
+        permalink: '/blog/simple/slug',
+        title: 'Simple Slug',
+      },
+      date: new Date('2020-08-16'),
+      tags: [],
+      truncated: false,
+    });
+
+    expect({
+      ...blogPosts.find((v) => v.metadata.title === 'Simple Slug').metadata,
+      ...{prevItem: undefined},
+    }).toEqual({
+      editUrl:
+        'https://github.com/facebook/docusaurus/edit/master/website-1x/blog/simple-slug.md',
+      permalink: '/blog/simple/slug',
+      readingTime: 0.015,
+      source: path.join('@site', pluginPath, 'simple-slug.md'),
+      title: 'Simple Slug',
+      description: `simple url slug`,
+      prevItem: undefined,
+      nextItem: {
+        permalink: '/blog/draft',
         title: 'draft',
       },
+      date: new Date('2020-08-16'),
+      tags: [],
       truncated: false,
     });
   });

packages/docusaurus-plugin-content-blog/src/blogUtils.ts

@@ -7,6 +7,7 @@
 
 import fs from 'fs-extra';
 import globby from 'globby';
+import chalk from 'chalk';
 import path from 'path';
 import readingTime from 'reading-time';
 import {Feed} from 'feed';
@@ -126,6 +127,14 @@ export async function generateBlogPosts(
         return;
       }
 
+      if (frontMatter.id) {
+        console.warn(
+          chalk.yellow(
+            `${blogFileName} - 'id' header option is deprecated. Please use 'slug' option instead.`,
+          ),
+        );
+      }
+
       let date;
       // Extract date and title from filename.
       const match = blogFileName.match(FILENAME_PATTERN);
@@ -144,16 +153,15 @@ export async function generateBlogPosts(
 
       // Use file create time for blog.
       date = date || (await fs.stat(source)).birthtime;
+
+      const slug =
+        frontMatter.slug || (match ? toUrl({date, link: linkName}) : linkName);
       frontMatter.title = frontMatter.title || linkName;
 
       blogPosts.push({
-        id: frontMatter.id || frontMatter.title,
+        id: frontMatter.slug || frontMatter.title,
         metadata: {
-          permalink: normalizeUrl([
+          permalink: normalizeUrl([baseUrl, routeBasePath, slug]),
-            baseUrl,
-            routeBasePath,
-            frontMatter.id || toUrl({date, link: linkName}),
-          ]),
           editUrl: editBlogUrl,
           source: aliasedSource,
           description: frontMatter.description || excerpt,