diff --git a/docs/guides-blog.md b/docs/guides-blog.md index c70eafaa92..4391d43566 100644 --- a/docs/guides-blog.md +++ b/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 diff --git a/packages/docusaurus-init/templates/bootstrap/blog/2019-05-28-hola.md b/packages/docusaurus-init/templates/bootstrap/blog/2019-05-28-hola.md index 5552da124f..4adbc327fc 100644 --- a/packages/docusaurus-init/templates/bootstrap/blog/2019-05-28-hola.md +++ b/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 diff --git a/packages/docusaurus-init/templates/bootstrap/blog/2019-05-29-hello-world.md b/packages/docusaurus-init/templates/bootstrap/blog/2019-05-29-hello-world.md index 3b33193938..151671f023 100644 --- a/packages/docusaurus-init/templates/bootstrap/blog/2019-05-29-hello-world.md +++ b/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 diff --git a/packages/docusaurus-init/templates/bootstrap/blog/2019-05-30-welcome.md b/packages/docusaurus-init/templates/bootstrap/blog/2019-05-30-welcome.md index 3b5affedce..d35d57b7dc 100644 --- a/packages/docusaurus-init/templates/bootstrap/blog/2019-05-30-welcome.md +++ b/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 diff --git a/packages/docusaurus-init/templates/classic/blog/2019-05-28-hola.md b/packages/docusaurus-init/templates/classic/blog/2019-05-28-hola.md index 5552da124f..4adbc327fc 100644 --- a/packages/docusaurus-init/templates/classic/blog/2019-05-28-hola.md +++ b/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 diff --git a/packages/docusaurus-init/templates/classic/blog/2019-05-29-hello-world.md b/packages/docusaurus-init/templates/classic/blog/2019-05-29-hello-world.md index 3b33193938..151671f023 100644 --- a/packages/docusaurus-init/templates/classic/blog/2019-05-29-hello-world.md +++ b/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 diff --git a/packages/docusaurus-init/templates/classic/blog/2019-05-30-welcome.md b/packages/docusaurus-init/templates/classic/blog/2019-05-30-welcome.md index 3b5affedce..d35d57b7dc 100644 --- a/packages/docusaurus-init/templates/classic/blog/2019-05-30-welcome.md +++ b/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 diff --git a/packages/docusaurus-init/templates/facebook/blog/2019-05-28-hola.md b/packages/docusaurus-init/templates/facebook/blog/2019-05-28-hola.md index 5552da124f..4adbc327fc 100644 --- a/packages/docusaurus-init/templates/facebook/blog/2019-05-28-hola.md +++ b/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 diff --git a/packages/docusaurus-init/templates/facebook/blog/2019-05-29-hello-world.md b/packages/docusaurus-init/templates/facebook/blog/2019-05-29-hello-world.md index 3b33193938..151671f023 100644 --- a/packages/docusaurus-init/templates/facebook/blog/2019-05-29-hello-world.md +++ b/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 diff --git a/packages/docusaurus-init/templates/facebook/blog/2019-05-30-welcome.md b/packages/docusaurus-init/templates/facebook/blog/2019-05-30-welcome.md index 3b5affedce..d35d57b7dc 100644 --- a/packages/docusaurus-init/templates/facebook/blog/2019-05-30-welcome.md +++ b/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 diff --git a/packages/docusaurus-plugin-content-blog/package.json b/packages/docusaurus-plugin-content-blog/package.json index 583c98091f..3cbb69f883 100644 --- a/packages/docusaurus-plugin-content-blog/package.json +++ b/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", diff --git a/packages/docusaurus-plugin-content-blog/src/__tests__/__fixtures__/website/blog/complex-slug.md b/packages/docusaurus-plugin-content-blog/src/__tests__/__fixtures__/website/blog/complex-slug.md new file mode 100644 index 0000000000..01236db3d2 --- /dev/null +++ b/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 diff --git a/packages/docusaurus-plugin-content-blog/src/__tests__/__fixtures__/website/blog/simple-slug.md b/packages/docusaurus-plugin-content-blog/src/__tests__/__fixtures__/website/blog/simple-slug.md new file mode 100644 index 0000000000..470ad3a684 --- /dev/null +++ b/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 diff --git a/packages/docusaurus-plugin-content-blog/src/__tests__/__snapshots__/generateBlogFeed.test.ts.snap b/packages/docusaurus-plugin-content-blog/src/__tests__/__snapshots__/generateBlogFeed.test.ts.snap index bc87fbf45f..56d761b878 100644 --- a/packages/docusaurus-plugin-content-blog/src/__tests__/__snapshots__/generateBlogFeed.test.ts.snap +++ b/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`] = ` <![CDATA[draft]]> draft - + 2020-02-27T00:00:00.000Z <![CDATA[date-matter]]> date-matter - + 2019-01-01T00:00:00.000Z @@ -77,14 +77,14 @@ exports[`blogFeed rss shows feed item for each post 1`] = ` Copyright <![CDATA[draft]]> - https://docusaurus.io/blog/2020/02/27/draft + https://docusaurus.io/blog/draft draft Thu, 27 Feb 2020 00:00:00 GMT <![CDATA[date-matter]]> - https://docusaurus.io/blog/2019/01/01/date-matter + https://docusaurus.io/blog/date-matter date-matter Tue, 01 Jan 2019 00:00:00 GMT diff --git a/packages/docusaurus-plugin-content-blog/src/__tests__/index.test.ts b/packages/docusaurus-plugin-content-blog/src/__tests__/index.test.ts index 0bc9715fa0..7c06d2b812 100644 --- a/packages/docusaurus-plugin-content-blog/src/__tests__/index.test.ts +++ b/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, }); }); diff --git a/packages/docusaurus-plugin-content-blog/src/blogUtils.ts b/packages/docusaurus-plugin-content-blog/src/blogUtils.ts index 184023925a..9d2314122d 100644 --- a/packages/docusaurus-plugin-content-blog/src/blogUtils.ts +++ b/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([ - baseUrl, - routeBasePath, - frontMatter.id || toUrl({date, link: linkName}), - ]), + permalink: normalizeUrl([baseUrl, routeBasePath, slug]), editUrl: editBlogUrl, source: aliasedSource, description: frontMatter.description || excerpt,