From 76a8d5f38a3049e20c010784867c6ed94083a6da Mon Sep 17 00:00:00 2001 From: Joshua Chen Date: Wed, 26 Jan 2022 23:54:15 +0800 Subject: [PATCH 001/352] fix(content-blog): generate feed by reading build output (#6454) --- .../package.json | 2 + .../14/Happy-First-Birthday-Slash/index.html | 18 +++ .../build-snap/blog/archive/index.html | 18 +++ .../build-snap/blog/date-matter/index.html | 18 +++ .../blog/heading-as-title/index.html | 18 +++ .../blog/hey/my super path/héllô/index.html | 18 +++ .../website/build-snap/blog/index.html | 19 +++ .../build-snap/blog/mdx-blog-post/index.html | 19 +++ .../blog/mdx-require-blog-post/index.html | 18 +++ .../build-snap/blog/simple/slug/index.html | 18 +++ .../build-snap/blog/tags/birthday/index.html | 18 +++ .../build-snap/blog/tags/complex/index.html | 18 +++ .../build-snap/blog/tags/date/index.html | 18 +++ .../website/build-snap/blog/tags/index.html | 18 +++ .../__tests__/__snapshots__/feed.test.ts.snap | 59 ++------ .../src/__tests__/feed.test.ts | 14 +- .../src/feed.ts | 42 +++--- .../src/index.ts | 8 +- .../docusaurus-theme-classic/package.json | 1 + .../src/theme/BlogPostItem/index.tsx | 7 +- packages/docusaurus-types/src/index.d.ts | 2 +- packages/docusaurus-utils-common/src/index.ts | 1 + .../src/__tests__/mdxUtils.test.ts | 133 ------------------ packages/docusaurus-utils/src/index.ts | 34 ++++- packages/docusaurus-utils/src/mdxUtils.ts | 32 ----- packages/docusaurus/src/commands/build.ts | 7 +- .../docs/api/plugin-methods/lifecycle-apis.md | 1 + yarn.lock | 34 ++++- 28 files changed, 364 insertions(+), 249 deletions(-) create mode 100644 packages/docusaurus-plugin-content-blog/src/__tests__/__fixtures__/website/build-snap/blog/2018/12/14/Happy-First-Birthday-Slash/index.html create mode 100644 packages/docusaurus-plugin-content-blog/src/__tests__/__fixtures__/website/build-snap/blog/archive/index.html create mode 100644 packages/docusaurus-plugin-content-blog/src/__tests__/__fixtures__/website/build-snap/blog/date-matter/index.html create mode 100644 packages/docusaurus-plugin-content-blog/src/__tests__/__fixtures__/website/build-snap/blog/heading-as-title/index.html create mode 100644 packages/docusaurus-plugin-content-blog/src/__tests__/__fixtures__/website/build-snap/blog/hey/my super path/héllô/index.html create mode 100644 packages/docusaurus-plugin-content-blog/src/__tests__/__fixtures__/website/build-snap/blog/index.html create mode 100644 packages/docusaurus-plugin-content-blog/src/__tests__/__fixtures__/website/build-snap/blog/mdx-blog-post/index.html create mode 100644 packages/docusaurus-plugin-content-blog/src/__tests__/__fixtures__/website/build-snap/blog/mdx-require-blog-post/index.html create mode 100644 packages/docusaurus-plugin-content-blog/src/__tests__/__fixtures__/website/build-snap/blog/simple/slug/index.html create mode 100644 packages/docusaurus-plugin-content-blog/src/__tests__/__fixtures__/website/build-snap/blog/tags/birthday/index.html create mode 100644 packages/docusaurus-plugin-content-blog/src/__tests__/__fixtures__/website/build-snap/blog/tags/complex/index.html create mode 100644 packages/docusaurus-plugin-content-blog/src/__tests__/__fixtures__/website/build-snap/blog/tags/date/index.html create mode 100644 packages/docusaurus-plugin-content-blog/src/__tests__/__fixtures__/website/build-snap/blog/tags/index.html delete mode 100644 packages/docusaurus-utils/src/__tests__/mdxUtils.test.ts delete mode 100644 packages/docusaurus-utils/src/mdxUtils.ts diff --git a/packages/docusaurus-plugin-content-blog/package.json b/packages/docusaurus-plugin-content-blog/package.json index 3abd1efc99..5c5dd3543f 100644 --- a/packages/docusaurus-plugin-content-blog/package.json +++ b/packages/docusaurus-plugin-content-blog/package.json @@ -22,7 +22,9 @@ "@docusaurus/logger": "2.0.0-beta.14", "@docusaurus/mdx-loader": "2.0.0-beta.14", "@docusaurus/utils": "2.0.0-beta.14", + "@docusaurus/utils-common": "2.0.0-beta.14", "@docusaurus/utils-validation": "2.0.0-beta.14", + "cheerio": "^1.0.0-rc.10", "feed": "^4.2.2", "fs-extra": "^10.0.0", "lodash": "^4.17.20", diff --git a/packages/docusaurus-plugin-content-blog/src/__tests__/__fixtures__/website/build-snap/blog/2018/12/14/Happy-First-Birthday-Slash/index.html b/packages/docusaurus-plugin-content-blog/src/__tests__/__fixtures__/website/build-snap/blog/2018/12/14/Happy-First-Birthday-Slash/index.html new file mode 100644 index 0000000000..1a3b803a8f --- /dev/null +++ b/packages/docusaurus-plugin-content-blog/src/__tests__/__fixtures__/website/build-snap/blog/2018/12/14/Happy-First-Birthday-Slash/index.html @@ -0,0 +1,18 @@ + + + + + + + +Happy 1st Birthday Slash! | My Site + + + + +
+
Skip to main content
+ + + + diff --git a/packages/docusaurus-plugin-content-blog/src/__tests__/__fixtures__/website/build-snap/blog/archive/index.html b/packages/docusaurus-plugin-content-blog/src/__tests__/__fixtures__/website/build-snap/blog/archive/index.html new file mode 100644 index 0000000000..403fe3174d --- /dev/null +++ b/packages/docusaurus-plugin-content-blog/src/__tests__/__fixtures__/website/build-snap/blog/archive/index.html @@ -0,0 +1,18 @@ + + + + + + + +Archive | My Site + + + + +
+
Skip to main content

Archive

Archive

2018

2019

2020

2021

+ + + + \ No newline at end of file diff --git a/packages/docusaurus-plugin-content-blog/src/__tests__/__fixtures__/website/build-snap/blog/date-matter/index.html b/packages/docusaurus-plugin-content-blog/src/__tests__/__fixtures__/website/build-snap/blog/date-matter/index.html new file mode 100644 index 0000000000..f56293ab02 --- /dev/null +++ b/packages/docusaurus-plugin-content-blog/src/__tests__/__fixtures__/website/build-snap/blog/date-matter/index.html @@ -0,0 +1,18 @@ + + + + + + + +date-matter | My Site + + + + +
+
Skip to main content

date-matter

· One min read

date inside front matter

+ + + + diff --git a/packages/docusaurus-plugin-content-blog/src/__tests__/__fixtures__/website/build-snap/blog/heading-as-title/index.html b/packages/docusaurus-plugin-content-blog/src/__tests__/__fixtures__/website/build-snap/blog/heading-as-title/index.html new file mode 100644 index 0000000000..8e699a3d2d --- /dev/null +++ b/packages/docusaurus-plugin-content-blog/src/__tests__/__fixtures__/website/build-snap/blog/heading-as-title/index.html @@ -0,0 +1,18 @@ + + + + + + + +some heading | My Site + + + + +
+
Skip to main content

some heading

· 0 min read
+ + + + diff --git a/packages/docusaurus-plugin-content-blog/src/__tests__/__fixtures__/website/build-snap/blog/hey/my super path/héllô/index.html b/packages/docusaurus-plugin-content-blog/src/__tests__/__fixtures__/website/build-snap/blog/hey/my super path/héllô/index.html new file mode 100644 index 0000000000..99bfcb770a --- /dev/null +++ b/packages/docusaurus-plugin-content-blog/src/__tests__/__fixtures__/website/build-snap/blog/hey/my super path/héllô/index.html @@ -0,0 +1,18 @@ + + + + + + + +Complex Slug | My Site + + + + +
+
Skip to main content

Complex Slug

· One min read

complex url slug

+ + + + diff --git a/packages/docusaurus-plugin-content-blog/src/__tests__/__fixtures__/website/build-snap/blog/index.html b/packages/docusaurus-plugin-content-blog/src/__tests__/__fixtures__/website/build-snap/blog/index.html new file mode 100644 index 0000000000..b0ba576b63 --- /dev/null +++ b/packages/docusaurus-plugin-content-blog/src/__tests__/__fixtures__/website/build-snap/blog/index.html @@ -0,0 +1,19 @@ + + + + + + + +Blog | My Site + + + + +
+
Skip to main content

· One min read

HTML Heading 1

HTML Heading 2

HTML Paragraph

Import DOM

Heading 1

Heading 2​

Heading 3​

Heading 4​

Heading 5​
  • list1
  • list2
  • list3
  • list1
  • list2
  • list3

Normal Text Italics Text Bold Text

link +image

· One min read

date inside front matter

+ + + + \ No newline at end of file diff --git a/packages/docusaurus-plugin-content-blog/src/__tests__/__fixtures__/website/build-snap/blog/mdx-blog-post/index.html b/packages/docusaurus-plugin-content-blog/src/__tests__/__fixtures__/website/build-snap/blog/mdx-blog-post/index.html new file mode 100644 index 0000000000..921732b877 --- /dev/null +++ b/packages/docusaurus-plugin-content-blog/src/__tests__/__fixtures__/website/build-snap/blog/mdx-blog-post/index.html @@ -0,0 +1,19 @@ + + + + + + + +Full Blog Sample | My Site + + + + +
+
Skip to main content

Full Blog Sample

· One min read

HTML Heading 1

HTML Heading 2

HTML Paragraph

Import DOM

Heading 1

Heading 2​

Heading 3​

Heading 4​

Heading 5​
  • list1
  • list2
  • list3
  • list1
  • list2
  • list3

Normal Text Italics Text Bold Text

link +image

+ + + + diff --git a/packages/docusaurus-plugin-content-blog/src/__tests__/__fixtures__/website/build-snap/blog/mdx-require-blog-post/index.html b/packages/docusaurus-plugin-content-blog/src/__tests__/__fixtures__/website/build-snap/blog/mdx-require-blog-post/index.html new file mode 100644 index 0000000000..8d0ac938d8 --- /dev/null +++ b/packages/docusaurus-plugin-content-blog/src/__tests__/__fixtures__/website/build-snap/blog/mdx-require-blog-post/index.html @@ -0,0 +1,18 @@ + + + + + + + +MDX Blog Sample with require calls | My Site + + + + +
+
Skip to main content

MDX Blog Sample with require calls

· One min read

Test MDX with require calls

+ + + + diff --git a/packages/docusaurus-plugin-content-blog/src/__tests__/__fixtures__/website/build-snap/blog/simple/slug/index.html b/packages/docusaurus-plugin-content-blog/src/__tests__/__fixtures__/website/build-snap/blog/simple/slug/index.html new file mode 100644 index 0000000000..1dd47a9943 --- /dev/null +++ b/packages/docusaurus-plugin-content-blog/src/__tests__/__fixtures__/website/build-snap/blog/simple/slug/index.html @@ -0,0 +1,18 @@ + + + + + + + +Simple Slug | My Site + + + + +
+
Skip to main content

Simple Slug

· One min read

simple url slug

+ + + + diff --git a/packages/docusaurus-plugin-content-blog/src/__tests__/__fixtures__/website/build-snap/blog/tags/birthday/index.html b/packages/docusaurus-plugin-content-blog/src/__tests__/__fixtures__/website/build-snap/blog/tags/birthday/index.html new file mode 100644 index 0000000000..f9820c0f21 --- /dev/null +++ b/packages/docusaurus-plugin-content-blog/src/__tests__/__fixtures__/website/build-snap/blog/tags/birthday/index.html @@ -0,0 +1,18 @@ + + + + + + + +One post tagged with "birthday" | My Site + + + + +
+
Skip to main content

One post tagged with "birthday"

View All Tags
+ + + + \ No newline at end of file diff --git a/packages/docusaurus-plugin-content-blog/src/__tests__/__fixtures__/website/build-snap/blog/tags/complex/index.html b/packages/docusaurus-plugin-content-blog/src/__tests__/__fixtures__/website/build-snap/blog/tags/complex/index.html new file mode 100644 index 0000000000..c8b5017f1a --- /dev/null +++ b/packages/docusaurus-plugin-content-blog/src/__tests__/__fixtures__/website/build-snap/blog/tags/complex/index.html @@ -0,0 +1,18 @@ + + + + + + + +One post tagged with "complex" | My Site + + + + +
+
Skip to main content

One post tagged with "complex"

View All Tags
+ + + + \ No newline at end of file diff --git a/packages/docusaurus-plugin-content-blog/src/__tests__/__fixtures__/website/build-snap/blog/tags/date/index.html b/packages/docusaurus-plugin-content-blog/src/__tests__/__fixtures__/website/build-snap/blog/tags/date/index.html new file mode 100644 index 0000000000..1878e30260 --- /dev/null +++ b/packages/docusaurus-plugin-content-blog/src/__tests__/__fixtures__/website/build-snap/blog/tags/date/index.html @@ -0,0 +1,18 @@ + + + + + + + +2 posts tagged with "date" | My Site + + + + +
+
Skip to main content

2 posts tagged with "date"

View All Tags
+ + + + \ No newline at end of file diff --git a/packages/docusaurus-plugin-content-blog/src/__tests__/__fixtures__/website/build-snap/blog/tags/index.html b/packages/docusaurus-plugin-content-blog/src/__tests__/__fixtures__/website/build-snap/blog/tags/index.html new file mode 100644 index 0000000000..292400b08f --- /dev/null +++ b/packages/docusaurus-plugin-content-blog/src/__tests__/__fixtures__/website/build-snap/blog/tags/index.html @@ -0,0 +1,18 @@ + + + + + + + +Tags | My Site + + + + +
+
Skip to main content

Tags

+ + + + \ No newline at end of file diff --git a/packages/docusaurus-plugin-content-blog/src/__tests__/__snapshots__/feed.test.ts.snap b/packages/docusaurus-plugin-content-blog/src/__tests__/__snapshots__/feed.test.ts.snap index 6c5dd55354..28d2e5b294 100644 --- a/packages/docusaurus-plugin-content-blog/src/__tests__/__snapshots__/feed.test.ts.snap +++ b/packages/docusaurus-plugin-content-blog/src/__tests__/__snapshots__/feed.test.ts.snap @@ -2,9 +2,7 @@ exports[`blogFeed atom shows feed item for each post 1`] = ` Array [ - Array [ - "build/blog/atom.xml", - " + " https://docusaurus.io/myBaseUrl/blog Hello Blog @@ -20,6 +18,7 @@ Array [ 2021-03-06T00:00:00.000Z + Test MDX with require calls

]]> <![CDATA[Full Blog Sample]]> @@ -27,8 +26,8 @@ Array [ 2021-03-05T00:00:00.000Z - HTML Heading 1

HTML Heading 2

HTML Paragraph

Import DOM

Heading 1

Heading 2

Heading 3

Heading 4

Heading 5
  • list1
  • list2
  • list3
  • list1
  • list2
  • list3

Normal Text Italics Text Bold Text

link -\\"image\\"/

]]> + HTML Heading 1

HTML Heading 2

HTML Paragraph

Import DOM

Heading 1

Heading 2​

Heading 3​

Heading 4​

Heading 5​
  • list1
  • list2
  • list3
  • list1
  • list2
  • list3

Normal Text Italics Text Bold Text

link +\\"image\\"

]]> <![CDATA[Complex Slug]]> @@ -52,14 +51,6 @@ Array [ https://sebastienlorber.com - - <![CDATA[draft]]> - /draft - - 2020-02-27T00:00:00.000Z - - this post should not be published yet

]]> - <![CDATA[some heading]]> /heading-as-title @@ -81,7 +72,7 @@ Array [ 2018-12-14T00:00:00.000Z - Happy birthday! (translated)

]]> + Happy birthday!

]]> Yangshun Tay (translated) @@ -90,15 +81,12 @@ Array [ ", - ], ] `; exports[`blogFeed json shows feed item for each post 1`] = ` Array [ - Array [ - "build/blog/feed.json", - "{ + "{ \\"version\\": \\"https://jsonfeed.org/version/1\\", \\"title\\": \\"Hello Blog\\", \\"home_page_url\\": \\"https://docusaurus.io/myBaseUrl/blog\\", @@ -106,6 +94,7 @@ Array [ \\"items\\": [ { \\"id\\": \\"/mdx-require-blog-post\\", + \\"content_html\\": \\"

Test MDX with require calls

\\", \\"url\\": \\"https://docusaurus.io/myBaseUrl/blog/mdx-require-blog-post\\", \\"title\\": \\"MDX Blog Sample with require calls\\", \\"summary\\": \\"Test MDX with require calls\\", @@ -114,7 +103,7 @@ Array [ }, { \\"id\\": \\"/mdx-blog-post\\", - \\"content_html\\": \\"

HTML Heading 1

HTML Heading 2

HTML Paragraph

Import DOM

Heading 1

Heading 2

Heading 3

Heading 4

Heading 5

Normal Text Italics Text Bold Text

link\\\\n\\\\\\"image\\\\\\"/

\\", + \\"content_html\\": \\"

HTML Heading 1

HTML Heading 2

HTML Paragraph

Import DOM

Heading 1

Heading 2​

Heading 3​

Heading 4​

Heading 5​

Normal Text Italics Text Bold Text

link\\\\n\\\\\\"image\\\\\\"

\\", \\"url\\": \\"https://docusaurus.io/myBaseUrl/blog/mdx-blog-post\\", \\"title\\": \\"Full Blog Sample\\", \\"summary\\": \\"HTML Heading 1\\", @@ -146,15 +135,6 @@ Array [ }, \\"tags\\": [] }, - { - \\"id\\": \\"/draft\\", - \\"content_html\\": \\"

this post should not be published yet

\\", - \\"url\\": \\"https://docusaurus.io/myBaseUrl/blog/draft\\", - \\"title\\": \\"draft\\", - \\"summary\\": \\"this post should not be published yet\\", - \\"date_modified\\": \\"2020-02-27T00:00:00.000Z\\", - \\"tags\\": [] - }, { \\"id\\": \\"/heading-as-title\\", \\"content_html\\": \\"\\", @@ -176,7 +156,7 @@ Array [ }, { \\"id\\": \\"/2018/12/14/Happy-First-Birthday-Slash\\", - \\"content_html\\": \\"

Happy birthday! (translated)

\\", + \\"content_html\\": \\"

Happy birthday!

\\", \\"url\\": \\"https://docusaurus.io/myBaseUrl/blog/2018/12/14/Happy-First-Birthday-Slash\\", \\"title\\": \\"Happy 1st Birthday Slash! (translated)\\", \\"summary\\": \\"Happy birthday! (translated)\\", @@ -188,15 +168,12 @@ Array [ } ] }", - ], ] `; exports[`blogFeed rss shows feed item for each post 1`] = ` Array [ - Array [ - "build/blog/rss.xml", - " + " Hello Blog @@ -212,6 +189,7 @@ Array [ /mdx-require-blog-post Sat, 06 Mar 2021 00:00:00 GMT + Test MDX with require calls

]]> <![CDATA[Full Blog Sample]]> @@ -219,8 +197,8 @@ Array [ /mdx-blog-post Fri, 05 Mar 2021 00:00:00 GMT - HTML Heading 1

HTML Heading 2

HTML Paragraph

Import DOM

Heading 1

Heading 2

Heading 3

Heading 4

Heading 5
  • list1
  • list2
  • list3
  • list1
  • list2
  • list3

Normal Text Italics Text Bold Text

link -\\"image\\"/

]]> + HTML Heading 1

HTML Heading 2

HTML Paragraph

Import DOM

Heading 1

Heading 2​

Heading 3​

Heading 4​

Heading 5​
  • list1
  • list2
  • list3
  • list1
  • list2
  • list3

Normal Text Italics Text Bold Text

link +\\"image\\"

]]> <![CDATA[Complex Slug]]> @@ -240,14 +218,6 @@ Array [ simple url slug

]]> - - <![CDATA[draft]]> - https://docusaurus.io/myBaseUrl/blog/draft - /draft - Thu, 27 Feb 2020 00:00:00 GMT - - this post should not be published yet

]]> - <![CDATA[some heading]]> https://docusaurus.io/myBaseUrl/blog/heading-as-title @@ -269,10 +239,9 @@ Array [ /2018/12/14/Happy-First-Birthday-Slash Fri, 14 Dec 2018 00:00:00 GMT - Happy birthday! (translated)

]]> + Happy birthday!

]]> ", - ], ] `; diff --git a/packages/docusaurus-plugin-content-blog/src/__tests__/feed.test.ts b/packages/docusaurus-plugin-content-blog/src/__tests__/feed.test.ts index d6d5d1f2d3..bd77b29115 100644 --- a/packages/docusaurus-plugin-content-blog/src/__tests__/feed.test.ts +++ b/packages/docusaurus-plugin-content-blog/src/__tests__/feed.test.ts @@ -44,10 +44,10 @@ async function testGenerateFeeds( ); await createBlogFeedFiles({ - blogPosts, + blogPosts: blogPosts.filter((post) => !post.metadata.frontMatter.draft), options, siteConfig: context.siteConfig, - outDir: 'build', + outDir: context.outDir, }); } @@ -64,12 +64,14 @@ describe('blogFeed', () => { url: 'https://docusaurus.io', favicon: 'image/favicon.ico', }; + const outDir = path.join(siteDir, 'build-snap'); await testGenerateFeeds( { siteDir, siteConfig, i18n: DefaultI18N, + outDir, } as LoadContext, { path: 'invalid-blog-path', @@ -92,7 +94,7 @@ describe('blogFeed', () => { test('shows feed item for each post', async () => { const siteDir = path.join(__dirname, '__fixtures__', 'website'); - const generatedFilesDir = path.resolve(siteDir, '.docusaurus'); + const outDir = path.join(siteDir, 'build-snap'); const siteConfig = { title: 'Hello', baseUrl: '/myBaseUrl/', @@ -100,12 +102,14 @@ describe('blogFeed', () => { favicon: 'image/favicon.ico', }; + // Build is quite difficult to mock, so we built the blog beforehand and + // copied the output to the fixture... await testGenerateFeeds( { siteDir, siteConfig, - generatedFilesDir, i18n: DefaultI18N, + outDir, } as LoadContext, { path: 'blog', @@ -123,7 +127,7 @@ describe('blogFeed', () => { } as PluginOptions, ); - expect(fsMock.mock.calls).toMatchSnapshot(); + expect(fsMock.mock.calls.map((call) => call[1])).toMatchSnapshot(); fsMock.mockClear(); }); }); diff --git a/packages/docusaurus-plugin-content-blog/src/feed.ts b/packages/docusaurus-plugin-content-blog/src/feed.ts index 20f9a109a5..1357135e60 100644 --- a/packages/docusaurus-plugin-content-blog/src/feed.ts +++ b/packages/docusaurus-plugin-content-blog/src/feed.ts @@ -7,7 +7,13 @@ import {Feed, type Author as FeedAuthor, type Item as FeedItem} from 'feed'; import type {BlogPost} from './types'; -import {normalizeUrl, mdxToHtml, posixPath} from '@docusaurus/utils'; +import { + normalizeUrl, + posixPath, + mapAsyncSequential, + readOutputHTMLFile, +} from '@docusaurus/utils'; +import cheerio from 'cheerio'; import type {DocusaurusConfig} from '@docusaurus/types'; import path from 'path'; import fs from 'fs-extra'; @@ -16,28 +22,18 @@ import type { PluginOptions, Author, } from '@docusaurus/plugin-content-blog'; - -// TODO this is temporary until we handle mdxToHtml better -// It's hard to convert reliably JSX/require calls to an html feed content -// See https://github.com/facebook/docusaurus/issues/5664 -function mdxToFeedContent(mdxContent: string): string | undefined { - try { - return mdxToHtml(mdxContent); - } catch (e) { - // TODO will we need a plugin option to configure how to handle such an error - // Swallow the error on purpose for now, until we understand better the problem space - return undefined; - } -} +import {blogPostContainerID} from '@docusaurus/utils-common'; async function generateBlogFeed({ blogPosts, options, siteConfig, + outDir, }: { blogPosts: BlogPost[]; options: PluginOptions; siteConfig: DocusaurusConfig; + outDir: string; }): Promise { if (!blogPosts.length) { return null; @@ -66,7 +62,7 @@ async function generateBlogFeed({ return {name: author.name, link: author.url}; } - blogPosts.forEach((post) => { + await mapAsyncSequential(blogPosts, async (post) => { const { id, metadata: { @@ -79,6 +75,13 @@ async function generateBlogFeed({ }, } = post; + const content = await readOutputHTMLFile( + permalink.replace(siteConfig.baseUrl, ''), + outDir, + siteConfig.trailingSlash, + ); + const $ = cheerio.load(content); + const feedItem: FeedItem = { title: metadataTitle, id, @@ -87,7 +90,7 @@ async function generateBlogFeed({ description, // Atom feed demands the "term", while other feeds use "name" category: tags.map((tag) => ({name: tag.label, term: tag.label})), - content: mdxToFeedContent(post.content), + content: $(`#${blogPostContainerID}`).html()!, }; // json1() method takes the first item of authors array @@ -145,7 +148,12 @@ export async function createBlogFeedFiles({ siteConfig: DocusaurusConfig; outDir: string; }): Promise { - const feed = await generateBlogFeed({blogPosts, options, siteConfig}); + const feed = await generateBlogFeed({ + blogPosts, + options, + siteConfig, + outDir, + }); const feedTypes = options.feedOptions.type; if (!feed || !feedTypes) { diff --git a/packages/docusaurus-plugin-content-blog/src/index.ts b/packages/docusaurus-plugin-content-blog/src/index.ts index c21cfe4a85..14729a2fad 100644 --- a/packages/docusaurus-plugin-content-blog/src/index.ts +++ b/packages/docusaurus-plugin-content-blog/src/index.ts @@ -36,7 +36,6 @@ import {PluginOptionSchema} from './pluginOptionSchema'; import type { LoadContext, ConfigureWebpackUtils, - Props, Plugin, HtmlTags, OptionValidationContext, @@ -512,14 +511,11 @@ export default async function pluginContentBlog( }; }, - async postBuild({outDir}: Props) { + async postBuild({outDir, content}) { if (!options.feedOptions.type) { return; } - - // TODO: we shouldn't need to re-read the posts here! - // postBuild should receive loadedContent - const blogPosts = await generateBlogPosts(contentPaths, context, options); + const {blogPosts} = content; if (!blogPosts.length) { return; } diff --git a/packages/docusaurus-theme-classic/package.json b/packages/docusaurus-theme-classic/package.json index 1dafae9093..5a74747c45 100644 --- a/packages/docusaurus-theme-classic/package.json +++ b/packages/docusaurus-theme-classic/package.json @@ -28,6 +28,7 @@ "@docusaurus/theme-common": "2.0.0-beta.14", "@docusaurus/theme-translations": "2.0.0-beta.14", "@docusaurus/utils": "2.0.0-beta.14", + "@docusaurus/utils-common": "2.0.0-beta.14", "@docusaurus/utils-validation": "2.0.0-beta.14", "@mdx-js/react": "^1.6.21", "clsx": "^1.1.1", diff --git a/packages/docusaurus-theme-classic/src/theme/BlogPostItem/index.tsx b/packages/docusaurus-theme-classic/src/theme/BlogPostItem/index.tsx index 2d98e1909f..dd9c870a80 100644 --- a/packages/docusaurus-theme-classic/src/theme/BlogPostItem/index.tsx +++ b/packages/docusaurus-theme-classic/src/theme/BlogPostItem/index.tsx @@ -12,6 +12,7 @@ import Translate, {translate} from '@docusaurus/Translate'; import Link from '@docusaurus/Link'; import {useBaseUrlUtils} from '@docusaurus/useBaseUrl'; import {usePluralForm} from '@docusaurus/theme-common'; +import {blogPostContainerID} from '@docusaurus/utils-common'; import MDXComponents from '@theme/MDXComponents'; import EditThisPage from '@theme/EditThisPage'; import type {Props} from '@theme/BlogPostItem'; @@ -102,7 +103,11 @@ function BlogPostItem(props: Props): JSX.Element { )} -
+
{children}
diff --git a/packages/docusaurus-types/src/index.d.ts b/packages/docusaurus-types/src/index.d.ts index d2fe18dab0..bb5d564a12 100644 --- a/packages/docusaurus-types/src/index.d.ts +++ b/packages/docusaurus-types/src/index.d.ts @@ -258,7 +258,7 @@ export interface Plugin { actions: PluginContentLoadedActions; }) => Promise; routesLoaded?: (routes: RouteConfig[]) => void; // TODO remove soon, deprecated (alpha-60) - postBuild?: (props: Props) => void; + postBuild?: (props: Props & {content: Content}) => Promise; postStart?: (props: Props) => void; // TODO refactor the configureWebpack API surface: use an object instead of multiple params (requires breaking change) configureWebpack?: ( diff --git a/packages/docusaurus-utils-common/src/index.ts b/packages/docusaurus-utils-common/src/index.ts index 204a13ebf5..6d7fb91b4f 100644 --- a/packages/docusaurus-utils-common/src/index.ts +++ b/packages/docusaurus-utils-common/src/index.ts @@ -5,5 +5,6 @@ * LICENSE file in the root directory of this source tree. */ +export const blogPostContainerID = 'post-content'; export {default as applyTrailingSlash} from './applyTrailingSlash'; export type {ApplyTrailingSlashParams} from './applyTrailingSlash'; diff --git a/packages/docusaurus-utils/src/__tests__/mdxUtils.test.ts b/packages/docusaurus-utils/src/__tests__/mdxUtils.test.ts deleted file mode 100644 index 15e63d1322..0000000000 --- a/packages/docusaurus-utils/src/__tests__/mdxUtils.test.ts +++ /dev/null @@ -1,133 +0,0 @@ -/** - * Copyright (c) Facebook, Inc. and its affiliates. - * - * This source code is licensed under the MIT license found in the - * LICENSE file in the root directory of this source tree. - */ - -import {mdxToHtml} from '../mdxUtils'; - -describe('mdxToHtml', () => { - test('work with simple markdown', () => { - const mdxString = ` -# title - -title text **bold** - -## subtitle - -subtitle text *italic* - -> Quote - - `; - - expect(mdxToHtml(mdxString)).toMatchInlineSnapshot( - `"

title

title text bold

subtitle

subtitle text italic

Quote

"`, - ); - }); - - test('work with MDX imports', () => { - const mdxString = ` -# title - -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; - -text - - `; - - expect(mdxToHtml(mdxString)).toMatchInlineSnapshot( - `"

title

text

"`, - ); - }); - - test('work with MDX exports', () => { - const mdxString = ` -# title - -export const someExport = 42 - -export const MyLocalComponent = () => "result" - -export const toc = [ - {id: "title",label: "title"} -] - -text - - - `; - - expect(mdxToHtml(mdxString)).toMatchInlineSnapshot( - `"

title

text

"`, - ); - }); - - test('work with MDX Tabs', () => { - const mdxString = ` -# title - -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; - - - - This is an apple 🍎 - - - This is an orange 🍊 - - - -text - - - `; - - // TODO this is not an ideal behavior! - // There is a warning "Component TabItem was not imported, exported, or provided by MDXProvider as global scope" - // Theme + MDX config should provide a list of React components to put in MDX scope - expect(mdxToHtml(mdxString)).toMatchInlineSnapshot( - `"

title

This is an apple 🍎
This is an orange 🍊

text

"`, - ); - }); - - test('work with MDX Tabs with ```mdx-code-block', () => { - const mdxString = ` -# title - -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; - -\`\`\`mdx-code-block - - - This is an apple 🍎 - - - This is an orange 🍊 - - -\`\`\` - -text - - `; - - // TODO bad behavior! - // ```mdx-code-block should be unwrapped and inner MDX content should be evaluated - expect(mdxToHtml(mdxString)).toMatchInlineSnapshot(` - "

title

<Tabs>
-        <TabItem value="apple" label="Apple">
-          This is an apple 🍎
-        </TabItem>
-        <TabItem value="orange" label="Orange">
-          This is an orange 🍊
-        </TabItem>
-      </Tabs>
-

text

" - `); - }); -}); diff --git a/packages/docusaurus-utils/src/index.ts b/packages/docusaurus-utils/src/index.ts index e0ca7f81ec..bb0cffa266 100644 --- a/packages/docusaurus-utils/src/index.ts +++ b/packages/docusaurus-utils/src/index.ts @@ -23,7 +23,6 @@ import {simpleHash, docuHash} from './hashUtils'; import {DEFAULT_PLUGIN_ID} from './constants'; export * from './constants'; -export * from './mdxUtils'; export * from './urlUtils'; export * from './tags'; export * from './markdownParser'; @@ -210,6 +209,39 @@ export function getPluginI18nPath({ ); } +/** + * @param permalink The URL that the HTML file corresponds to, without base URL + * @param outDir Full path to the output directory + * @param trailingSlash The site config option. If provided, only one path will be read. + * @returns This returns a buffer, which you have to decode string yourself if + * needed. (Not always necessary since the output isn't for human consumption + * anyways, and most HTML manipulation libs accept buffers) + */ +export async function readOutputHTMLFile( + permalink: string, + outDir: string, + trailingSlash: boolean | undefined, +): Promise { + const withTrailingSlashPath = path.join(outDir, permalink, 'index.html'); + const withoutTrailingSlashPath = path.join(outDir, `${permalink}.html`); + if (trailingSlash) { + return fs.readFile(withTrailingSlashPath); + } else if (trailingSlash === false) { + return fs.readFile(withoutTrailingSlashPath); + } else { + const HTMLPath = await findAsyncSequential( + [withTrailingSlashPath, withoutTrailingSlashPath], + fs.pathExists, + ); + if (!HTMLPath) { + throw new Error( + `Expected output HTML file to be found at ${withTrailingSlashPath}`, + ); + } + return fs.readFile(HTMLPath); + } +} + export async function mapAsyncSequential( array: T[], action: (t: T) => Promise, diff --git a/packages/docusaurus-utils/src/mdxUtils.ts b/packages/docusaurus-utils/src/mdxUtils.ts deleted file mode 100644 index a8028896fc..0000000000 --- a/packages/docusaurus-utils/src/mdxUtils.ts +++ /dev/null @@ -1,32 +0,0 @@ -/** - * Copyright (c) Facebook, Inc. and its affiliates. - * - * This source code is licensed under the MIT license found in the - * LICENSE file in the root directory of this source tree. - */ - -import React from 'react'; -import ReactDOMServer from 'react-dom/server'; -import MDX from '@mdx-js/runtime'; -import removeImports from 'remark-mdx-remove-imports'; -import removeExports from 'remark-mdx-remove-exports'; - -/** - * Transform mdx text to plain html text - * Initially created to convert MDX blog posts to HTML for the RSS feed - * without import/export nodes - * - * TODO not ideal implementation, won't work well with MDX elements! - * TODO theme+global site config should be able to declare MDX comps in scope for rendering the RSS feeds - * see also https://github.com/facebook/docusaurus/issues/4625 - */ -export function mdxToHtml( - mdxStr: string, - // TODO allow providing components/scope here, see https://github.com/mdx-js/mdx/tree/v1.6.13/packages/runtime -): string { - return ReactDOMServer.renderToString( - React.createElement(MDX, {remarkPlugins: [removeImports, removeExports]}, [ - mdxStr, - ]), - ); -} diff --git a/packages/docusaurus/src/commands/build.ts b/packages/docusaurus/src/commands/build.ts index cdb99a2cd8..2f7d64c7d7 100644 --- a/packages/docusaurus/src/commands/build.ts +++ b/packages/docusaurus/src/commands/build.ts @@ -176,7 +176,7 @@ async function buildLocale({ if (configureWebpack) { clientConfig = applyConfigureWebpack( - configureWebpack.bind(plugin), // The plugin lifecycle may reference `this`. // TODO remove this implicit api: inject in callback instead + configureWebpack.bind(plugin), // The plugin lifecycle may reference `this`. clientConfig, false, props.siteConfig.webpack?.jsLoader, @@ -184,7 +184,7 @@ async function buildLocale({ ); serverConfig = applyConfigureWebpack( - configureWebpack.bind(plugin), // The plugin lifecycle may reference `this`. // TODO remove this implicit api: inject in callback instead + configureWebpack.bind(plugin), // The plugin lifecycle may reference `this`. serverConfig, true, props.siteConfig.webpack?.jsLoader, @@ -220,7 +220,8 @@ async function buildLocale({ if (!plugin.postBuild) { return; } - await plugin.postBuild(props); + // The plugin may reference `this`. We manually bind it again to prevent any bugs. + await plugin.postBuild({...props, content: plugin.content}); }), ); diff --git a/website/docs/api/plugin-methods/lifecycle-apis.md b/website/docs/api/plugin-methods/lifecycle-apis.md index ea06de717d..e4cb3d211e 100644 --- a/website/docs/api/plugin-methods/lifecycle-apis.md +++ b/website/docs/api/plugin-methods/lifecycle-apis.md @@ -281,6 +281,7 @@ interface Props { postBodyTags: string; routesPaths: string[]; plugins: Plugin[]; + content: Content; } ``` diff --git a/yarn.lock b/yarn.lock index d0a9d8ebed..f35378b92a 100644 --- a/yarn.lock +++ b/yarn.lock @@ -6047,6 +6047,17 @@ chardet@^0.7.0: resolved "https://registry.yarnpkg.com/chardet/-/chardet-0.7.0.tgz#90094849f0937f2eedc2425d0d28a9e5f0cbad9e" integrity sha512-mT8iDcrh03qDGRRmoA2hmBJnxpllMR+0/0qlzjqZES6NdiWDcZkCNAk4rPFZ9Q85r27unkiNNg8ZOiwZXBHwcA== +cheerio-select@^1.5.0: + version "1.5.0" + resolved "https://registry.yarnpkg.com/cheerio-select/-/cheerio-select-1.5.0.tgz#faf3daeb31b17c5e1a9dabcee288aaf8aafa5823" + integrity sha512-qocaHPv5ypefh6YNxvnbABM07KMxExbtbfuJoIie3iZXX1ERwYmJcIiRrr9H05ucQP1k28dav8rpdDgjQd8drg== + dependencies: + css-select "^4.1.3" + css-what "^5.0.1" + domelementtype "^2.2.0" + domhandler "^4.2.0" + domutils "^2.7.0" + cheerio@^0.22.0: version "0.22.0" resolved "https://registry.yarnpkg.com/cheerio/-/cheerio-0.22.0.tgz#a9baa860a3f9b595a6b81b1a86873121ed3a269e" @@ -6069,6 +6080,19 @@ cheerio@^0.22.0: lodash.reject "^4.4.0" lodash.some "^4.4.0" +cheerio@^1.0.0-rc.10: + version "1.0.0-rc.10" + resolved "https://registry.yarnpkg.com/cheerio/-/cheerio-1.0.0-rc.10.tgz#2ba3dcdfcc26e7956fc1f440e61d51c643379f3e" + integrity sha512-g0J0q/O6mW8z5zxQ3A8E8J1hUgp4SMOvEoW/x84OwyHKe/Zccz83PVT4y5Crcr530FV6NgmKI1qvGTKVl9XXVw== + dependencies: + cheerio-select "^1.5.0" + dom-serializer "^1.3.2" + domhandler "^4.2.0" + htmlparser2 "^6.1.0" + parse5 "^6.0.1" + parse5-htmlparser2-tree-adapter "^6.0.1" + tslib "^2.2.0" + chokidar@^3.0.2, chokidar@^3.4.0, chokidar@^3.4.2, chokidar@^3.5.2: version "3.5.2" resolved "https://registry.yarnpkg.com/chokidar/-/chokidar-3.5.2.tgz#dba3976fcadb016f66fd365021d91600d01c1e75" @@ -7117,7 +7141,7 @@ css-what@2.1: resolved "https://registry.yarnpkg.com/css-what/-/css-what-2.1.3.tgz#a6d7604573365fe74686c3f311c56513d88285f2" integrity sha512-a+EPoD+uZiNfh+5fxw2nO9QwFa6nJe2Or35fGY6Ipw1R3R4AGz1d1TEZrCegvw2YTmZ0jXirGYlzxxpYSHwpEg== -css-what@^5.1.0: +css-what@^5.0.1, css-what@^5.1.0: version "5.1.0" resolved "https://registry.yarnpkg.com/css-what/-/css-what-5.1.0.tgz#3f7b707aadf633baf62c2ceb8579b545bb40f7fe" integrity sha512-arSMRWIIFY0hV8pIxZMEfmMI47Wj3R/aWpZDDxWYCPEiOMv6tfOrnpDtgxBYPEQD4V0Y/958+1TdC3iWTFcUPw== @@ -7757,7 +7781,7 @@ dom-serializer@0: domelementtype "^2.0.1" entities "^2.0.0" -dom-serializer@^1.0.1: +dom-serializer@^1.0.1, dom-serializer@^1.3.2: version "1.3.2" resolved "https://registry.yarnpkg.com/dom-serializer/-/dom-serializer-1.3.2.tgz#6206437d32ceefaec7161803230c7a20bc1b4d91" integrity sha512-5c54Bk5Dw4qAxNOI1pFEizPSjVsx5+bpJKmL2kPn8JhBUq2q09tTCa3mjijun2NfK78NMouDYNMBkOrPZiS+ig== @@ -7826,7 +7850,7 @@ domutils@^1.5.1: dom-serializer "0" domelementtype "1" -domutils@^2.5.2, domutils@^2.8.0: +domutils@^2.5.2, domutils@^2.7.0, domutils@^2.8.0: version "2.8.0" resolved "https://registry.yarnpkg.com/domutils/-/domutils-2.8.0.tgz#4437def5db6e2d1f5d6ee859bd95ca7d02048135" integrity sha512-w96Cjofp72M5IIhpjgobBimYEfoPjx1Vx0BSX9P30WBdZW2WIKU0T1Bd0kz2eNZ9ikjKgHbEyKx8BB6H1L3h3A== @@ -14544,7 +14568,7 @@ parse-url@^6.0.0: parse-path "^4.0.0" protocols "^1.4.0" -parse5-htmlparser2-tree-adapter@^6.0.0: +parse5-htmlparser2-tree-adapter@^6.0.0, parse5-htmlparser2-tree-adapter@^6.0.1: version "6.0.1" resolved "https://registry.yarnpkg.com/parse5-htmlparser2-tree-adapter/-/parse5-htmlparser2-tree-adapter-6.0.1.tgz#2cdf9ad823321140370d4dbf5d3e92c7c8ddc6e6" integrity sha512-qPuWvbLgvDGilKc5BoicRovlT4MtYT6JfJyBOMDsKoiT+GiuP5qyrPCnR9HcPECIJJmZh5jRndyNThnhhb/vlA== @@ -18450,7 +18474,7 @@ tslib@^1.8.1, tslib@^1.9.0: resolved "https://registry.yarnpkg.com/tslib/-/tslib-1.14.1.tgz#cf2d38bdc34a134bcaf1091c41f6619e2f672d00" integrity sha512-Xni35NKzjgMrwevysHTCArtLDpPvye8zV/0E4EyYn43P7/7qvQwPh9BGkHewbMulVntbigmcT7rdX3BNo9wRJg== -tslib@^2.0.1, tslib@^2.0.3, tslib@^2.1.0, tslib@^2.3.1: +tslib@^2.0.1, tslib@^2.0.3, tslib@^2.1.0, tslib@^2.2.0, tslib@^2.3.1: version "2.3.1" resolved "https://registry.yarnpkg.com/tslib/-/tslib-2.3.1.tgz#e8a335add5ceae51aa261d32a490158ef042ef01" integrity sha512-77EbyPPpMz+FRFRuAFlWMtmgUWGe9UOG2Z25NqCwiIjRhOf5iKGuzSe5P2w1laq+FkRy4p+PCuVkJSGkzTEKVw== From 24a895fbc56793331a1956c2b254048456ad527b Mon Sep 17 00:00:00 2001 From: Joshua Chen Date: Thu, 27 Jan 2022 00:58:52 +0800 Subject: [PATCH 002/352] feat(content-docs): expose isCategoryIndex matcher to customize conventions (#6451) Co-authored-by: sebastienlorber --- .../__snapshots__/index.test.ts.snap | 1 + .../src/__tests__/docs.test.ts | 114 ++++++++------ .../src/docs.ts | 65 ++++++-- .../src/plugin-content-docs.d.ts | 9 ++ .../src/sidebars/__tests__/generator.test.ts | 140 ++++++++++++++++-- .../src/sidebars/__tests__/processor.test.ts | 4 + .../src/sidebars/generator.ts | 14 +- .../src/sidebars/processor.ts | 2 + .../src/sidebars/types.ts | 2 + .../src/slug.ts | 9 +- .../src/types.ts | 4 +- .../custom-index-convention/intro.md | 3 + .../custom-index-convention/sample-doc.md | 3 + website/_dogfooding/dogfooding.config.js | 14 ++ .../docs/api/plugins/plugin-content-docs.md | 20 ++- .../docs/guides/docs/sidebar/autogenerated.md | 97 ++++++++++++ 16 files changed, 408 insertions(+), 93 deletions(-) create mode 100644 website/_dogfooding/_docs tests/tests/category-links/custom-index-convention/intro.md create mode 100644 website/_dogfooding/_docs tests/tests/category-links/custom-index-convention/sample-doc.md diff --git a/packages/docusaurus-plugin-content-docs/src/__tests__/__snapshots__/index.test.ts.snap b/packages/docusaurus-plugin-content-docs/src/__tests__/__snapshots__/index.test.ts.snap index 35d26aa8a5..0d601a5d24 100644 --- a/packages/docusaurus-plugin-content-docs/src/__tests__/__snapshots__/index.test.ts.snap +++ b/packages/docusaurus-plugin-content-docs/src/__tests__/__snapshots__/index.test.ts.snap @@ -1491,6 +1491,7 @@ Object { "unversionedId": "installation", }, ], + "isCategoryIndex": [Function], "item": Object { "dirName": ".", "type": "autogenerated", diff --git a/packages/docusaurus-plugin-content-docs/src/__tests__/docs.test.ts b/packages/docusaurus-plugin-content-docs/src/__tests__/docs.test.ts index a5cd7c5c31..f00525b88e 100644 --- a/packages/docusaurus-plugin-content-docs/src/__tests__/docs.test.ts +++ b/packages/docusaurus-plugin-content-docs/src/__tests__/docs.test.ts @@ -12,7 +12,7 @@ import { readVersionDocs, readDocFile, addDocNavigation, - isConventionalDocIndex, + isCategoryIndex, } from '../docs'; import {loadSidebars} from '../sidebars'; import {readVersionsMetadata} from '../versions'; @@ -938,108 +938,124 @@ describe('versioned site', () => { describe('isConventionalDocIndex', () => { test('supports readme', () => { expect( - isConventionalDocIndex({ - sourceDirName: 'doesNotMatter', - source: 'readme.md', + isCategoryIndex({ + fileName: 'readme', + directories: ['doesNotMatter'], + extension: '.md', }), ).toEqual(true); expect( - isConventionalDocIndex({ - sourceDirName: 'doesNotMatter', - source: 'readme.mdx', + isCategoryIndex({ + fileName: 'readme', + directories: ['doesNotMatter'], + extension: '.mdx', }), ).toEqual(true); expect( - isConventionalDocIndex({ - sourceDirName: 'doesNotMatter', - source: 'README.md', + isCategoryIndex({ + fileName: 'README', + directories: ['doesNotMatter'], + extension: '.md', }), ).toEqual(true); expect( - isConventionalDocIndex({ - sourceDirName: 'doesNotMatter', - source: 'parent/ReAdMe', + isCategoryIndex({ + fileName: 'ReAdMe', + directories: ['doesNotMatter'], + extension: '', }), ).toEqual(true); }); test('supports index', () => { expect( - isConventionalDocIndex({ - sourceDirName: 'doesNotMatter', - source: 'index.md', + isCategoryIndex({ + fileName: 'index', + directories: ['doesNotMatter'], + extension: '.md', }), ).toEqual(true); expect( - isConventionalDocIndex({ - sourceDirName: 'doesNotMatter', - source: 'index.mdx', + isCategoryIndex({ + fileName: 'index', + directories: ['doesNotMatter'], + extension: '.mdx', }), ).toEqual(true); expect( - isConventionalDocIndex({ - sourceDirName: 'doesNotMatter', - source: 'INDEX.md', + isCategoryIndex({ + fileName: 'INDEX', + directories: ['doesNotMatter'], + extension: '.md', }), ).toEqual(true); expect( - isConventionalDocIndex({ - sourceDirName: 'doesNotMatter', - source: 'parent/InDeX', + isCategoryIndex({ + fileName: 'InDeX', + directories: ['doesNotMatter'], + extension: '', }), ).toEqual(true); }); test('supports /.md', () => { expect( - isConventionalDocIndex({ - sourceDirName: 'someCategory', - source: 'someCategory', + isCategoryIndex({ + fileName: 'someCategory', + directories: ['someCategory', 'doesNotMatter'], + extension: '', }), ).toEqual(true); expect( - isConventionalDocIndex({ - sourceDirName: 'someCategory', - source: 'someCategory.md', + isCategoryIndex({ + fileName: 'someCategory', + directories: ['someCategory'], + extension: '.md', }), ).toEqual(true); expect( - isConventionalDocIndex({ - sourceDirName: 'someCategory', - source: 'someCategory.mdx', + isCategoryIndex({ + fileName: 'someCategory', + directories: ['someCategory'], + extension: '.mdx', }), ).toEqual(true); expect( - isConventionalDocIndex({ - sourceDirName: 'some_category', - source: 'SOME_CATEGORY.md', + isCategoryIndex({ + fileName: 'SOME_CATEGORY', + directories: ['some_category'], + extension: '.md', }), ).toEqual(true); expect( - isConventionalDocIndex({ - sourceDirName: 'some_category', - source: 'parent/some_category', + isCategoryIndex({ + fileName: 'some_category', + directories: ['some_category'], + extension: '', }), ).toEqual(true); }); test('reject other cases', () => { expect( - isConventionalDocIndex({ - sourceDirName: 'someCategory', - source: 'some_Category', + isCategoryIndex({ + fileName: 'some_Category', + directories: ['someCategory'], + extension: '', }), ).toEqual(false); expect( - isConventionalDocIndex({ - sourceDirName: 'doesNotMatter', - source: 'read_me', + isCategoryIndex({ + fileName: 'read_me', + directories: ['doesNotMatter'], + extension: '', }), ).toEqual(false); expect( - isConventionalDocIndex({ - sourceDirName: 'doesNotMatter', - source: 'the index', + isCategoryIndex({ + fileName: 'the index', + directories: ['doesNotMatter'], + extension: '', }), ).toEqual(false); }); diff --git a/packages/docusaurus-plugin-content-docs/src/docs.ts b/packages/docusaurus-plugin-content-docs/src/docs.ts index 9925156250..9002479b9a 100644 --- a/packages/docusaurus-plugin-content-docs/src/docs.ts +++ b/packages/docusaurus-plugin-content-docs/src/docs.ts @@ -8,7 +8,7 @@ import path from 'path'; import fs from 'fs-extra'; import logger from '@docusaurus/logger'; -import {keyBy, last} from 'lodash'; +import {keyBy} from 'lodash'; import { aliasedSitePath, getEditUrl, @@ -41,6 +41,8 @@ import {toDocNavigationLink, toNavigationLink} from './sidebars/utils'; import type { MetadataOptions, PluginOptions, + CategoryIndexMatcher, + CategoryIndexMatcherParam, } from '@docusaurus/plugin-content-docs'; type LastUpdateOptions = Pick< @@ -367,31 +369,62 @@ export function getMainDocId({ return getMainDoc().unversionedId; } -function getLastPathSegment(str: string): string { - return last(str.split('/'))!; -} - // By convention, Docusaurus considers some docs are "indexes": // - index.md // - readme.md // - /.md // +// This function is the default implementation of this convention +// // Those index docs produce a different behavior // - Slugs do not end with a weird "/index" suffix // - Auto-generated sidebar categories link to them as intro -export function isConventionalDocIndex(doc: { - source: DocMetadataBase['slug']; - sourceDirName: DocMetadataBase['sourceDirName']; -}): boolean { - // "@site/docs/folder/subFolder/subSubFolder/myDoc.md" => "myDoc" - const docName = path.parse(doc.source).name; +export const isCategoryIndex: CategoryIndexMatcher = ({ + fileName, + directories, +}): boolean => { + const eligibleDocIndexNames = [ + 'index', + 'readme', + directories[0]?.toLowerCase(), + ]; + return eligibleDocIndexNames.includes(fileName.toLowerCase()); +}; - // "folder/subFolder/subSubFolder" => "subSubFolder" - const lastDirName = getLastPathSegment(doc.sourceDirName); +export function toCategoryIndexMatcherParam({ + source, + sourceDirName, +}: Pick< + DocMetadataBase, + 'source' | 'sourceDirName' +>): CategoryIndexMatcherParam { + // source + sourceDirName are always posix-style + return { + fileName: path.posix.parse(source).name, + extension: path.posix.parse(source).ext, + directories: sourceDirName.split(path.posix.sep).reverse(), + }; +} - const eligibleDocIndexNames = ['index', 'readme', lastDirName.toLowerCase()]; - - return eligibleDocIndexNames.includes(docName.toLowerCase()); +/** + * guides/sidebar/autogenerated.md -> 'autogenerated', '.md', ['sidebar', 'guides'] + */ +export function splitPath(str: string): { + /** + * The list of directories, from lowest level to highest. + * If there's no dir name, directories is ['.'] + */ + directories: string[]; + /** The file name, without extension */ + fileName: string; + /** The extension, with a leading dot */ + extension: string; +} { + return { + fileName: path.parse(str).name, + extension: path.parse(str).ext, + directories: path.dirname(str).split(path.sep).reverse(), + }; } // Return both doc ids diff --git a/packages/docusaurus-plugin-content-docs/src/plugin-content-docs.d.ts b/packages/docusaurus-plugin-content-docs/src/plugin-content-docs.d.ts index 130de3b2c9..59f54a69c7 100644 --- a/packages/docusaurus-plugin-content-docs/src/plugin-content-docs.d.ts +++ b/packages/docusaurus-plugin-content-docs/src/plugin-content-docs.d.ts @@ -13,6 +13,15 @@ declare module '@docusaurus/plugin-content-docs' { numberPrefix?: number; }; + export type CategoryIndexMatcherParam = { + fileName: string; + directories: string[]; + extension: string; + }; + export type CategoryIndexMatcher = ( + param: CategoryIndexMatcherParam, + ) => boolean; + export type EditUrlFunction = (editUrlParams: { version: string; versionDocsDirPath: string; diff --git a/packages/docusaurus-plugin-content-docs/src/sidebars/__tests__/generator.test.ts b/packages/docusaurus-plugin-content-docs/src/sidebars/__tests__/generator.test.ts index defbe97a2c..67e7073294 100644 --- a/packages/docusaurus-plugin-content-docs/src/sidebars/__tests__/generator.test.ts +++ b/packages/docusaurus-plugin-content-docs/src/sidebars/__tests__/generator.test.ts @@ -12,6 +12,7 @@ import { import type {Sidebar, SidebarItemsGenerator} from '../types'; import fs from 'fs-extra'; import {DefaultNumberPrefixParser} from '../../numberPrefix'; +import {isCategoryIndex} from '../../docs'; describe('DefaultSidebarItemsGenerator', () => { function testDefaultSidebarItemsGenerator( @@ -19,6 +20,7 @@ describe('DefaultSidebarItemsGenerator', () => { ) { return DefaultSidebarItemsGenerator({ numberPrefixParser: DefaultNumberPrefixParser, + isCategoryIndex, item: { type: 'autogenerated', dirName: '.', @@ -146,6 +148,7 @@ describe('DefaultSidebarItemsGenerator', () => { const sidebarSlice = await DefaultSidebarItemsGenerator({ numberPrefixParser: DefaultNumberPrefixParser, + isCategoryIndex, item: { type: 'autogenerated', dirName: '.', @@ -157,48 +160,48 @@ describe('DefaultSidebarItemsGenerator', () => { docs: [ { id: 'intro', - source: 'intro.md', + source: '@site/docs/intro.md', sourceDirName: '.', sidebarPosition: 1, frontMatter: {}, }, { id: 'tutorials-index', - source: 'index.md', + source: '@site/docs/01-Tutorials/index.md', sourceDirName: '01-Tutorials', sidebarPosition: 2, frontMatter: {}, }, { id: 'tutorial2', - source: 'tutorial2.md', + source: '@site/docs/01-Tutorials/tutorial2.md', sourceDirName: '01-Tutorials', sidebarPosition: 2, frontMatter: {}, }, { id: 'tutorial1', - source: 'tutorial1.md', + source: '@site/docs/01-Tutorials/tutorial1.md', sourceDirName: '01-Tutorials', sidebarPosition: 1, frontMatter: {}, }, { id: 'guides-index', - source: '02-Guides.md', // TODO should we allow to just use "Guides.md" to have an index? + source: '@site/docs/02-Guides/02-Guides.md', // TODO should we allow to just use "Guides.md" to have an index? sourceDirName: '02-Guides', frontMatter: {}, }, { id: 'guide2', - source: 'guide2.md', + source: '@site/docs/02-Guides/guide2.md', sourceDirName: '02-Guides', sidebarPosition: 2, frontMatter: {}, }, { id: 'guide1', - source: 'guide1.md', + source: '@site/docs/02-Guides/guide1.md', sourceDirName: '02-Guides', sidebarPosition: 1, frontMatter: { @@ -207,14 +210,14 @@ describe('DefaultSidebarItemsGenerator', () => { }, { id: 'nested-guide', - source: 'nested-guide.md', + source: '@site/docs/02-Guides/01-SubGuides/nested-guide.md', sourceDirName: '02-Guides/01-SubGuides', sidebarPosition: undefined, frontMatter: {}, }, { id: 'end', - source: 'end.md', + source: '@site/docs/end.md', sourceDirName: '.', sidebarPosition: 3, frontMatter: {}, @@ -296,6 +299,7 @@ describe('DefaultSidebarItemsGenerator', () => { const sidebarSlice = await DefaultSidebarItemsGenerator({ numberPrefixParser: DefaultNumberPrefixParser, + isCategoryIndex, item: { type: 'autogenerated', dirName: 'subfolder/subsubfolder', @@ -427,19 +431,19 @@ describe('DefaultSidebarItemsGenerator', () => { docs: [ { id: 'parent/doc1', - source: 'index.md', + source: '@site/docs/Category/index.md', sourceDirName: 'Category', frontMatter: {}, }, { id: 'parent/doc2', - source: 'index.md', + source: '@site/docs/Category/index.md', sourceDirName: 'Category', frontMatter: {}, }, { id: 'parent/doc3', - source: 'doc3.md', + source: '@site/docs/Category/doc3.md', sourceDirName: 'Category', frontMatter: {}, }, @@ -473,4 +477,116 @@ describe('DefaultSidebarItemsGenerator', () => { }, ] as Sidebar); }); + + test('respects custom isCategoryIndex', async () => { + const sidebarSlice = await DefaultSidebarItemsGenerator({ + numberPrefixParser: DefaultNumberPrefixParser, + isCategoryIndex({fileName, directories}) { + return ( + fileName.replace( + `${DefaultNumberPrefixParser( + directories[0], + ).filename.toLowerCase()}-`, + '', + ) === 'index' + ); + }, + item: { + type: 'autogenerated', + dirName: '.', + }, + version: { + versionName: 'current', + contentPath: '', + }, + docs: [ + { + id: 'intro', + source: '@site/docs/intro.md', + sourceDirName: '.', + sidebarPosition: 1, + frontMatter: {}, + }, + { + id: 'tutorials-index', + source: '@site/docs/01-Tutorials/tutorials-index.md', + sourceDirName: '01-Tutorials', + sidebarPosition: 2, + frontMatter: {}, + }, + { + id: 'tutorial2', + source: '@site/docs/01-Tutorials/tutorial2.md', + sourceDirName: '01-Tutorials', + sidebarPosition: 2, + frontMatter: {}, + }, + { + id: 'tutorial1', + source: '@site/docs/01-Tutorials/tutorial1.md', + sourceDirName: '01-Tutorials', + sidebarPosition: 1, + frontMatter: {}, + }, + { + id: 'not-guides-index', + source: '@site/docs/02-Guides/README.md', + sourceDirName: '02-Guides', + frontMatter: {}, + }, + { + id: 'guide2', + source: '@site/docs/02-Guides/guide2.md', + sourceDirName: '02-Guides', + sidebarPosition: 2, + frontMatter: {}, + }, + { + id: 'guide1', + source: '@site/docs/02-Guides/guide1.md', + sourceDirName: '02-Guides', + sidebarPosition: 1, + frontMatter: { + sidebar_class_name: 'foo', + }, + }, + ], + options: { + sidebarCollapsed: true, + sidebarCollapsible: true, + }, + }); + + expect(sidebarSlice).toEqual([ + {type: 'doc', id: 'intro'}, + { + type: 'category', + label: 'Tutorials', + collapsed: true, + collapsible: true, + link: { + type: 'doc', + id: 'tutorials-index', + }, + items: [ + {type: 'doc', id: 'tutorial1'}, + {type: 'doc', id: 'tutorial2'}, + ], + }, + { + type: 'category', + label: 'Guides', + collapsed: true, + collapsible: true, + items: [ + {type: 'doc', id: 'guide1', className: 'foo'}, + {type: 'doc', id: 'guide2'}, + { + type: 'doc', + id: 'not-guides-index', + }, + ], + }, + ] as Sidebar); + }); }); diff --git a/packages/docusaurus-plugin-content-docs/src/sidebars/__tests__/processor.test.ts b/packages/docusaurus-plugin-content-docs/src/sidebars/__tests__/processor.test.ts index b7caeae4de..3341d8c399 100644 --- a/packages/docusaurus-plugin-content-docs/src/sidebars/__tests__/processor.test.ts +++ b/packages/docusaurus-plugin-content-docs/src/sidebars/__tests__/processor.test.ts @@ -16,6 +16,7 @@ import {DefaultSidebarItemsGenerator} from '../generator'; import {createSlugger} from '@docusaurus/utils'; import type {VersionMetadata} from '../../types'; import {DefaultNumberPrefixParser} from '../../numberPrefix'; +import {isCategoryIndex} from '../../docs'; describe('processSidebars', () => { function createStaticSidebarItemGenerator( @@ -137,6 +138,7 @@ describe('processSidebars', () => { versionName: version.versionName, }, numberPrefixParser: DefaultNumberPrefixParser, + isCategoryIndex, options: params.sidebarOptions, }); expect(StaticSidebarItemsGenerator).toHaveBeenCalledWith({ @@ -147,6 +149,7 @@ describe('processSidebars', () => { versionName: version.versionName, }, numberPrefixParser: DefaultNumberPrefixParser, + isCategoryIndex, options: params.sidebarOptions, }); expect(StaticSidebarItemsGenerator).toHaveBeenCalledWith({ @@ -157,6 +160,7 @@ describe('processSidebars', () => { versionName: version.versionName, }, numberPrefixParser: DefaultNumberPrefixParser, + isCategoryIndex, options: params.sidebarOptions, }); diff --git a/packages/docusaurus-plugin-content-docs/src/sidebars/generator.ts b/packages/docusaurus-plugin-content-docs/src/sidebars/generator.ts index acd534a993..0807112cba 100644 --- a/packages/docusaurus-plugin-content-docs/src/sidebars/generator.ts +++ b/packages/docusaurus-plugin-content-docs/src/sidebars/generator.ts @@ -25,7 +25,7 @@ import path from 'path'; import fs from 'fs-extra'; import Yaml from 'js-yaml'; import {validateCategoryMetadataFile} from './validation'; -import {createDocsByIdIndex, isConventionalDocIndex} from '../docs'; +import {createDocsByIdIndex, toCategoryIndexMatcherParam} from '../docs'; const BreadcrumbSeparator = '/'; // To avoid possible name clashes with a folder of the same name as the ID @@ -94,6 +94,7 @@ async function readCategoryMetadataFile( // Comment for this feature: https://github.com/facebook/docusaurus/issues/3464#issuecomment-818670449 export const DefaultSidebarItemsGenerator: SidebarItemsGenerator = async ({ numberPrefixParser, + isCategoryIndex, docs: allDocs, options, item: {dirName: autogenDir}, @@ -210,10 +211,13 @@ export const DefaultSidebarItemsGenerator: SidebarItemsGenerator = async ({ } function findConventionalCategoryDocLink(): SidebarItemDoc | undefined { - return allItems.find( - (item) => - item.type === 'doc' && isConventionalDocIndex(getDoc(item.id)), - ) as SidebarItemDoc | undefined; + return allItems.find((item) => { + if (item.type !== 'doc') { + return false; + } + const doc = getDoc(item.id); + return isCategoryIndex(toCategoryIndexMatcherParam(doc)); + }) as SidebarItemDoc | undefined; } function getCategoryLinkedDocId(): string | undefined { diff --git a/packages/docusaurus-plugin-content-docs/src/sidebars/processor.ts b/packages/docusaurus-plugin-content-docs/src/sidebars/processor.ts index e1ec68fbc2..0ef94ba25f 100644 --- a/packages/docusaurus-plugin-content-docs/src/sidebars/processor.ts +++ b/packages/docusaurus-plugin-content-docs/src/sidebars/processor.ts @@ -25,6 +25,7 @@ import {DefaultSidebarItemsGenerator} from './generator'; import {mapValues, memoize, pick} from 'lodash'; import combinePromises from 'combine-promises'; import {normalizeItem} from './normalization'; +import {isCategoryIndex} from '../docs'; import type {Slugger} from '@docusaurus/utils'; import type { NumberPrefixParser, @@ -95,6 +96,7 @@ async function processSidebar( item, numberPrefixParser, defaultSidebarItemsGenerator: DefaultSidebarItemsGenerator, + isCategoryIndex, ...getSidebarItemsGeneratorDocsAndVersion(), options: sidebarOptions, }); diff --git a/packages/docusaurus-plugin-content-docs/src/sidebars/types.ts b/packages/docusaurus-plugin-content-docs/src/sidebars/types.ts index 8d6c61ecf3..56a4be084a 100644 --- a/packages/docusaurus-plugin-content-docs/src/sidebars/types.ts +++ b/packages/docusaurus-plugin-content-docs/src/sidebars/types.ts @@ -10,6 +10,7 @@ import type {DocMetadataBase, VersionMetadata} from '../types'; import type { NumberPrefixParser, SidebarOptions, + CategoryIndexMatcher, } from '@docusaurus/plugin-content-docs'; // Makes all properties visible when hovering over the type @@ -195,6 +196,7 @@ export type SidebarItemsGeneratorArgs = { version: SidebarItemsGeneratorVersion; docs: SidebarItemsGeneratorDoc[]; numberPrefixParser: NumberPrefixParser; + isCategoryIndex: CategoryIndexMatcher; options: SidebarOptions; }; export type SidebarItemsGenerator = ( diff --git a/packages/docusaurus-plugin-content-docs/src/slug.ts b/packages/docusaurus-plugin-content-docs/src/slug.ts index 6d84e9b176..e5168563c2 100644 --- a/packages/docusaurus-plugin-content-docs/src/slug.ts +++ b/packages/docusaurus-plugin-content-docs/src/slug.ts @@ -16,7 +16,7 @@ import { stripPathNumberPrefixes, } from './numberPrefix'; import type {DocMetadataBase} from './types'; -import {isConventionalDocIndex} from './docs'; +import {isCategoryIndex, toCategoryIndexMatcherParam} from './docs'; import type {NumberPrefixParser} from '@docusaurus/plugin-content-docs'; export default function getSlug({ @@ -29,7 +29,7 @@ export default function getSlug({ }: { baseID: string; frontMatterSlug?: string; - source: DocMetadataBase['slug']; + source: DocMetadataBase['source']; sourceDirName: DocMetadataBase['sourceDirName']; stripDirNumberPrefixes?: boolean; numberPrefixParser?: NumberPrefixParser; @@ -50,7 +50,10 @@ export default function getSlug({ return frontMatterSlug; } else { const dirNameSlug = getDirNameSlug(); - if (!frontMatterSlug && isConventionalDocIndex({source, sourceDirName})) { + if ( + !frontMatterSlug && + isCategoryIndex(toCategoryIndexMatcherParam({source, sourceDirName})) + ) { return dirNameSlug; } const baseSlug = frontMatterSlug || baseID; diff --git a/packages/docusaurus-plugin-content-docs/src/types.ts b/packages/docusaurus-plugin-content-docs/src/types.ts index 4604ca1d65..b32575772f 100644 --- a/packages/docusaurus-plugin-content-docs/src/types.ts +++ b/packages/docusaurus-plugin-content-docs/src/types.ts @@ -82,8 +82,8 @@ export type DocMetadataBase = LastUpdateData & { version: string; title: string; description: string; - source: string; // @site aliased source => "@site/docs/folder/subFolder/subSubFolder/myDoc.md" - sourceDirName: string; // relative to the versioned docs folder (can be ".") => "folder/subFolder/subSubFolder" + source: string; // @site aliased posix source => "@site/docs/folder/subFolder/subSubFolder/myDoc.md" + sourceDirName: string; // posix path relative to the versioned docs folder (can be ".") => "folder/subFolder/subSubFolder" slug: string; permalink: string; sidebarPosition?: number; diff --git a/website/_dogfooding/_docs tests/tests/category-links/custom-index-convention/intro.md b/website/_dogfooding/_docs tests/tests/category-links/custom-index-convention/intro.md new file mode 100644 index 0000000000..dd647aa825 --- /dev/null +++ b/website/_dogfooding/_docs tests/tests/category-links/custom-index-convention/intro.md @@ -0,0 +1,3 @@ +# Introduction + +This file is called `intro.md`. Typically, it won't be selected by the convention; however, it is in this case, because we have used a custom one. diff --git a/website/_dogfooding/_docs tests/tests/category-links/custom-index-convention/sample-doc.md b/website/_dogfooding/_docs tests/tests/category-links/custom-index-convention/sample-doc.md new file mode 100644 index 0000000000..15fb7937c3 --- /dev/null +++ b/website/_dogfooding/_docs tests/tests/category-links/custom-index-convention/sample-doc.md @@ -0,0 +1,3 @@ +# Sample doc + +Lorem Ipsum diff --git a/website/_dogfooding/dogfooding.config.js b/website/_dogfooding/dogfooding.config.js index 0179dc3599..3d087da411 100644 --- a/website/_dogfooding/dogfooding.config.js +++ b/website/_dogfooding/dogfooding.config.js @@ -21,6 +21,20 @@ const dogfoodingPluginInstances = [ // The target folder uses a _ prefix to test against an edge case regarding MDX partials: https://github.com/facebook/docusaurus/discussions/5181#discussioncomment-1018079 path: fs.realpathSync('_dogfooding/docs-tests-symlink'), showLastUpdateTime: true, + sidebarItemsGenerator(args) { + return args.defaultSidebarItemsGenerator({ + ...args, + isCategoryIndex({fileName, directories}) { + const eligibleDocIndexNames = [ + 'index', + 'readme', + directories[0].toLowerCase(), + 'intro', + ]; + return eligibleDocIndexNames.includes(fileName.toLowerCase()); + }, + }); + }, }), ], diff --git a/website/docs/api/plugins/plugin-content-docs.md b/website/docs/api/plugins/plugin-content-docs.md index ef6b1aa9ac..1c706ef128 100644 --- a/website/docs/api/plugins/plugin-content-docs.md +++ b/website/docs/api/plugins/plugin-content-docs.md @@ -77,6 +77,12 @@ type PrefixParser = (filename: string) => { numberPrefix?: number; }; +type CategoryIndexMatcher = (doc: { + fileName: string; + directories: string[]; + extension: string; +}) => boolean; + type SidebarGenerator = (generatorArgs: { item: {type: 'autogenerated'; dirName: string}; // the sidebar item with type "autogenerated" version: {contentPath: string; versionName: string}; // the current version @@ -88,6 +94,7 @@ type SidebarGenerator = (generatorArgs: { sidebarPosition?: number | undefined; }>; // all the docs of that version (unfiltered) numberPrefixParser: PrefixParser; // numberPrefixParser configured for this plugin + isCategoryIndex: CategoryIndexMatcher; // the default category index matcher, that you can override defaultSidebarItemsGenerator: SidebarGenerator; // useful to re-use/enhance default sidebar generation logic from Docusaurus }) => Promise; @@ -141,6 +148,7 @@ const config = { item, version, docs, + isCategoryIndex, }) { // Use the provided data to generate a custom sidebar slice return [ @@ -274,15 +282,15 @@ website/i18n/[locale]/docusaurus-plugin-content-docs │ │ # translations for website/docs ├── current -│   ├── api -│   │   └── config.md -│   └── getting-started.md +│ ├── api +│ │ └── config.md +│ └── getting-started.md ├── current.json │ │ # translations for website/versioned_docs/version-1.0.0 ├── version-1.0.0 -│   ├── api -│   │   └── config.md -│   └── getting-started.md +│ ├── api +│ │ └── config.md +│ └── getting-started.md └── version-1.0.0.json ``` diff --git a/website/docs/guides/docs/sidebar/autogenerated.md b/website/docs/guides/docs/sidebar/autogenerated.md index f3ffe9b20c..4282e02c11 100644 --- a/website/docs/guides/docs/sidebar/autogenerated.md +++ b/website/docs/guides/docs/sidebar/autogenerated.md @@ -194,6 +194,102 @@ Naming your introductory document `README.md` makes it show up when browsing the ::: +
+ +Customizing category index matching + +It is possible to opt out any of the category index conventions, or define even more conventions. You can inject your own `isCategoryIndex` matcher through the [`sidebarItemsGenerator`](#customize-the-sidebar-items-generator) callback. For example, you can also pick `intro` as another file name eligible for automatically becoming the category index. + +```js title="docusaurus.config.js" +module.exports = { + plugins: [ + [ + '@docusaurus/plugin-content-docs', + { + async sidebarItemsGenerator({ + ...args, + isCategoryIndex: defaultCategoryIndexMatcher, // The default matcher implementation, given below + defaultSidebarItemsGenerator, + }) { + return defaultSidebarItemsGenerator({ + ...args, + // highlight-start + isCategoryIndex(doc) { + return ( + // Also pick intro.md in addition to the default ones + doc.fileName.toLowerCase() === 'intro' || + defaultCategoryIndexMatcher(doc) + ); + }, + // highlight-end + }); + }, + }, + ], + ], +}; +``` + +Or choose to not have any category index convention. + +```js title="docusaurus.config.js" +module.exports = { + plugins: [ + [ + '@docusaurus/plugin-content-docs', + { + async sidebarItemsGenerator({ + ...args, + isCategoryIndex: defaultCategoryIndexMatcher, // The default matcher implementation, given below + defaultSidebarItemsGenerator, + }) { + return defaultSidebarItemsGenerator({ + ...args, + // highlight-start + isCategoryIndex() { + // No doc will be automatically picked as category index + return false; + }, + // highlight-end + }); + }, + }, + ], + ], +}; +``` + +The `isCategoryIndex` matcher will be provided with three fields: + +- `fileName`, the file's name without extension and with casing preserved +- `directories`, the list of directory names _from the lowest level to the highest level_, relative to the docs root directory +- `extension`, the file's extension, with a leading dot. + +For example, for a doc file at `guides/sidebar/autogenerated.md`, the props the matcher receives are + +```js +const props = { + fileName: 'autogenerated', + directories: ['sidebar', 'guides'], + extension: '.md', +}; +``` + +The default implementation is: + +```js +function isCategoryIndex({fileName, directories}) { + const eligibleDocIndexNames = [ + 'index', + 'readme', + directories[0].toLowerCase(), + ]; + return eligibleDocIndexNames.includes(fileName.toLowerCase()); +} +``` + +
+ ## Autogenerated sidebar metadata {#autogenerated-sidebar-metadata} For hand-written sidebar definitions, you would provide metadata to sidebar items through `sidebars.js`; for autogenerated, Docusaurus would read them from the item's respective file. In addition, you may want to adjust the relative position of each item, because, by default, items within a sidebar slice will be generated in **alphabetical order** (using files and folders names). @@ -317,6 +413,7 @@ module.exports = { item, version, docs, + isCategoryIndex, }) { // Example: return an hardcoded list of static sidebar items return [ From d6cff8c75453b591bc654d8b2ebd148c2e69dd48 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?S=C3=A9bastien=20Lorber?= Date: Wed, 26 Jan 2022 19:28:16 +0100 Subject: [PATCH 003/352] chore(v2): prepare v2.0.0-beta.15 release (#6473) --- CHANGELOG.md | 314 +++++++ admin/new.docusaurus.io/package.json | 2 +- lerna.json | 2 +- packages/create-docusaurus/package.json | 4 +- .../templates/classic-typescript/package.json | 8 +- .../templates/classic/package.json | 6 +- .../templates/facebook/package.json | 6 +- .../docusaurus-cssnano-preset/package.json | 2 +- packages/docusaurus-logger/package.json | 2 +- packages/docusaurus-mdx-loader/package.json | 8 +- packages/docusaurus-migrate/package.json | 4 +- .../package.json | 4 +- .../package.json | 14 +- .../package.json | 16 +- .../package.json | 16 +- .../package.json | 12 +- packages/docusaurus-plugin-debug/package.json | 8 +- .../package.json | 8 +- .../package.json | 8 +- .../package.json | 14 +- packages/docusaurus-plugin-pwa/package.json | 14 +- .../docusaurus-plugin-sitemap/package.json | 12 +- .../docusaurus-preset-classic/package.json | 24 +- .../package.json | 2 +- .../docusaurus-theme-classic/package.json | 24 +- packages/docusaurus-theme-common/package.json | 14 +- .../package.json | 12 +- .../package.json | 16 +- .../package.json | 6 +- packages/docusaurus-types/package.json | 2 +- packages/docusaurus-utils-common/package.json | 4 +- .../docusaurus-utils-validation/package.json | 6 +- packages/docusaurus-utils/package.json | 6 +- packages/docusaurus/package.json | 18 +- packages/lqip-loader/package.json | 2 +- packages/stylelint-copyright/package.json | 2 +- website/package.json | 20 +- .../version-2.0.0-beta.13/advanced/routing.md | 17 - .../api/plugins/plugin-client-redirects.md | 130 --- .../api/plugins/plugin-debug.md | 40 - .../api/plugins/plugin-google-analytics.md | 94 -- .../api/plugins/plugin-google-gtag.md | 100 --- .../api/plugins/plugin-ideal-image.md | 53 -- .../api/plugins/plugin-sitemap.md | 37 - .../guides/docs/docs-introduction.md | 86 -- .../guides/docs/sidebar.md | 809 ------------------ .../guides/docs/versioning.md | 216 ----- .../markdown-features-admonitions.mdx | 123 --- .../markdown-features-math-equations.mdx | 116 --- .../markdown-features-react.mdx | 218 ----- .../i18n/i18n-tutorial.md | 336 -------- .../version-2.0.0-beta.13/presets.md | 137 --- .../version-2.0.0-beta.13/static-assets.md | 71 -- .../version-2.0.0-beta.13/using-plugins.md | 209 ----- .../version-2.0.0-beta.13/using-themes.md | 247 ------ .../_partials/swizzleWarning.mdx | 0 .../advanced/architecture.md | 28 + .../version-2.0.0-beta.15/advanced/index.md | 12 + .../version-2.0.0-beta.15/advanced/plugins.md | 129 +++ .../version-2.0.0-beta.15/advanced/routing.md | 277 ++++++ .../version-2.0.0-beta.15/advanced/ssg.md | 206 +++++ .../advanced/swizzling.md | 195 +++++ .../api/docusaurus.config.js.md | 81 +- .../api/plugin-methods/README.md | 8 +- .../api/plugin-methods/_category_.yml | 0 .../plugin-methods/extend-infrastructure.md | 30 +- .../api/plugin-methods/i18n-lifecycles.md | 4 +- .../api/plugin-methods/lifecycle-apis.md | 41 +- .../api/plugin-methods/static-methods.md | 22 +- .../api/plugins/_category_.yml | 0 .../api/plugins/overview.md | 0 .../api/plugins/plugin-client-redirects.md | 98 +++ .../api/plugins/plugin-content-blog.md | 97 +-- .../api/plugins/plugin-content-docs.md | 110 +-- .../api/plugins/plugin-content-pages.md | 65 +- .../api/plugins/plugin-debug.md | 102 +++ .../api/plugins/plugin-google-analytics.md | 63 ++ .../api/plugins/plugin-google-gtag.md | 69 ++ .../api/plugins/plugin-ideal-image.md | 79 ++ .../api/plugins/plugin-pwa.md | 0 .../api/plugins/plugin-sitemap.md | 72 ++ .../api/themes/_category_.yml | 0 .../api/themes/overview.md | 0 .../api/themes/theme-classic.md | 0 .../api/themes/theme-configuration.md | 130 ++- .../api/themes/theme-live-codeblock.md | 2 +- .../api/themes/theme-search-algolia.md | 2 +- .../docusaurus-asset-example-banner.png | Bin .../assets/docusaurus-asset-example.docx | Bin .../assets/docusaurus-asset-example.xyz | Bin .../blog.mdx | 122 ++- .../browser-support.md | 60 +- .../cli.md | 10 +- .../configuration.md | 63 +- .../deployment.mdx | 52 +- .../docusaurus-core.md | 116 ++- .../guides/creating-pages.md | 43 +- .../guides/docs/docs-create-doc.mdx | 18 +- .../guides/docs/docs-introduction.md | 163 ++++ .../guides/docs/docs-markdown-features.mdx | 6 +- .../guides/docs/docs-multi-instance.mdx | 10 +- .../guides/docs/sidebar/autogenerated.md | 471 ++++++++++ .../guides/docs/sidebar/index.md | 179 ++++ .../guides/docs/sidebar/items.md | 452 ++++++++++ .../guides/docs/sidebar/multiple-sidebars.md | 142 +++ .../guides/docs/versioning.md | 280 ++++++ .../_markdown-partial-example.mdx | 0 .../markdown-features-admonitions.mdx | 199 +++++ .../markdown-features-assets.mdx | 71 +- .../markdown-features-code-blocks.mdx | 295 +++++-- .../markdown-features-head-metadata.mdx | 8 +- .../markdown-features-headings.mdx | 8 +- .../markdown-features-inline-toc.mdx | 6 +- .../markdown-features-intro.mdx | 22 +- .../markdown-features-math-equations.mdx | 193 +++++ .../markdown-features-plugins.mdx | 54 +- .../markdown-features-react.mdx | 465 ++++++++++ .../markdown-features-react.module.css | 17 + .../markdown-features-tabs-styles.module.css | 30 + .../markdown-features-tabs.mdx | 89 +- .../guides/whats-next.md | 21 + .../i18n/i18n-crowdin.mdx | 67 +- .../i18n/i18n-git.md | 18 +- .../i18n/i18n-introduction.md | 64 +- .../i18n/i18n-tutorial.md | 457 ++++++++++ .../installation.md | 35 +- .../introduction.md | 68 +- .../migration/migration-automated.md | 0 .../migration/migration-manual.md | 68 +- .../migration/migration-overview.md | 2 +- .../migration/migration-translated-sites.md | 6 +- .../migration/migration-versioned-sites.md | 10 +- .../playground.mdx | 0 .../search.md | 76 +- .../seo.md | 22 +- .../version-2.0.0-beta.15/static-assets.md | 108 +++ .../styling-layout.md | 159 ++-- .../typescript-support.md | 24 +- .../version-2.0.0-beta.15/using-plugins.md | 320 +++++++ ...on => version-2.0.0-beta.15-sidebars.json} | 36 +- website/versions.json | 5 +- website/versionsArchived.json | 1 + 142 files changed, 6704 insertions(+), 4110 deletions(-) delete mode 100644 website/versioned_docs/version-2.0.0-beta.13/advanced/routing.md delete mode 100644 website/versioned_docs/version-2.0.0-beta.13/api/plugins/plugin-client-redirects.md delete mode 100644 website/versioned_docs/version-2.0.0-beta.13/api/plugins/plugin-debug.md delete mode 100644 website/versioned_docs/version-2.0.0-beta.13/api/plugins/plugin-google-analytics.md delete mode 100644 website/versioned_docs/version-2.0.0-beta.13/api/plugins/plugin-google-gtag.md delete mode 100644 website/versioned_docs/version-2.0.0-beta.13/api/plugins/plugin-ideal-image.md delete mode 100644 website/versioned_docs/version-2.0.0-beta.13/api/plugins/plugin-sitemap.md delete mode 100644 website/versioned_docs/version-2.0.0-beta.13/guides/docs/docs-introduction.md delete mode 100644 website/versioned_docs/version-2.0.0-beta.13/guides/docs/sidebar.md delete mode 100644 website/versioned_docs/version-2.0.0-beta.13/guides/docs/versioning.md delete mode 100644 website/versioned_docs/version-2.0.0-beta.13/guides/markdown-features/markdown-features-admonitions.mdx delete mode 100644 website/versioned_docs/version-2.0.0-beta.13/guides/markdown-features/markdown-features-math-equations.mdx delete mode 100644 website/versioned_docs/version-2.0.0-beta.13/guides/markdown-features/markdown-features-react.mdx delete mode 100644 website/versioned_docs/version-2.0.0-beta.13/i18n/i18n-tutorial.md delete mode 100644 website/versioned_docs/version-2.0.0-beta.13/presets.md delete mode 100644 website/versioned_docs/version-2.0.0-beta.13/static-assets.md delete mode 100644 website/versioned_docs/version-2.0.0-beta.13/using-plugins.md delete mode 100644 website/versioned_docs/version-2.0.0-beta.13/using-themes.md rename website/versioned_docs/{version-2.0.0-beta.13 => version-2.0.0-beta.15}/_partials/swizzleWarning.mdx (100%) create mode 100644 website/versioned_docs/version-2.0.0-beta.15/advanced/architecture.md create mode 100644 website/versioned_docs/version-2.0.0-beta.15/advanced/index.md create mode 100644 website/versioned_docs/version-2.0.0-beta.15/advanced/plugins.md create mode 100644 website/versioned_docs/version-2.0.0-beta.15/advanced/routing.md create mode 100644 website/versioned_docs/version-2.0.0-beta.15/advanced/ssg.md create mode 100644 website/versioned_docs/version-2.0.0-beta.15/advanced/swizzling.md rename website/versioned_docs/{version-2.0.0-beta.13 => version-2.0.0-beta.15}/api/docusaurus.config.js.md (86%) rename website/versioned_docs/{version-2.0.0-beta.13 => version-2.0.0-beta.15}/api/plugin-methods/README.md (93%) rename website/versioned_docs/{version-2.0.0-beta.13 => version-2.0.0-beta.15}/api/plugin-methods/_category_.yml (100%) rename website/versioned_docs/{version-2.0.0-beta.13 => version-2.0.0-beta.15}/api/plugin-methods/extend-infrastructure.md (71%) rename website/versioned_docs/{version-2.0.0-beta.13 => version-2.0.0-beta.15}/api/plugin-methods/i18n-lifecycles.md (94%) rename website/versioned_docs/{version-2.0.0-beta.13 => version-2.0.0-beta.15}/api/plugin-methods/lifecycle-apis.md (88%) rename website/versioned_docs/{version-2.0.0-beta.13 => version-2.0.0-beta.15}/api/plugin-methods/static-methods.md (80%) rename website/versioned_docs/{version-2.0.0-beta.13 => version-2.0.0-beta.15}/api/plugins/_category_.yml (100%) rename website/versioned_docs/{version-2.0.0-beta.13 => version-2.0.0-beta.15}/api/plugins/overview.md (100%) create mode 100644 website/versioned_docs/version-2.0.0-beta.15/api/plugins/plugin-client-redirects.md rename website/versioned_docs/{version-2.0.0-beta.13 => version-2.0.0-beta.15}/api/plugins/plugin-content-blog.md (81%) rename website/versioned_docs/{version-2.0.0-beta.13 => version-2.0.0-beta.15}/api/plugins/plugin-content-docs.md (80%) rename website/versioned_docs/{version-2.0.0-beta.13 => version-2.0.0-beta.15}/api/plugins/plugin-content-pages.md (64%) create mode 100644 website/versioned_docs/version-2.0.0-beta.15/api/plugins/plugin-debug.md create mode 100644 website/versioned_docs/version-2.0.0-beta.15/api/plugins/plugin-google-analytics.md create mode 100644 website/versioned_docs/version-2.0.0-beta.15/api/plugins/plugin-google-gtag.md create mode 100644 website/versioned_docs/version-2.0.0-beta.15/api/plugins/plugin-ideal-image.md rename website/versioned_docs/{version-2.0.0-beta.13 => version-2.0.0-beta.15}/api/plugins/plugin-pwa.md (100%) create mode 100644 website/versioned_docs/version-2.0.0-beta.15/api/plugins/plugin-sitemap.md rename website/versioned_docs/{version-2.0.0-beta.13 => version-2.0.0-beta.15}/api/themes/_category_.yml (100%) rename website/versioned_docs/{version-2.0.0-beta.13 => version-2.0.0-beta.15}/api/themes/overview.md (100%) rename website/versioned_docs/{version-2.0.0-beta.13 => version-2.0.0-beta.15}/api/themes/theme-classic.md (100%) rename website/versioned_docs/{version-2.0.0-beta.13 => version-2.0.0-beta.15}/api/themes/theme-configuration.md (87%) rename website/versioned_docs/{version-2.0.0-beta.13 => version-2.0.0-beta.15}/api/themes/theme-live-codeblock.md (95%) rename website/versioned_docs/{version-2.0.0-beta.13 => version-2.0.0-beta.15}/api/themes/theme-search-algolia.md (91%) rename website/versioned_docs/{version-2.0.0-beta.13 => version-2.0.0-beta.15}/assets/docusaurus-asset-example-banner.png (100%) rename website/versioned_docs/{version-2.0.0-beta.13 => version-2.0.0-beta.15}/assets/docusaurus-asset-example.docx (100%) rename website/versioned_docs/{version-2.0.0-beta.13 => version-2.0.0-beta.15}/assets/docusaurus-asset-example.xyz (100%) rename website/versioned_docs/{version-2.0.0-beta.13 => version-2.0.0-beta.15}/blog.mdx (77%) rename website/versioned_docs/{version-2.0.0-beta.13 => version-2.0.0-beta.15}/browser-support.md (52%) rename website/versioned_docs/{version-2.0.0-beta.13 => version-2.0.0-beta.15}/cli.md (95%) rename website/versioned_docs/{version-2.0.0-beta.13 => version-2.0.0-beta.15}/configuration.md (61%) rename website/versioned_docs/{version-2.0.0-beta.13 => version-2.0.0-beta.15}/deployment.mdx (91%) rename website/versioned_docs/{version-2.0.0-beta.13 => version-2.0.0-beta.15}/docusaurus-core.md (82%) rename website/versioned_docs/{version-2.0.0-beta.13 => version-2.0.0-beta.15}/guides/creating-pages.md (72%) rename website/versioned_docs/{version-2.0.0-beta.13 => version-2.0.0-beta.15}/guides/docs/docs-create-doc.mdx (87%) create mode 100644 website/versioned_docs/version-2.0.0-beta.15/guides/docs/docs-introduction.md rename website/versioned_docs/{version-2.0.0-beta.13 => version-2.0.0-beta.15}/guides/docs/docs-markdown-features.mdx (83%) rename website/versioned_docs/{version-2.0.0-beta.13 => version-2.0.0-beta.15}/guides/docs/docs-multi-instance.mdx (92%) create mode 100644 website/versioned_docs/version-2.0.0-beta.15/guides/docs/sidebar/autogenerated.md create mode 100644 website/versioned_docs/version-2.0.0-beta.15/guides/docs/sidebar/index.md create mode 100644 website/versioned_docs/version-2.0.0-beta.15/guides/docs/sidebar/items.md create mode 100644 website/versioned_docs/version-2.0.0-beta.15/guides/docs/sidebar/multiple-sidebars.md create mode 100644 website/versioned_docs/version-2.0.0-beta.15/guides/docs/versioning.md rename website/versioned_docs/{version-2.0.0-beta.13 => version-2.0.0-beta.15}/guides/markdown-features/_markdown-partial-example.mdx (100%) create mode 100644 website/versioned_docs/version-2.0.0-beta.15/guides/markdown-features/markdown-features-admonitions.mdx rename website/versioned_docs/{version-2.0.0-beta.13 => version-2.0.0-beta.15}/guides/markdown-features/markdown-features-assets.mdx (66%) rename website/versioned_docs/{version-2.0.0-beta.13 => version-2.0.0-beta.15}/guides/markdown-features/markdown-features-code-blocks.mdx (67%) rename website/versioned_docs/{version-2.0.0-beta.13 => version-2.0.0-beta.15}/guides/markdown-features/markdown-features-head-metadata.mdx (81%) rename website/versioned_docs/{version-2.0.0-beta.13 => version-2.0.0-beta.15}/guides/markdown-features/markdown-features-headings.mdx (82%) rename website/versioned_docs/{version-2.0.0-beta.13 => version-2.0.0-beta.15}/guides/markdown-features/markdown-features-inline-toc.mdx (91%) rename website/versioned_docs/{version-2.0.0-beta.13 => version-2.0.0-beta.15}/guides/markdown-features/markdown-features-intro.mdx (79%) create mode 100644 website/versioned_docs/version-2.0.0-beta.15/guides/markdown-features/markdown-features-math-equations.mdx rename website/versioned_docs/{version-2.0.0-beta.13 => version-2.0.0-beta.15}/guides/markdown-features/markdown-features-plugins.mdx (76%) create mode 100644 website/versioned_docs/version-2.0.0-beta.15/guides/markdown-features/markdown-features-react.mdx create mode 100644 website/versioned_docs/version-2.0.0-beta.15/guides/markdown-features/markdown-features-react.module.css create mode 100644 website/versioned_docs/version-2.0.0-beta.15/guides/markdown-features/markdown-features-tabs-styles.module.css rename website/versioned_docs/{version-2.0.0-beta.13 => version-2.0.0-beta.15}/guides/markdown-features/markdown-features-tabs.mdx (70%) create mode 100644 website/versioned_docs/version-2.0.0-beta.15/guides/whats-next.md rename website/versioned_docs/{version-2.0.0-beta.13 => version-2.0.0-beta.15}/i18n/i18n-crowdin.mdx (87%) rename website/versioned_docs/{version-2.0.0-beta.13 => version-2.0.0-beta.15}/i18n/i18n-git.md (90%) rename website/versioned_docs/{version-2.0.0-beta.13 => version-2.0.0-beta.15}/i18n/i18n-introduction.md (66%) create mode 100644 website/versioned_docs/version-2.0.0-beta.15/i18n/i18n-tutorial.md rename website/versioned_docs/{version-2.0.0-beta.13 => version-2.0.0-beta.15}/installation.md (76%) rename website/versioned_docs/{version-2.0.0-beta.13 => version-2.0.0-beta.15}/introduction.md (57%) rename website/versioned_docs/{version-2.0.0-beta.13 => version-2.0.0-beta.15}/migration/migration-automated.md (100%) rename website/versioned_docs/{version-2.0.0-beta.13 => version-2.0.0-beta.15}/migration/migration-manual.md (93%) rename website/versioned_docs/{version-2.0.0-beta.13 => version-2.0.0-beta.15}/migration/migration-overview.md (99%) rename website/versioned_docs/{version-2.0.0-beta.13 => version-2.0.0-beta.15}/migration/migration-translated-sites.md (96%) rename website/versioned_docs/{version-2.0.0-beta.13 => version-2.0.0-beta.15}/migration/migration-versioned-sites.md (92%) rename website/versioned_docs/{version-2.0.0-beta.13 => version-2.0.0-beta.15}/playground.mdx (100%) rename website/versioned_docs/{version-2.0.0-beta.13 => version-2.0.0-beta.15}/search.md (73%) rename website/versioned_docs/{version-2.0.0-beta.13 => version-2.0.0-beta.15}/seo.md (84%) create mode 100644 website/versioned_docs/version-2.0.0-beta.15/static-assets.md rename website/versioned_docs/{version-2.0.0-beta.13 => version-2.0.0-beta.15}/styling-layout.md (55%) rename website/versioned_docs/{version-2.0.0-beta.13 => version-2.0.0-beta.15}/typescript-support.md (83%) create mode 100644 website/versioned_docs/version-2.0.0-beta.15/using-plugins.md rename website/versioned_sidebars/{version-2.0.0-beta.13-sidebars.json => version-2.0.0-beta.15-sidebars.json} (78%) diff --git a/CHANGELOG.md b/CHANGELOG.md index 1dc67ac55b..4f104ed1d1 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,319 @@ # Docusaurus 2 Changelog +## 2.0.0-beta.15 (2022-01-26) + +#### :rocket: New Feature + +- `docusaurus-plugin-content-docs` + - [#6451](https://github.com/facebook/docusaurus/pull/6451) feat(content-docs): expose isCategoryIndex matcher to customize conventions ([@Josh-Cena](https://github.com/Josh-Cena)) + - [#5782](https://github.com/facebook/docusaurus/pull/5782) feat(content-docs): displayed_sidebar front matter ([@Josh-Cena](https://github.com/Josh-Cena)) +- `docusaurus-theme-classic`, `docusaurus-theme-common` + - [#6466](https://github.com/facebook/docusaurus/pull/6466) feat(theme-classic): add stable class for DocSidebarContainer ([@homotechsual](https://github.com/homotechsual)) + - [#3811](https://github.com/facebook/docusaurus/pull/3811) feat(theme-classic): auto-collapse sibling categories in doc sidebar ([@josephriosIO](https://github.com/josephriosIO)) + - [#6216](https://github.com/facebook/docusaurus/pull/6216) feat(theme-classic): usable CodeBlock outside markdown ([@Josh-Cena](https://github.com/Josh-Cena)) +- `docusaurus-plugin-content-blog`, `docusaurus-theme-classic` + - [#6416](https://github.com/facebook/docusaurus/pull/6416) feat(content-blog): allow authors list to contain images only ([@Josh-Cena](https://github.com/Josh-Cena)) +- `docusaurus-plugin-content-blog` + - [#6415](https://github.com/facebook/docusaurus/pull/6415) feat(content-blog): allow disabling generating archive ([@Josh-Cena](https://github.com/Josh-Cena)) + - [#6245](https://github.com/facebook/docusaurus/pull/6245) feat(content-blog): parse date from middle of file path ([@Josh-Cena](https://github.com/Josh-Cena)) + - [#6388](https://github.com/facebook/docusaurus/pull/6388) feat(content-blog): include tags in feed ([@Josh-Cena](https://github.com/Josh-Cena)) +- `docusaurus-module-type-aliases`, `docusaurus-theme-classic`, `docusaurus-types`, `docusaurus` + - [#6371](https://github.com/facebook/docusaurus/pull/6371) feat(core, theme-classic): allow overriding htmlLang ([@noomorph](https://github.com/noomorph)) +- `docusaurus-mdx-loader` + - [#6323](https://github.com/facebook/docusaurus/pull/6323) feat(mdx-loader): preserve hash in image src; support GH themed images ([@Josh-Cena](https://github.com/Josh-Cena)) +- `docusaurus-plugin-content-docs`, `docusaurus-theme-classic` + - [#6139](https://github.com/facebook/docusaurus/pull/6139) feat(theme-classic): new navbar item linking to a sidebar ([@lmpham1](https://github.com/lmpham1)) + - [#6239](https://github.com/facebook/docusaurus/pull/6239) feat(content-docs): allow SEO metadata for category index pages ([@Josh-Cena](https://github.com/Josh-Cena)) +- `docusaurus-plugin-sitemap` + - [#6248](https://github.com/facebook/docusaurus/pull/6248) feat(sitemap): remove trailingSlash option; respect noIndex config ([@Josh-Cena](https://github.com/Josh-Cena)) +- `docusaurus-plugin-ideal-image`, `docusaurus-theme-translations` + - [#6173](https://github.com/facebook/docusaurus/pull/6173) feat(ideal-image): allow translating status messages ([@Josh-Cena](https://github.com/Josh-Cena)) +- `docusaurus-plugin-ideal-image` + - [#6155](https://github.com/facebook/docusaurus/pull/6155) feat(ideal-image): new option disableInDev ([@Josh-Cena](https://github.com/Josh-Cena)) +- `docusaurus-theme-translations` + - [#6169](https://github.com/facebook/docusaurus/pull/6169) feat(theme-translations): add Italian translations ([@mcallisto](https://github.com/mcallisto)) +- `docusaurus-plugin-content-blog`, `docusaurus-plugin-content-docs`, `docusaurus-plugin-content-pages`, `docusaurus-types`, `docusaurus` + - [#6166](https://github.com/facebook/docusaurus/pull/6166) feat: async plugin creator functions ([@slorber](https://github.com/slorber)) +- `docusaurus` + - [#6165](https://github.com/facebook/docusaurus/pull/6165) feat(core): async docusaurus.config.js creator function ([@slorber](https://github.com/slorber)) + +#### :boom: Breaking Change + +- `docusaurus-theme-search-algolia` + - [#6407](https://github.com/facebook/docusaurus/pull/6407) feat(search): enable contextual search by default ([@slorber](https://github.com/slorber)) +- `docusaurus-theme-classic`, `docusaurus-theme-common`, `docusaurus-theme-live-codeblock`, `docusaurus-theme-search-algolia` + - [#6289](https://github.com/facebook/docusaurus/pull/6289) refactor: move @theme/hooks to @docusaurus/theme-common ([@slorber](https://github.com/slorber)) +- `docusaurus-theme-classic` + - [#6283](https://github.com/facebook/docusaurus/pull/6283) refactor(theme-classic): apply import/no-named-export eslint rule ([@slorber](https://github.com/slorber)) +- `docusaurus-plugin-sitemap` + - [#6248](https://github.com/facebook/docusaurus/pull/6248) feat(sitemap): remove trailingSlash option; respect noIndex config ([@Josh-Cena](https://github.com/Josh-Cena)) + +#### :bug: Bug Fix + +- `docusaurus-plugin-content-blog`, `docusaurus-theme-classic`, `docusaurus-types`, `docusaurus-utils-common`, `docusaurus-utils`, `docusaurus` + - [#6454](https://github.com/facebook/docusaurus/pull/6454) fix(content-blog): generate feed by reading build output ([@Josh-Cena](https://github.com/Josh-Cena)) +- `create-docusaurus` + - [#6468](https://github.com/facebook/docusaurus/pull/6468) fix(init): cd to correct path when installing ([@gabrielcsapo](https://github.com/gabrielcsapo)) +- `docusaurus-mdx-loader` + - [#4827](https://github.com/facebook/docusaurus/pull/4827) fix: allow links to JSON in .md files to be transformed as asset links ([@antmcc49](https://github.com/antmcc49)) +- `docusaurus-plugin-content-docs` + - [#6435](https://github.com/facebook/docusaurus/pull/6435) fix(content-docs): make getActivePlugin match plugin paths more exactly ([@Josh-Cena](https://github.com/Josh-Cena)) + - [#6310](https://github.com/facebook/docusaurus/pull/6310) fix: highlight appropriate navItem when browsing generated category index ([@tapanchudasama](https://github.com/tapanchudasama)) + - [#6202](https://github.com/facebook/docusaurus/pull/6202) fix(content-docs): quotify path when retrieving git history ([@Josh-Cena](https://github.com/Josh-Cena)) +- `docusaurus` + - [#6424](https://github.com/facebook/docusaurus/pull/6424) fix(core): fix css url("image.png"), use css-loader v6 with esModules: false ([@slorber](https://github.com/slorber)) + - [#6378](https://github.com/facebook/docusaurus/pull/6378) fix(core): do not coerce webpack warning to string ([@Josh-Cena](https://github.com/Josh-Cena)) + - [#6197](https://github.com/facebook/docusaurus/pull/6197) fix(cli): quotify temp path in deploy command ([@Josh-Cena](https://github.com/Josh-Cena)) + - [#6168](https://github.com/facebook/docusaurus/pull/6168) fix(core): update webpack-dev-server + fix deprecation warning ([@slorber](https://github.com/slorber)) +- `docusaurus-logger`, `docusaurus-utils` + - [#6384](https://github.com/facebook/docusaurus/pull/6384) fix(logger): properly stringify objects for logging ([@Josh-Cena](https://github.com/Josh-Cena)) +- `docusaurus-module-type-aliases`, `docusaurus-theme-classic`, `docusaurus` + - [#6338](https://github.com/facebook/docusaurus/pull/6338) fix(core): error boundary should allow no children ([@slorber](https://github.com/slorber)) +- `docusaurus-theme-classic` + - [#6314](https://github.com/facebook/docusaurus/pull/6314) fix(theme-classic): fix mobile version dropdown label with only one version ([@Josh-Cena](https://github.com/Josh-Cena)) + - [#6288](https://github.com/facebook/docusaurus/pull/6288) fix(theme-classic): add missing role=region to SkipToContent ([@JoshuaKGoldberg](https://github.com/JoshuaKGoldberg)) + - [#6213](https://github.com/facebook/docusaurus/pull/6213) refactor(theme-classic): extract common PaginatorNavLink component ([@Josh-Cena](https://github.com/Josh-Cena)) + - [#6177](https://github.com/facebook/docusaurus/pull/6177) fix(theme-classic): make React elements in pre render correctly ([@Josh-Cena](https://github.com/Josh-Cena)) +- `docusaurus-plugin-client-redirects`, `docusaurus-plugin-content-blog`, `docusaurus-plugin-content-docs`, `docusaurus-plugin-content-pages`, `docusaurus-preset-classic`, `docusaurus-theme-classic`, `docusaurus-theme-search-algolia` + - [#6300](https://github.com/facebook/docusaurus/pull/6300) refactor: move exported type definitions to declaration file ([@Josh-Cena](https://github.com/Josh-Cena)) +- `docusaurus-migrate` + - [#6276](https://github.com/facebook/docusaurus/pull/6276) fix(migrate): migration CLI should correctly migrate gtag options ([@Josh-Cena](https://github.com/Josh-Cena)) +- `docusaurus-plugin-content-blog` + - [#6244](https://github.com/facebook/docusaurus/pull/6244) fix(content-blog): always convert front matter date as UTC ([@Josh-Cena](https://github.com/Josh-Cena)) +- `docusaurus-mdx-loader`, `docusaurus-utils`, `docusaurus` + - [#6190](https://github.com/facebook/docusaurus/pull/6190) fix(utils): properly escape Windows paths ([@Josh-Cena](https://github.com/Josh-Cena)) + +#### :nail_care: Polish + +- `docusaurus-module-type-aliases` + - [#6469](https://github.com/facebook/docusaurus/pull/6469) fix(module-type-aliases): fix type def for translate params ([@Josh-Cena](https://github.com/Josh-Cena)) +- `docusaurus-theme-search-algolia` + - [#6407](https://github.com/facebook/docusaurus/pull/6407) feat(search): enable contextual search by default ([@slorber](https://github.com/slorber)) +- `docusaurus-mdx-loader` + - [#6443](https://github.com/facebook/docusaurus/pull/6443) refactor(mdx-loader): use vfile.path to access Markdown file path ([@Josh-Cena](https://github.com/Josh-Cena)) +- `docusaurus-theme-classic` + - [#6427](https://github.com/facebook/docusaurus/pull/6427) feat(theme-classic): add aria-current to sidebar category link ([@Josh-Cena](https://github.com/Josh-Cena)) + - [#6391](https://github.com/facebook/docusaurus/pull/6391) refactor(theme-classic): add comments to Prism setup; minor refactor ([@Josh-Cena](https://github.com/Josh-Cena)) + - [#6240](https://github.com/facebook/docusaurus/pull/6240) refactor(theme-classic): use front matter from metadata for BlogPostPage ([@Josh-Cena](https://github.com/Josh-Cena)) +- `docusaurus` + - [#6419](https://github.com/facebook/docusaurus/pull/6419) feat(core): warn users about hand-modifying generated files ([@Josh-Cena](https://github.com/Josh-Cena)) + - [#6405](https://github.com/facebook/docusaurus/pull/6405) feat(core): check imported API name when extracting translations ([@Josh-Cena](https://github.com/Josh-Cena)) + - [#6291](https://github.com/facebook/docusaurus/pull/6291) feat(core): improve error message for BrowserOnly; better docs ([@Josh-Cena](https://github.com/Josh-Cena)) +- `create-docusaurus` + - [#5822](https://github.com/facebook/docusaurus/pull/5822) feat: update website & init template palette to pass WCAG test; include contrast check in ColorGenerator ([@Josh-Cena](https://github.com/Josh-Cena)) + - [#6368](https://github.com/facebook/docusaurus/pull/6368) fix(create-docusaurus): add useBaseUrl for image URLs ([@alias-mac](https://github.com/alias-mac)) +- `docusaurus-plugin-content-pages`, `docusaurus-theme-classic` + - [#6400](https://github.com/facebook/docusaurus/pull/6400) feat(content-pages): front matter validation, include front matter in metadata ([@Josh-Cena](https://github.com/Josh-Cena)) +- `docusaurus-mdx-loader`, `docusaurus-theme-classic` + - [#6339](https://github.com/facebook/docusaurus/pull/6339) feat(mdx-loader): read image dimensions when processing Markdown ([@Josh-Cena](https://github.com/Josh-Cena)) +- `docusaurus-plugin-content-blog` + - [#6388](https://github.com/facebook/docusaurus/pull/6388) feat(content-blog): include tags in feed ([@Josh-Cena](https://github.com/Josh-Cena)) + - [#6189](https://github.com/facebook/docusaurus/pull/6189) feat(content-blog): include front matter in loaded content metadata ([@Josh-Cena](https://github.com/Josh-Cena)) +- `docusaurus-theme-common` + - [#6317](https://github.com/facebook/docusaurus/pull/6317) feat(theme-classic): autoscroll TOC with active link ([@cerkiewny](https://github.com/cerkiewny)) +- `docusaurus-mdx-loader`, `docusaurus-plugin-client-redirects`, `docusaurus-plugin-content-blog`, `docusaurus-theme-search-algolia`, `docusaurus-utils-validation`, `docusaurus-utils`, `docusaurus` + - [#6303](https://github.com/facebook/docusaurus/pull/6303) test(utils, mdx-loader, core): improve coverage ([@Josh-Cena](https://github.com/Josh-Cena)) +- `docusaurus-plugin-google-analytics`, `docusaurus-plugin-google-gtag`, `docusaurus-preset-classic` + - [#6284](https://github.com/facebook/docusaurus/pull/6284) fix(preset-classic): throw if preset finds GA options in theme config ([@Josh-Cena](https://github.com/Josh-Cena)) +- `create-docusaurus`, `docusaurus` + - [#6186](https://github.com/facebook/docusaurus/pull/6186) refactor: print trailing new line when outputting JSON ([@Josh-Cena](https://github.com/Josh-Cena)) + +#### :memo: Documentation + +- Other + - [#6296](https://github.com/facebook/docusaurus/pull/6296) docs: add advanced guides ([@Josh-Cena](https://github.com/Josh-Cena)) + - [#6459](https://github.com/facebook/docusaurus/pull/6459) docs: add replicad to showcase ([@sgenoud](https://github.com/sgenoud)) + - [#6334](https://github.com/facebook/docusaurus/pull/6334) docs: 2021 recap blog post ([@Josh-Cena](https://github.com/Josh-Cena)) + - [#6458](https://github.com/facebook/docusaurus/pull/6458) docs: add Kuizuo's Personal Website to showcase ([@kuizuo](https://github.com/kuizuo)) + - [#6431](https://github.com/facebook/docusaurus/pull/6431) docs: add Koyeb as a deployment option ([@edouardb](https://github.com/edouardb)) + - [#6455](https://github.com/facebook/docusaurus/pull/6455) docs: add Sass Fairy to showcase ([@roydukkey](https://github.com/roydukkey)) + - [#6453](https://github.com/facebook/docusaurus/pull/6453) docs: document embedding generated index in doc page ([@Josh-Cena](https://github.com/Josh-Cena)) + - [#6450](https://github.com/facebook/docusaurus/pull/6450) docs: split sidebar documentation into sections ([@Josh-Cena](https://github.com/Josh-Cena)) + - [#6449](https://github.com/facebook/docusaurus/pull/6449) docs: multiple doc improvements ([@Josh-Cena](https://github.com/Josh-Cena)) + - [#6448](https://github.com/facebook/docusaurus/pull/6448) fix(website): update colors correctly when palette is only customized in one color mode ([@Josh-Cena](https://github.com/Josh-Cena)) + - [#6385](https://github.com/facebook/docusaurus/pull/6385) chore: add height/width for front page images ([@nschonni](https://github.com/nschonni)) + - [#6445](https://github.com/facebook/docusaurus/pull/6445) docs: update showcase data of InfraQL ([@jeffreyaven](https://github.com/jeffreyaven)) + - [#6433](https://github.com/facebook/docusaurus/pull/6433) docs: add kube-green to showcase ([@davidebianchi](https://github.com/davidebianchi)) + - [#6428](https://github.com/facebook/docusaurus/pull/6428) docs: elaborate on i18n tutorial ([@Josh-Cena](https://github.com/Josh-Cena)) + - [#6422](https://github.com/facebook/docusaurus/pull/6422) docs: add 404Lab wiki to showcase ([@HiChen404](https://github.com/HiChen404)) + - [#6420](https://github.com/facebook/docusaurus/pull/6420) fix(website): restore some site CSS in light mode ([@Josh-Cena](https://github.com/Josh-Cena)) + - [#6410](https://github.com/facebook/docusaurus/pull/6410) docs: add SODA for SPARC to showcase ([@megasanjay](https://github.com/megasanjay)) + - [#6417](https://github.com/facebook/docusaurus/pull/6417) docs: fix accessibility of search modal ([@Josh-Cena](https://github.com/Josh-Cena)) + - [#6406](https://github.com/facebook/docusaurus/pull/6406) docs(i18n): add docs for htmlLang config ([@noomorph](https://github.com/noomorph)) + - [#6393](https://github.com/facebook/docusaurus/pull/6393) docs: update Algolia docs for new DocSearch infra ([@Josh-Cena](https://github.com/Josh-Cena)) + - [#6383](https://github.com/facebook/docusaurus/pull/6383) docs: elaborate on different CSS class names ([@Josh-Cena](https://github.com/Josh-Cena)) + - [#6348](https://github.com/facebook/docusaurus/pull/6348) docs: add KaustubhK24's site to showcase ([@kaustubhk24](https://github.com/kaustubhk24)) + - [#6333](https://github.com/facebook/docusaurus/pull/6333) feat(website): search in showcase ([@Josh-Cena](https://github.com/Josh-Cena)) + - [#6344](https://github.com/facebook/docusaurus/pull/6344) fix(website): make ColorGenerator functional ([@shwaka](https://github.com/shwaka)) + - [#6340](https://github.com/facebook/docusaurus/pull/6340) docs: minor fix in the sample config for ESM ([@pranabdas](https://github.com/pranabdas)) + - [#6336](https://github.com/facebook/docusaurus/pull/6336) docs: make upgrade guide always show the latest version ([@Josh-Cena](https://github.com/Josh-Cena)) + - [#6320](https://github.com/facebook/docusaurus/pull/6320) chore: upgrade rehype-katex with ESM support, update docs ([@pranabdas](https://github.com/pranabdas)) + - [#6335](https://github.com/facebook/docusaurus/pull/6335) docs: add Pglet website to showcase ([@FeodorFitsner](https://github.com/FeodorFitsner)) + - [#6327](https://github.com/facebook/docusaurus/pull/6327) docs: remove typo bracket ([@MorookaKotaro](https://github.com/MorookaKotaro)) + - [#6316](https://github.com/facebook/docusaurus/pull/6316) docs: add bandwidth.com to showcase ([@ajrice6713](https://github.com/ajrice6713)) + - [#6313](https://github.com/facebook/docusaurus/pull/6313) docs: add Refine site to showcase ([@omeraplak](https://github.com/omeraplak)) + - [#6318](https://github.com/facebook/docusaurus/pull/6318) fix(website): various anchor link fixes ([@Josh-Cena](https://github.com/Josh-Cena)) + - [#6308](https://github.com/facebook/docusaurus/pull/6308) fix(website): wrap details in mdx-code-block ([@Josh-Cena](https://github.com/Josh-Cena)) + - [#6307](https://github.com/facebook/docusaurus/pull/6307) docs: document MD and JSX interoperability issues ([@Josh-Cena](https://github.com/Josh-Cena)) + - [#6299](https://github.com/facebook/docusaurus/pull/6299) docs: add icodex to showcase ([@wood3n](https://github.com/wood3n)) + - [#6297](https://github.com/facebook/docusaurus/pull/6297) docs: mention setup in monorepo ([@PatelN123](https://github.com/PatelN123)) + - [#6293](https://github.com/facebook/docusaurus/pull/6293) docs: remove GraphQL mesh from showcase ([@Josh-Cena](https://github.com/Josh-Cena)) + - [#6231](https://github.com/facebook/docusaurus/pull/6231) docs: update showcase images; remove GraphQL Code Generator site ([@PatelN123](https://github.com/PatelN123)) + - [#6285](https://github.com/facebook/docusaurus/pull/6285) refactor(website): further optimize showcase images ([@Josh-Cena](https://github.com/Josh-Cena)) + - [#6281](https://github.com/facebook/docusaurus/pull/6281) docs: Add kwatch to showcase ([@abahmed](https://github.com/abahmed)) + - [#6280](https://github.com/facebook/docusaurus/pull/6280) docs: elaborate on doc versioning ([@Josh-Cena](https://github.com/Josh-Cena)) + - [#6043](https://github.com/facebook/docusaurus/pull/6043) fix(website): resize showcase images, tighten CI check ([@armano2](https://github.com/armano2)) + - [#6274](https://github.com/facebook/docusaurus/pull/6274) docs: add dyte docs to showcase ([@vaibhavshn](https://github.com/vaibhavshn)) + - [#6278](https://github.com/facebook/docusaurus/pull/6278) docs: add Khyron Realm to showcase ([@alexgrigoras](https://github.com/alexgrigoras)) + - [#6271](https://github.com/facebook/docusaurus/pull/6271) docs: add FlatifyCSS to showcase ([@amir2mi](https://github.com/amir2mi)) + - [#6275](https://github.com/facebook/docusaurus/pull/6275) fix(website): fix config-tabs breaking after translation ([@Josh-Cena](https://github.com/Josh-Cena)) + - [#6269](https://github.com/facebook/docusaurus/pull/6269) docs: add Ionic to showcase ([@ltm](https://github.com/ltm)) + - [#6272](https://github.com/facebook/docusaurus/pull/6272) docs: make tsconfig work OOTB in typescript guide ([@Josh-Cena](https://github.com/Josh-Cena)) + - [#6265](https://github.com/facebook/docusaurus/pull/6265) docs: add Eric JiuRan's blog to showcase ([@1084350607](https://github.com/1084350607)) + - [#6242](https://github.com/facebook/docusaurus/pull/6242) docs(showcase): update oxidizer website url ([@vandreleal](https://github.com/vandreleal)) + - [#6226](https://github.com/facebook/docusaurus/pull/6226) docs: update showcase data for digital support notes ([@PatelN123](https://github.com/PatelN123)) + - [#6224](https://github.com/facebook/docusaurus/pull/6224) docs: add TalentBrick to showcase ([@Josh-Cena](https://github.com/Josh-Cena)) + - [#6223](https://github.com/facebook/docusaurus/pull/6223) docs: normalize CodeBlock highlighting ([@Josh-Cena](https://github.com/Josh-Cena)) + - [#6214](https://github.com/facebook/docusaurus/pull/6214) feat(website): improve prism themes ([@Josh-Cena](https://github.com/Josh-Cena)) + - [#6215](https://github.com/facebook/docusaurus/pull/6215) docs: use BrowserWindow for Markdown demos ([@Josh-Cena](https://github.com/Josh-Cena)) + - [#6193](https://github.com/facebook/docusaurus/pull/6193) docs: normalize plugin API documentation ([@Josh-Cena](https://github.com/Josh-Cena)) + - [#6209](https://github.com/facebook/docusaurus/pull/6209) docs: elaborate on static asset resolution ([@Josh-Cena](https://github.com/Josh-Cena)) + - [#6207](https://github.com/facebook/docusaurus/pull/6207) docs: add default value for BrowserWindow URL field ([@Josh-Cena](https://github.com/Josh-Cena)) + - [#6206](https://github.com/facebook/docusaurus/pull/6206) docs: fix highlighting of YAML front matter ([@Josh-Cena](https://github.com/Josh-Cena)) + - [#6191](https://github.com/facebook/docusaurus/pull/6191) docs: fix react live scope button color in dark mode ([@Josh-Cena](https://github.com/Josh-Cena)) + - [#6188](https://github.com/facebook/docusaurus/pull/6188) docs: add Layer0 to deployment guide ([@rishi-raj-jain](https://github.com/rishi-raj-jain)) + - [#6184](https://github.com/facebook/docusaurus/pull/6184) docs: remove mention of 'UA-' in gtag ([@johnnyreilly](https://github.com/johnnyreilly)) + - [#6181](https://github.com/facebook/docusaurus/pull/6181) docs: add GTFS-to-HTML to showcase ([@brendannee](https://github.com/brendannee)) + - [#6178](https://github.com/facebook/docusaurus/pull/6178) docs: add Digital Support Notes to showcase ([@PatelN123](https://github.com/PatelN123)) + - [#6170](https://github.com/facebook/docusaurus/pull/6170) docs: add LabVIEW coding experience to showcase ([@ruanqizhen](https://github.com/ruanqizhen)) + - [#6164](https://github.com/facebook/docusaurus/pull/6164) docs: fix import module name of theme/Admonition ([@Josh-Cena](https://github.com/Josh-Cena)) + - [#6158](https://github.com/facebook/docusaurus/pull/6158) docs: add Astronomer to showcase ([@jwitz](https://github.com/jwitz)) +- `create-docusaurus` + - [#5822](https://github.com/facebook/docusaurus/pull/5822) feat: update website & init template palette to pass WCAG test; include contrast check in ColorGenerator ([@Josh-Cena](https://github.com/Josh-Cena)) + - [#6187](https://github.com/facebook/docusaurus/pull/6187) docs: make installation guide more beginner-friendly ([@PatelN123](https://github.com/PatelN123)) +- `docusaurus-utils` + - [#6204](https://github.com/facebook/docusaurus/pull/6204) docs: recommend highlighting with comments than number range ([@Josh-Cena](https://github.com/Josh-Cena)) +- `create-docusaurus`, `docusaurus-theme-classic` + - [#6203](https://github.com/facebook/docusaurus/pull/6203) docs: audit grammar issues ([@Josh-Cena](https://github.com/Josh-Cena)) + +#### :house: Internal + +- `docusaurus-mdx-loader`, `docusaurus-migrate`, `docusaurus-plugin-client-redirects`, `docusaurus-plugin-content-blog`, `docusaurus-plugin-content-docs`, `docusaurus-theme-classic`, `docusaurus-theme-common`, `docusaurus-theme-search-algolia`, `docusaurus-utils-validation`, `docusaurus-utils`, `docusaurus` + - [#6456](https://github.com/facebook/docusaurus/pull/6456) chore: add cSpell for spell checking ([@nschonni](https://github.com/nschonni)) +- Other + - [#6444](https://github.com/facebook/docusaurus/pull/6444) misc: update nvmrc to 14.17.0 to meet dependency requirements ([@jodyheavener](https://github.com/jodyheavener)) + - [#6441](https://github.com/facebook/docusaurus/pull/6441) misc: fix stylelint erroring when lint-staged passed ignored file ([@Josh-Cena](https://github.com/Josh-Cena)) + - [#6421](https://github.com/facebook/docusaurus/pull/6421) chore: fix yarn build:website:fast ([@slorber](https://github.com/slorber)) + - [#6381](https://github.com/facebook/docusaurus/pull/6381) chore(website): set cache-control for static assets ([@nschonni](https://github.com/nschonni)) + - [#6364](https://github.com/facebook/docusaurus/pull/6364) chore: remove Intl polyfills for Jest ([@Josh-Cena](https://github.com/Josh-Cena)) + - [#6325](https://github.com/facebook/docusaurus/pull/6325) chore: add Dependabot for dependency updates ([@nschonni](https://github.com/nschonni)) + - [#6328](https://github.com/facebook/docusaurus/pull/6328) chore(ci): upgrade actions/github-script to v5 ([@nschonni](https://github.com/nschonni)) + - [#6332](https://github.com/facebook/docusaurus/pull/6332) chore(deps): bump follow-redirects from 1.14.5 to 1.14.7 ([@dependabot[bot]](https://github.com/apps/dependabot)) + - [#6326](https://github.com/facebook/docusaurus/pull/6326) misc(ci): remove redundant "CI: true" env ([@nschonni](https://github.com/nschonni)) + - [#6304](https://github.com/facebook/docusaurus/pull/6304) chore: upgrade to Husky 7 ([@nschonni](https://github.com/nschonni)) + - [#6222](https://github.com/facebook/docusaurus/pull/6222) test: ensure consistent CSS ordering ([@slorber](https://github.com/slorber)) + - [#6159](https://github.com/facebook/docusaurus/pull/6159) docs: remove useless comment ([@slorber](https://github.com/slorber)) + - [#6148](https://github.com/facebook/docusaurus/pull/6148) chore(examples): update examples to 2.0.0-beta.14 ([@slorber](https://github.com/slorber)) +- `docusaurus-plugin-debug`, `docusaurus-theme-classic`, `docusaurus-theme-common`, `docusaurus-theme-live-codeblock`, `docusaurus-theme-search-algolia`, `docusaurus` + - [#6442](https://github.com/facebook/docusaurus/pull/6442) chore: enable stylelint standard config ([@Josh-Cena](https://github.com/Josh-Cena)) +- `docusaurus-mdx-loader`, `docusaurus-plugin-client-redirects`, `docusaurus-plugin-content-blog`, `docusaurus-plugin-content-docs`, `docusaurus-plugin-ideal-image`, `docusaurus-theme-classic`, `docusaurus-theme-common`, `docusaurus-theme-live-codeblock`, `docusaurus` + - [#6440](https://github.com/facebook/docusaurus/pull/6440) chore: remove some unused dependencies from package.json ([@Josh-Cena](https://github.com/Josh-Cena)) +- `docusaurus-theme-classic` + - [#6436](https://github.com/facebook/docusaurus/pull/6436) refactor(theme-classic): render BlogPostItem as one JSX element ([@Josh-Cena](https://github.com/Josh-Cena)) + - [#6283](https://github.com/facebook/docusaurus/pull/6283) refactor(theme-classic): apply import/no-named-export eslint rule ([@slorber](https://github.com/slorber)) +- `docusaurus-plugin-content-pages` + - [#6413](https://github.com/facebook/docusaurus/pull/6413) fix(content-pages): declare hide_table_of_contents as boolean ([@Josh-Cena](https://github.com/Josh-Cena)) +- `docusaurus-migrate`, `docusaurus-module-type-aliases`, `docusaurus-theme-classic`, `docusaurus` + - [#6399](https://github.com/facebook/docusaurus/pull/6399) refactor: clean up TODO comments ([@Josh-Cena](https://github.com/Josh-Cena)) +- `docusaurus-cssnano-preset`, `docusaurus-plugin-client-redirects`, `docusaurus-plugin-content-blog`, `docusaurus-plugin-content-docs`, `docusaurus-theme-common`, `docusaurus-theme-translations`, `docusaurus` + - [#6387](https://github.com/facebook/docusaurus/pull/6387) test: improve test coverage ([@Josh-Cena](https://github.com/Josh-Cena)) +- `docusaurus-utils` + - [#6380](https://github.com/facebook/docusaurus/pull/6380) chore: enable a few fixable ESLint rules ([@nschonni](https://github.com/nschonni)) +- `docusaurus-mdx-loader`, `docusaurus-plugin-content-docs`, `docusaurus-utils`, `docusaurus` + - [#6377](https://github.com/facebook/docusaurus/pull/6377) refactor: use findAsyncSequential in a few places ([@Josh-Cena](https://github.com/Josh-Cena)) +- `docusaurus-mdx-loader`, `docusaurus-migrate`, `docusaurus-plugin-client-redirects`, `docusaurus-plugin-content-blog`, `docusaurus-plugin-content-docs`, `docusaurus-plugin-content-pages`, `docusaurus-theme-classic`, `docusaurus-theme-search-algolia`, `docusaurus-utils-common`, `docusaurus-utils`, `docusaurus`, `stylelint-copyright` + - [#6375](https://github.com/facebook/docusaurus/pull/6375) chore: enable eslint-plugin-jest ([@Josh-Cena](https://github.com/Josh-Cena)) +- `create-docusaurus` + - [#6373](https://github.com/facebook/docusaurus/pull/6373) chore: enable react/jsx-closing-bracket-location ([@nschonni](https://github.com/nschonni)) +- `docusaurus-theme-classic`, `stylelint-copyright` + - [#6374](https://github.com/facebook/docusaurus/pull/6374) feat(stylelint-copyright): autofix, stricter config ([@Josh-Cena](https://github.com/Josh-Cena)) +- `docusaurus-cssnano-preset`, `docusaurus-theme-classic` + - [#6372](https://github.com/facebook/docusaurus/pull/6372) chore: add baseline stylelint rules ([@nschonni](https://github.com/nschonni)) +- `create-docusaurus`, `docusaurus-plugin-debug`, `docusaurus-theme-classic` + - [#6369](https://github.com/facebook/docusaurus/pull/6369) chore: upgrade lint-staged and globs ([@nschonni](https://github.com/nschonni)) +- `docusaurus-theme-search-algolia`, `docusaurus-utils-validation`, `docusaurus` + - [#6341](https://github.com/facebook/docusaurus/pull/6341) chore: regenerate yarn.lock ([@slorber](https://github.com/slorber)) +- `docusaurus-mdx-loader`, `docusaurus-plugin-client-redirects`, `docusaurus-plugin-content-blog`, `docusaurus-plugin-content-pages`, `docusaurus-remark-plugin-npm2yarn`, `docusaurus-theme-classic`, `docusaurus-theme-common`, `docusaurus` + - [#6324](https://github.com/facebook/docusaurus/pull/6324) chore: minor typo cleanup ([@nschonni](https://github.com/nschonni)) +- `create-docusaurus`, `docusaurus-logger`, `docusaurus-mdx-loader`, `docusaurus-migrate`, `docusaurus-plugin-client-redirects`, `docusaurus-plugin-content-blog`, `docusaurus-plugin-content-docs`, `docusaurus-plugin-content-pages`, `docusaurus-plugin-debug`, `docusaurus-plugin-google-analytics`, `docusaurus-plugin-google-gtag`, `docusaurus-plugin-ideal-image`, `docusaurus-plugin-pwa`, `docusaurus-plugin-sitemap`, `docusaurus-preset-classic`, `docusaurus-remark-plugin-npm2yarn`, `docusaurus-theme-classic`, `docusaurus-theme-common`, `docusaurus-theme-live-codeblock`, `docusaurus-theme-search-algolia`, `docusaurus-theme-translations`, `docusaurus-utils-common`, `docusaurus-utils-validation`, `docusaurus-utils`, `docusaurus`, `lqip-loader`, `stylelint-copyright` + - [#6286](https://github.com/facebook/docusaurus/pull/6286) misc: convert all internal scripts to ESM ([@Josh-Cena](https://github.com/Josh-Cena)) +- `docusaurus-theme-classic`, `docusaurus-theme-common`, `docusaurus-theme-live-codeblock`, `docusaurus-theme-search-algolia` + - [#6289](https://github.com/facebook/docusaurus/pull/6289) refactor: move @theme/hooks to @docusaurus/theme-common ([@slorber](https://github.com/slorber)) +- `docusaurus-plugin-content-docs`, `docusaurus-theme-classic`, `docusaurus-theme-common`, `docusaurus-theme-search-algolia` + - [#6287](https://github.com/facebook/docusaurus/pull/6287) refactor: new @docusaurus/plugin-content-docs/client interface ([@slorber](https://github.com/slorber)) +- `docusaurus` + - [#6279](https://github.com/facebook/docusaurus/pull/6279) refactor(core): use native types from webpack-dev-server ([@RDIL](https://github.com/RDIL)) +- `docusaurus-plugin-content-docs` + - [#6277](https://github.com/facebook/docusaurus/pull/6277) refactor(content-docs): make readVersionsMetadata async ([@Josh-Cena](https://github.com/Josh-Cena)) +- `docusaurus-types`, `docusaurus` + - [#6237](https://github.com/facebook/docusaurus/pull/6237) refactor(core): convert serverEntry.js to TS ([@Josh-Cena](https://github.com/Josh-Cena)) +- `create-docusaurus`, `docusaurus-logger`, `docusaurus-mdx-loader`, `docusaurus-migrate`, `docusaurus-module-type-aliases`, `docusaurus-plugin-client-redirects`, `docusaurus-plugin-content-blog`, `docusaurus-plugin-content-docs`, `docusaurus-plugin-content-pages`, `docusaurus-plugin-debug`, `docusaurus-plugin-pwa`, `docusaurus-plugin-sitemap`, `docusaurus-theme-classic`, `docusaurus-theme-common`, `docusaurus-theme-live-codeblock`, `docusaurus-utils-common`, `docusaurus-utils-validation`, `docusaurus-utils`, `docusaurus`, `lqip-loader` + - [#6230](https://github.com/facebook/docusaurus/pull/6230) refactor: enforce type import specifiers ([@Josh-Cena](https://github.com/Josh-Cena)) +- `create-docusaurus`, `docusaurus-plugin-content-blog`, `docusaurus-utils`, `docusaurus` + - [#6229](https://github.com/facebook/docusaurus/pull/6229) refactor(utils): reorganize functions; move authors file resolution to utils ([@Josh-Cena](https://github.com/Josh-Cena)) +- `docusaurus-theme-translations` + - [#6225](https://github.com/facebook/docusaurus/pull/6225) refactor(theme-translations): improve typing for update script ([@Josh-Cena](https://github.com/Josh-Cena)) + - [#6174](https://github.com/facebook/docusaurus/pull/6174) misc(theme-translations): multiple improvements to the update CLI ([@Josh-Cena](https://github.com/Josh-Cena)) + +#### Committers: 46 + +- AJ Rice ([@ajrice6713](https://github.com/ajrice6713)) +- Abdelrahman Ahmed ([@abahmed](https://github.com/abahmed)) +- Alexandru Grigoras ([@alexgrigoras](https://github.com/alexgrigoras)) +- Amir M. Mohamadi ([@amir2mi](https://github.com/amir2mi)) +- Anthony McCaigue ([@antmcc49](https://github.com/antmcc49)) +- Armano ([@armano2](https://github.com/armano2)) +- Brendan Nee ([@brendannee](https://github.com/brendannee)) +- Chen ([@HiChen404](https://github.com/HiChen404)) +- Davide Bianchi ([@davidebianchi](https://github.com/davidebianchi)) +- Devtato ([@cerkiewny](https://github.com/cerkiewny)) +- Edouard Bonlieu ([@edouardb](https://github.com/edouardb)) +- Feodor Fitsner ([@FeodorFitsner](https://github.com/FeodorFitsner)) +- Filipe Guerra ([@alias-mac](https://github.com/alias-mac)) +- Gabriel Csapo ([@gabrielcsapo](https://github.com/gabrielcsapo)) +- Jake Witz ([@jwitz](https://github.com/jwitz)) +- Jeffrey Aven ([@jeffreyaven](https://github.com/jeffreyaven)) +- Jody Heavener ([@jodyheavener](https://github.com/jodyheavener)) +- John Reilly ([@johnnyreilly](https://github.com/johnnyreilly)) +- Joseph ([@josephriosIO](https://github.com/josephriosIO)) +- Josh Goldberg ([@JoshuaKGoldberg](https://github.com/JoshuaKGoldberg)) +- Joshua Chen ([@Josh-Cena](https://github.com/Josh-Cena)) +- Kaustubh Kulkarni ([@kaustubhk24](https://github.com/kaustubhk24)) +- Lars Mikkelsen ([@ltm](https://github.com/ltm)) +- Mikey O'Toole ([@homotechsual](https://github.com/homotechsual)) +- Minh Pham ([@lmpham1](https://github.com/lmpham1)) +- Morooka Kotaro ([@MorookaKotaro](https://github.com/MorookaKotaro)) +- Nayan Patel ([@PatelN123](https://github.com/PatelN123)) +- Nick Schonning ([@nschonni](https://github.com/nschonni)) +- Pranab Das ([@pranabdas](https://github.com/pranabdas)) +- Reece Dunham ([@RDIL](https://github.com/RDIL)) +- Rishi Raj Jain ([@rishi-raj-jain](https://github.com/rishi-raj-jain)) +- Sanjay Soundarajan ([@megasanjay](https://github.com/megasanjay)) +- Shun Wakatsuki ([@shwaka](https://github.com/shwaka)) +- Sébastien Lorber ([@slorber](https://github.com/slorber)) +- Tapan Chudasama ([@tapanchudasama](https://github.com/tapanchudasama)) +- Vaibhav Shinde ([@vaibhavshn](https://github.com/vaibhavshn)) +- Vandré Leal ([@vandreleal](https://github.com/vandreleal)) +- Yaroslav Serhieiev ([@noomorph](https://github.com/noomorph)) +- [@mcallisto](https://github.com/mcallisto) +- [@ruanqizhen](https://github.com/ruanqizhen) +- [@wood3n](https://github.com/wood3n) +- kuizuo ([@kuizuo](https://github.com/kuizuo)) +- sgenoud ([@sgenoud](https://github.com/sgenoud)) +- trent ([@roydukkey](https://github.com/roydukkey)) +- Ömer Faruk APLAK ([@omeraplak](https://github.com/omeraplak)) +- 久染 | JiuRan ([@1084350607](https://github.com/1084350607)) + ## 2.0.0-beta.14 (2021-12-21) #### :rocket: New Feature diff --git a/admin/new.docusaurus.io/package.json b/admin/new.docusaurus.io/package.json index 743c047e86..995e9db7d1 100644 --- a/admin/new.docusaurus.io/package.json +++ b/admin/new.docusaurus.io/package.json @@ -1,6 +1,6 @@ { "name": "new.docusaurus.io", - "version": "2.0.0-beta.14", + "version": "2.0.0-beta.15", "private": true, "scripts": { "start": "netlify dev" diff --git a/lerna.json b/lerna.json index 606f3131a5..61fe6362c7 100644 --- a/lerna.json +++ b/lerna.json @@ -1,5 +1,5 @@ { - "version": "2.0.0-beta.14", + "version": "2.0.0-beta.15", "npmClient": "yarn", "useWorkspaces": true, "changelog": { diff --git a/packages/create-docusaurus/package.json b/packages/create-docusaurus/package.json index 2b2a342054..eb50020692 100755 --- a/packages/create-docusaurus/package.json +++ b/packages/create-docusaurus/package.json @@ -1,6 +1,6 @@ { "name": "create-docusaurus", - "version": "2.0.0-beta.14", + "version": "2.0.0-beta.15", "description": "Create Docusaurus apps easily.", "repository": { "type": "git", @@ -21,7 +21,7 @@ }, "license": "MIT", "dependencies": { - "@docusaurus/logger": "2.0.0-beta.14", + "@docusaurus/logger": "2.0.0-beta.15", "commander": "^5.1.0", "fs-extra": "^10.0.0", "lodash": "^4.17.20", diff --git a/packages/create-docusaurus/templates/classic-typescript/package.json b/packages/create-docusaurus/templates/classic-typescript/package.json index 380464a6a4..f470e201f1 100644 --- a/packages/create-docusaurus/templates/classic-typescript/package.json +++ b/packages/create-docusaurus/templates/classic-typescript/package.json @@ -1,6 +1,6 @@ { "name": "docusaurus-2-classic-typescript-template", - "version": "2.0.0-beta.14", + "version": "2.0.0-beta.15", "private": true, "scripts": { "docusaurus": "docusaurus", @@ -15,8 +15,8 @@ "typecheck": "tsc" }, "dependencies": { - "@docusaurus/core": "2.0.0-beta.14", - "@docusaurus/preset-classic": "2.0.0-beta.14", + "@docusaurus/core": "2.0.0-beta.15", + "@docusaurus/preset-classic": "2.0.0-beta.15", "@mdx-js/react": "^1.6.21", "clsx": "^1.1.1", "prism-react-renderer": "^1.2.1", @@ -24,7 +24,7 @@ "react-dom": "^17.0.1" }, "devDependencies": { - "@docusaurus/module-type-aliases": "2.0.0-beta.14", + "@docusaurus/module-type-aliases": "2.0.0-beta.15", "@tsconfig/docusaurus": "^1.0.4", "typescript": "^4.5.2" }, diff --git a/packages/create-docusaurus/templates/classic/package.json b/packages/create-docusaurus/templates/classic/package.json index 0f73ec0c1c..4430589eb6 100644 --- a/packages/create-docusaurus/templates/classic/package.json +++ b/packages/create-docusaurus/templates/classic/package.json @@ -1,6 +1,6 @@ { "name": "docusaurus-2-classic-template", - "version": "2.0.0-beta.14", + "version": "2.0.0-beta.15", "private": true, "scripts": { "docusaurus": "docusaurus", @@ -14,8 +14,8 @@ "write-heading-ids": "docusaurus write-heading-ids" }, "dependencies": { - "@docusaurus/core": "2.0.0-beta.14", - "@docusaurus/preset-classic": "2.0.0-beta.14", + "@docusaurus/core": "2.0.0-beta.15", + "@docusaurus/preset-classic": "2.0.0-beta.15", "@mdx-js/react": "^1.6.21", "clsx": "^1.1.1", "prism-react-renderer": "^1.2.1", diff --git a/packages/create-docusaurus/templates/facebook/package.json b/packages/create-docusaurus/templates/facebook/package.json index e09e17bc0d..60822412a3 100644 --- a/packages/create-docusaurus/templates/facebook/package.json +++ b/packages/create-docusaurus/templates/facebook/package.json @@ -1,6 +1,6 @@ { "name": "docusaurus-2-facebook-template", - "version": "2.0.0-beta.14", + "version": "2.0.0-beta.15", "private": true, "scripts": { "docusaurus": "docusaurus", @@ -18,8 +18,8 @@ "format:diff": "prettier --config .prettierrc --list-different \"**/*.{js,jsx,ts,tsx,md,mdx}\"" }, "dependencies": { - "@docusaurus/core": "2.0.0-beta.14", - "@docusaurus/preset-classic": "2.0.0-beta.14", + "@docusaurus/core": "2.0.0-beta.15", + "@docusaurus/preset-classic": "2.0.0-beta.15", "@mdx-js/react": "^1.6.21", "clsx": "^1.1.1", "react": "^17.0.1", diff --git a/packages/docusaurus-cssnano-preset/package.json b/packages/docusaurus-cssnano-preset/package.json index 2f5e5ffb11..e05c7a6d92 100644 --- a/packages/docusaurus-cssnano-preset/package.json +++ b/packages/docusaurus-cssnano-preset/package.json @@ -1,6 +1,6 @@ { "name": "@docusaurus/cssnano-preset", - "version": "2.0.0-beta.14", + "version": "2.0.0-beta.15", "description": "Advanced cssnano preset for maximum optimization.", "main": "index.js", "license": "MIT", diff --git a/packages/docusaurus-logger/package.json b/packages/docusaurus-logger/package.json index 226de81f6f..c59bb4ca40 100644 --- a/packages/docusaurus-logger/package.json +++ b/packages/docusaurus-logger/package.json @@ -1,6 +1,6 @@ { "name": "@docusaurus/logger", - "version": "2.0.0-beta.14", + "version": "2.0.0-beta.15", "description": "An encapsulated logger for semantically formatting console messages.", "main": "./lib/index.js", "repository": { diff --git a/packages/docusaurus-mdx-loader/package.json b/packages/docusaurus-mdx-loader/package.json index 2dce287c5e..e29c2a8973 100644 --- a/packages/docusaurus-mdx-loader/package.json +++ b/packages/docusaurus-mdx-loader/package.json @@ -1,6 +1,6 @@ { "name": "@docusaurus/mdx-loader", - "version": "2.0.0-beta.14", + "version": "2.0.0-beta.15", "description": "Docusaurus Loader for MDX", "main": "lib/index.js", "types": "src/mdx-loader.d.ts", @@ -20,8 +20,8 @@ "dependencies": { "@babel/parser": "^7.16.4", "@babel/traverse": "^7.16.3", - "@docusaurus/logger": "2.0.0-beta.14", - "@docusaurus/utils": "2.0.0-beta.14", + "@docusaurus/logger": "2.0.0-beta.15", + "@docusaurus/utils": "2.0.0-beta.15", "@mdx-js/mdx": "^1.6.21", "escape-html": "^1.0.3", "file-loader": "^6.2.0", @@ -36,7 +36,7 @@ "webpack": "^5.61.0" }, "devDependencies": { - "@docusaurus/types": "2.0.0-beta.14", + "@docusaurus/types": "2.0.0-beta.15", "@types/escape-html": "^1.0.1", "@types/mdast": "^3.0.7", "@types/stringify-object": "^3.3.1", diff --git a/packages/docusaurus-migrate/package.json b/packages/docusaurus-migrate/package.json index b008942a2c..2af216b25e 100644 --- a/packages/docusaurus-migrate/package.json +++ b/packages/docusaurus-migrate/package.json @@ -1,6 +1,6 @@ { "name": "@docusaurus/migrate", - "version": "2.0.0-beta.14", + "version": "2.0.0-beta.15", "description": "A CLI tool to migrate from older versions of Docusaurus.", "main": "lib/index.js", "license": "MIT", @@ -24,7 +24,7 @@ }, "dependencies": { "@babel/preset-env": "^7.16.4", - "@docusaurus/logger": "2.0.0-beta.14", + "@docusaurus/logger": "2.0.0-beta.15", "@mapbox/hast-util-to-jsx": "^1.0.0", "color": "^4.0.1", "commander": "^5.1.0", diff --git a/packages/docusaurus-module-type-aliases/package.json b/packages/docusaurus-module-type-aliases/package.json index b8d66ef1cc..b996cc1ba4 100644 --- a/packages/docusaurus-module-type-aliases/package.json +++ b/packages/docusaurus-module-type-aliases/package.json @@ -1,6 +1,6 @@ { "name": "@docusaurus/module-type-aliases", - "version": "2.0.0-beta.14", + "version": "2.0.0-beta.15", "description": "Docusaurus module type aliases.", "types": "./src/index.d.ts", "publishConfig": { @@ -12,7 +12,7 @@ "directory": "packages/docusaurus-module-type-aliases" }, "dependencies": { - "@docusaurus/types": "2.0.0-beta.14", + "@docusaurus/types": "2.0.0-beta.15", "@types/react": "*", "@types/react-helmet": "*", "@types/react-router-config": "*", diff --git a/packages/docusaurus-plugin-client-redirects/package.json b/packages/docusaurus-plugin-client-redirects/package.json index e6f1b91a62..784c8d8c2b 100644 --- a/packages/docusaurus-plugin-client-redirects/package.json +++ b/packages/docusaurus-plugin-client-redirects/package.json @@ -1,6 +1,6 @@ { "name": "@docusaurus/plugin-client-redirects", - "version": "2.0.0-beta.14", + "version": "2.0.0-beta.15", "description": "Client redirects plugin for Docusaurus.", "main": "lib/index.js", "types": "src/plugin-client-redirects.d.ts", @@ -18,18 +18,18 @@ }, "license": "MIT", "dependencies": { - "@docusaurus/core": "2.0.0-beta.14", - "@docusaurus/logger": "2.0.0-beta.14", - "@docusaurus/utils": "2.0.0-beta.14", - "@docusaurus/utils-common": "2.0.0-beta.14", - "@docusaurus/utils-validation": "2.0.0-beta.14", + "@docusaurus/core": "2.0.0-beta.15", + "@docusaurus/logger": "2.0.0-beta.15", + "@docusaurus/utils": "2.0.0-beta.15", + "@docusaurus/utils-common": "2.0.0-beta.15", + "@docusaurus/utils-validation": "2.0.0-beta.15", "eta": "^1.12.3", "fs-extra": "^10.0.0", "lodash": "^4.17.20", "tslib": "^2.3.1" }, "devDependencies": { - "@docusaurus/types": "2.0.0-beta.14" + "@docusaurus/types": "2.0.0-beta.15" }, "peerDependencies": { "react": "^16.8.4 || ^17.0.0", diff --git a/packages/docusaurus-plugin-content-blog/package.json b/packages/docusaurus-plugin-content-blog/package.json index 5c5dd3543f..a4198e81c7 100644 --- a/packages/docusaurus-plugin-content-blog/package.json +++ b/packages/docusaurus-plugin-content-blog/package.json @@ -1,6 +1,6 @@ { "name": "@docusaurus/plugin-content-blog", - "version": "2.0.0-beta.14", + "version": "2.0.0-beta.15", "description": "Blog plugin for Docusaurus.", "main": "lib/index.js", "types": "src/plugin-content-blog.d.ts", @@ -18,12 +18,12 @@ }, "license": "MIT", "dependencies": { - "@docusaurus/core": "2.0.0-beta.14", - "@docusaurus/logger": "2.0.0-beta.14", - "@docusaurus/mdx-loader": "2.0.0-beta.14", - "@docusaurus/utils": "2.0.0-beta.14", - "@docusaurus/utils-common": "2.0.0-beta.14", - "@docusaurus/utils-validation": "2.0.0-beta.14", + "@docusaurus/core": "2.0.0-beta.15", + "@docusaurus/logger": "2.0.0-beta.15", + "@docusaurus/mdx-loader": "2.0.0-beta.15", + "@docusaurus/utils": "2.0.0-beta.15", + "@docusaurus/utils-common": "2.0.0-beta.15", + "@docusaurus/utils-validation": "2.0.0-beta.15", "cheerio": "^1.0.0-rc.10", "feed": "^4.2.2", "fs-extra": "^10.0.0", @@ -35,7 +35,7 @@ "webpack": "^5.61.0" }, "devDependencies": { - "@docusaurus/types": "2.0.0-beta.14", + "@docusaurus/types": "2.0.0-beta.15", "escape-string-regexp": "^4.0.0" }, "peerDependencies": { diff --git a/packages/docusaurus-plugin-content-docs/package.json b/packages/docusaurus-plugin-content-docs/package.json index c456105e1b..7f774c6070 100644 --- a/packages/docusaurus-plugin-content-docs/package.json +++ b/packages/docusaurus-plugin-content-docs/package.json @@ -1,6 +1,6 @@ { "name": "@docusaurus/plugin-content-docs", - "version": "2.0.0-beta.14", + "version": "2.0.0-beta.15", "description": "Docs plugin for Docusaurus.", "main": "lib/index.js", "exports": { @@ -22,11 +22,11 @@ }, "license": "MIT", "dependencies": { - "@docusaurus/core": "2.0.0-beta.14", - "@docusaurus/logger": "2.0.0-beta.14", - "@docusaurus/mdx-loader": "2.0.0-beta.14", - "@docusaurus/utils": "2.0.0-beta.14", - "@docusaurus/utils-validation": "2.0.0-beta.14", + "@docusaurus/core": "2.0.0-beta.15", + "@docusaurus/logger": "2.0.0-beta.15", + "@docusaurus/mdx-loader": "2.0.0-beta.15", + "@docusaurus/utils": "2.0.0-beta.15", + "@docusaurus/utils-validation": "2.0.0-beta.15", "combine-promises": "^1.1.0", "fs-extra": "^10.0.0", "import-fresh": "^3.2.2", @@ -39,8 +39,8 @@ "webpack": "^5.61.0" }, "devDependencies": { - "@docusaurus/module-type-aliases": "2.0.0-beta.14", - "@docusaurus/types": "2.0.0-beta.14", + "@docusaurus/module-type-aliases": "2.0.0-beta.15", + "@docusaurus/types": "2.0.0-beta.15", "@types/js-yaml": "^4.0.0", "@types/picomatch": "^2.2.1", "commander": "^5.1.0", diff --git a/packages/docusaurus-plugin-content-pages/package.json b/packages/docusaurus-plugin-content-pages/package.json index 6772e2f169..2aa0de50dd 100644 --- a/packages/docusaurus-plugin-content-pages/package.json +++ b/packages/docusaurus-plugin-content-pages/package.json @@ -1,6 +1,6 @@ { "name": "@docusaurus/plugin-content-pages", - "version": "2.0.0-beta.14", + "version": "2.0.0-beta.15", "description": "Pages plugin for Docusaurus.", "main": "lib/index.js", "types": "src/plugin-content-pages.d.ts", @@ -18,10 +18,10 @@ }, "license": "MIT", "dependencies": { - "@docusaurus/core": "2.0.0-beta.14", - "@docusaurus/mdx-loader": "2.0.0-beta.14", - "@docusaurus/utils": "2.0.0-beta.14", - "@docusaurus/utils-validation": "2.0.0-beta.14", + "@docusaurus/core": "2.0.0-beta.15", + "@docusaurus/mdx-loader": "2.0.0-beta.15", + "@docusaurus/utils": "2.0.0-beta.15", + "@docusaurus/utils-validation": "2.0.0-beta.15", "fs-extra": "^10.0.0", "globby": "^11.0.2", "remark-admonitions": "^1.2.1", @@ -29,7 +29,7 @@ "webpack": "^5.61.0" }, "devDependencies": { - "@docusaurus/types": "2.0.0-beta.14" + "@docusaurus/types": "2.0.0-beta.15" }, "peerDependencies": { "react": "^16.8.4 || ^17.0.0", diff --git a/packages/docusaurus-plugin-debug/package.json b/packages/docusaurus-plugin-debug/package.json index 5b2adfba39..07dc856451 100644 --- a/packages/docusaurus-plugin-debug/package.json +++ b/packages/docusaurus-plugin-debug/package.json @@ -1,6 +1,6 @@ { "name": "@docusaurus/plugin-debug", - "version": "2.0.0-beta.14", + "version": "2.0.0-beta.15", "description": "Debug plugin for Docusaurus.", "main": "lib/index.js", "types": "src/plugin-debug.d.ts", @@ -18,14 +18,14 @@ }, "license": "MIT", "dependencies": { - "@docusaurus/core": "2.0.0-beta.14", - "@docusaurus/utils": "2.0.0-beta.14", + "@docusaurus/core": "2.0.0-beta.15", + "@docusaurus/utils": "2.0.0-beta.15", "fs-extra": "^10.0.0", "react-json-view": "^1.21.3", "tslib": "^2.3.1" }, "devDependencies": { - "@docusaurus/types": "2.0.0-beta.14" + "@docusaurus/types": "2.0.0-beta.15" }, "peerDependencies": { "react": "^16.8.4 || ^17.0.0", diff --git a/packages/docusaurus-plugin-google-analytics/package.json b/packages/docusaurus-plugin-google-analytics/package.json index 9593476867..691c3099fb 100644 --- a/packages/docusaurus-plugin-google-analytics/package.json +++ b/packages/docusaurus-plugin-google-analytics/package.json @@ -1,6 +1,6 @@ { "name": "@docusaurus/plugin-google-analytics", - "version": "2.0.0-beta.14", + "version": "2.0.0-beta.15", "description": "Global analytics (analytics.js) plugin for Docusaurus.", "main": "lib/index.js", "types": "src/plugin-google-analytics.d.ts", @@ -18,12 +18,12 @@ }, "license": "MIT", "dependencies": { - "@docusaurus/core": "2.0.0-beta.14", - "@docusaurus/utils-validation": "2.0.0-beta.14", + "@docusaurus/core": "2.0.0-beta.15", + "@docusaurus/utils-validation": "2.0.0-beta.15", "tslib": "^2.3.1" }, "devDependencies": { - "@docusaurus/types": "2.0.0-beta.14" + "@docusaurus/types": "2.0.0-beta.15" }, "peerDependencies": { "react": "^16.8.4 || ^17.0.0", diff --git a/packages/docusaurus-plugin-google-gtag/package.json b/packages/docusaurus-plugin-google-gtag/package.json index 2616f708cb..21933fc5a7 100644 --- a/packages/docusaurus-plugin-google-gtag/package.json +++ b/packages/docusaurus-plugin-google-gtag/package.json @@ -1,6 +1,6 @@ { "name": "@docusaurus/plugin-google-gtag", - "version": "2.0.0-beta.14", + "version": "2.0.0-beta.15", "description": "Global Site Tag (gtag.js) plugin for Docusaurus.", "main": "lib/index.js", "types": "src/plugin-google-gtag.d.ts", @@ -18,12 +18,12 @@ }, "license": "MIT", "dependencies": { - "@docusaurus/core": "2.0.0-beta.14", - "@docusaurus/utils-validation": "2.0.0-beta.14", + "@docusaurus/core": "2.0.0-beta.15", + "@docusaurus/utils-validation": "2.0.0-beta.15", "tslib": "^2.3.1" }, "devDependencies": { - "@docusaurus/types": "2.0.0-beta.14" + "@docusaurus/types": "2.0.0-beta.15" }, "peerDependencies": { "react": "^16.8.4 || ^17.0.0", diff --git a/packages/docusaurus-plugin-ideal-image/package.json b/packages/docusaurus-plugin-ideal-image/package.json index fee95e8e93..824fac3cf6 100644 --- a/packages/docusaurus-plugin-ideal-image/package.json +++ b/packages/docusaurus-plugin-ideal-image/package.json @@ -1,6 +1,6 @@ { "name": "@docusaurus/plugin-ideal-image", - "version": "2.0.0-beta.14", + "version": "2.0.0-beta.15", "description": "Docusaurus Plugin to generate an almost ideal image (responsive, lazy-loading, and low quality placeholder).", "main": "lib/index.js", "types": "src/plugin-ideal-image.d.ts", @@ -21,11 +21,11 @@ }, "license": "MIT", "dependencies": { - "@docusaurus/core": "2.0.0-beta.14", - "@docusaurus/lqip-loader": "2.0.0-beta.14", + "@docusaurus/core": "2.0.0-beta.15", + "@docusaurus/lqip-loader": "2.0.0-beta.15", "@docusaurus/responsive-loader": "1.5.0", - "@docusaurus/theme-translations": "2.0.0-beta.14", - "@docusaurus/utils-validation": "2.0.0-beta.14", + "@docusaurus/theme-translations": "2.0.0-beta.15", + "@docusaurus/utils-validation": "2.0.0-beta.15", "@endiliey/react-ideal-image": "^0.0.11", "react-waypoint": "^10.1.0", "sharp": "^0.29.1", @@ -33,8 +33,8 @@ "webpack": "^5.61.0" }, "devDependencies": { - "@docusaurus/module-type-aliases": "2.0.0-beta.14", - "@docusaurus/types": "2.0.0-beta.14", + "@docusaurus/module-type-aliases": "2.0.0-beta.15", + "@docusaurus/types": "2.0.0-beta.15", "fs-extra": "^10.0.0" }, "peerDependencies": { diff --git a/packages/docusaurus-plugin-pwa/package.json b/packages/docusaurus-plugin-pwa/package.json index 50a603c33a..47ebac1dbc 100644 --- a/packages/docusaurus-plugin-pwa/package.json +++ b/packages/docusaurus-plugin-pwa/package.json @@ -1,6 +1,6 @@ { "name": "@docusaurus/plugin-pwa", - "version": "2.0.0-beta.14", + "version": "2.0.0-beta.15", "description": "Docusaurus Plugin to add PWA support.", "main": "lib/index.js", "types": "src/plugin-pwa.d.ts", @@ -23,11 +23,11 @@ "@babel/plugin-proposal-nullish-coalescing-operator": "^7.16.0", "@babel/plugin-proposal-optional-chaining": "^7.16.0", "@babel/preset-env": "^7.16.4", - "@docusaurus/core": "2.0.0-beta.14", - "@docusaurus/theme-common": "2.0.0-beta.14", - "@docusaurus/theme-translations": "2.0.0-beta.14", - "@docusaurus/utils": "2.0.0-beta.14", - "@docusaurus/utils-validation": "2.0.0-beta.14", + "@docusaurus/core": "2.0.0-beta.15", + "@docusaurus/theme-common": "2.0.0-beta.15", + "@docusaurus/theme-translations": "2.0.0-beta.15", + "@docusaurus/utils": "2.0.0-beta.15", + "@docusaurus/utils-validation": "2.0.0-beta.15", "babel-loader": "^8.2.2", "clsx": "^1.1.1", "core-js": "^3.18.0", @@ -40,7 +40,7 @@ "workbox-window": "^6.1.1" }, "devDependencies": { - "@docusaurus/module-type-aliases": "2.0.0-beta.14", + "@docusaurus/module-type-aliases": "2.0.0-beta.15", "fs-extra": "^10.0.0" }, "peerDependencies": { diff --git a/packages/docusaurus-plugin-sitemap/package.json b/packages/docusaurus-plugin-sitemap/package.json index c3f3b11150..4e8d2eae2b 100644 --- a/packages/docusaurus-plugin-sitemap/package.json +++ b/packages/docusaurus-plugin-sitemap/package.json @@ -1,6 +1,6 @@ { "name": "@docusaurus/plugin-sitemap", - "version": "2.0.0-beta.14", + "version": "2.0.0-beta.15", "description": "Simple sitemap generation plugin for Docusaurus.", "main": "lib/index.js", "types": "src/plugin-sitemap.d.ts", @@ -18,16 +18,16 @@ }, "license": "MIT", "dependencies": { - "@docusaurus/core": "2.0.0-beta.14", - "@docusaurus/utils": "2.0.0-beta.14", - "@docusaurus/utils-common": "2.0.0-beta.14", - "@docusaurus/utils-validation": "2.0.0-beta.14", + "@docusaurus/core": "2.0.0-beta.15", + "@docusaurus/utils": "2.0.0-beta.15", + "@docusaurus/utils-common": "2.0.0-beta.15", + "@docusaurus/utils-validation": "2.0.0-beta.15", "fs-extra": "^10.0.0", "sitemap": "^7.0.0", "tslib": "^2.3.1" }, "devDependencies": { - "@docusaurus/types": "2.0.0-beta.14" + "@docusaurus/types": "2.0.0-beta.15" }, "peerDependencies": { "react": "^16.8.4 || ^17.0.0", diff --git a/packages/docusaurus-preset-classic/package.json b/packages/docusaurus-preset-classic/package.json index 8f582c5627..1e87dcc106 100644 --- a/packages/docusaurus-preset-classic/package.json +++ b/packages/docusaurus-preset-classic/package.json @@ -1,6 +1,6 @@ { "name": "@docusaurus/preset-classic", - "version": "2.0.0-beta.14", + "version": "2.0.0-beta.15", "description": "Classic preset for Docusaurus.", "main": "lib/index.js", "types": "src/preset-classic.d.ts", @@ -18,17 +18,17 @@ }, "license": "MIT", "dependencies": { - "@docusaurus/core": "2.0.0-beta.14", - "@docusaurus/plugin-content-blog": "2.0.0-beta.14", - "@docusaurus/plugin-content-docs": "2.0.0-beta.14", - "@docusaurus/plugin-content-pages": "2.0.0-beta.14", - "@docusaurus/plugin-debug": "2.0.0-beta.14", - "@docusaurus/plugin-google-analytics": "2.0.0-beta.14", - "@docusaurus/plugin-google-gtag": "2.0.0-beta.14", - "@docusaurus/plugin-sitemap": "2.0.0-beta.14", - "@docusaurus/theme-classic": "2.0.0-beta.14", - "@docusaurus/theme-common": "2.0.0-beta.14", - "@docusaurus/theme-search-algolia": "2.0.0-beta.14" + "@docusaurus/core": "2.0.0-beta.15", + "@docusaurus/plugin-content-blog": "2.0.0-beta.15", + "@docusaurus/plugin-content-docs": "2.0.0-beta.15", + "@docusaurus/plugin-content-pages": "2.0.0-beta.15", + "@docusaurus/plugin-debug": "2.0.0-beta.15", + "@docusaurus/plugin-google-analytics": "2.0.0-beta.15", + "@docusaurus/plugin-google-gtag": "2.0.0-beta.15", + "@docusaurus/plugin-sitemap": "2.0.0-beta.15", + "@docusaurus/theme-classic": "2.0.0-beta.15", + "@docusaurus/theme-common": "2.0.0-beta.15", + "@docusaurus/theme-search-algolia": "2.0.0-beta.15" }, "peerDependencies": { "react": "^16.8.4 || ^17.0.0", diff --git a/packages/docusaurus-remark-plugin-npm2yarn/package.json b/packages/docusaurus-remark-plugin-npm2yarn/package.json index 80ca1b43fc..385634072f 100644 --- a/packages/docusaurus-remark-plugin-npm2yarn/package.json +++ b/packages/docusaurus-remark-plugin-npm2yarn/package.json @@ -1,6 +1,6 @@ { "name": "@docusaurus/remark-plugin-npm2yarn", - "version": "2.0.0-beta.14", + "version": "2.0.0-beta.15", "description": "Remark plugin for converting npm commands to Yarn commands as tabs.", "main": "lib/index.js", "publishConfig": { diff --git a/packages/docusaurus-theme-classic/package.json b/packages/docusaurus-theme-classic/package.json index 5a74747c45..c7cf53782c 100644 --- a/packages/docusaurus-theme-classic/package.json +++ b/packages/docusaurus-theme-classic/package.json @@ -1,6 +1,6 @@ { "name": "@docusaurus/theme-classic", - "version": "2.0.0-beta.14", + "version": "2.0.0-beta.15", "description": "Classic theme for Docusaurus", "main": "lib/index.js", "types": "src/theme-classic.d.ts", @@ -21,15 +21,15 @@ "format:lib-next": "prettier --config ../../.prettierrc --write \"lib-next/**/*.{js,ts,jsx,tsc}\"" }, "dependencies": { - "@docusaurus/core": "2.0.0-beta.14", - "@docusaurus/plugin-content-blog": "2.0.0-beta.14", - "@docusaurus/plugin-content-docs": "2.0.0-beta.14", - "@docusaurus/plugin-content-pages": "2.0.0-beta.14", - "@docusaurus/theme-common": "2.0.0-beta.14", - "@docusaurus/theme-translations": "2.0.0-beta.14", - "@docusaurus/utils": "2.0.0-beta.14", - "@docusaurus/utils-common": "2.0.0-beta.14", - "@docusaurus/utils-validation": "2.0.0-beta.14", + "@docusaurus/core": "2.0.0-beta.15", + "@docusaurus/plugin-content-blog": "2.0.0-beta.15", + "@docusaurus/plugin-content-docs": "2.0.0-beta.15", + "@docusaurus/plugin-content-pages": "2.0.0-beta.15", + "@docusaurus/theme-common": "2.0.0-beta.15", + "@docusaurus/theme-translations": "2.0.0-beta.15", + "@docusaurus/utils": "2.0.0-beta.15", + "@docusaurus/utils-common": "2.0.0-beta.15", + "@docusaurus/utils-validation": "2.0.0-beta.15", "@mdx-js/react": "^1.6.21", "clsx": "^1.1.1", "copy-text-to-clipboard": "^3.0.1", @@ -42,8 +42,8 @@ "rtlcss": "^3.3.0" }, "devDependencies": { - "@docusaurus/module-type-aliases": "2.0.0-beta.14", - "@docusaurus/types": "2.0.0-beta.14", + "@docusaurus/module-type-aliases": "2.0.0-beta.15", + "@docusaurus/types": "2.0.0-beta.15", "@types/mdx-js__react": "^1.5.4", "@types/parse-numeric-range": "^0.0.1", "@types/prismjs": "^1.16.2", diff --git a/packages/docusaurus-theme-common/package.json b/packages/docusaurus-theme-common/package.json index ac6dd3a14c..220ce0cae6 100644 --- a/packages/docusaurus-theme-common/package.json +++ b/packages/docusaurus-theme-common/package.json @@ -1,6 +1,6 @@ { "name": "@docusaurus/theme-common", - "version": "2.0.0-beta.14", + "version": "2.0.0-beta.15", "description": "Common code for Docusaurus themes.", "main": "./lib/index.js", "types": "./lib/index.d.ts", @@ -18,18 +18,18 @@ }, "license": "MIT", "dependencies": { - "@docusaurus/plugin-content-blog": "2.0.0-beta.14", - "@docusaurus/plugin-content-docs": "2.0.0-beta.14", - "@docusaurus/plugin-content-pages": "2.0.0-beta.14", + "@docusaurus/plugin-content-blog": "2.0.0-beta.15", + "@docusaurus/plugin-content-docs": "2.0.0-beta.15", + "@docusaurus/plugin-content-pages": "2.0.0-beta.15", "clsx": "^1.1.1", "parse-numeric-range": "^1.3.0", "tslib": "^2.3.1", "utility-types": "^3.10.0" }, "devDependencies": { - "@docusaurus/core": "2.0.0-beta.14", - "@docusaurus/module-type-aliases": "2.0.0-beta.14", - "@docusaurus/types": "2.0.0-beta.14", + "@docusaurus/core": "2.0.0-beta.15", + "@docusaurus/module-type-aliases": "2.0.0-beta.15", + "@docusaurus/types": "2.0.0-beta.15", "@testing-library/react-hooks": "^7.0.2", "fs-extra": "^10.0.0", "lodash": "^4.17.20" diff --git a/packages/docusaurus-theme-live-codeblock/package.json b/packages/docusaurus-theme-live-codeblock/package.json index 0ffe0b5b14..45ac58c657 100644 --- a/packages/docusaurus-theme-live-codeblock/package.json +++ b/packages/docusaurus-theme-live-codeblock/package.json @@ -1,6 +1,6 @@ { "name": "@docusaurus/theme-live-codeblock", - "version": "2.0.0-beta.14", + "version": "2.0.0-beta.15", "description": "Docusaurus live code block component.", "main": "lib/index.js", "publishConfig": { @@ -17,10 +17,10 @@ }, "license": "MIT", "dependencies": { - "@docusaurus/core": "2.0.0-beta.14", - "@docusaurus/theme-common": "2.0.0-beta.14", - "@docusaurus/theme-translations": "2.0.0-beta.14", - "@docusaurus/utils-validation": "2.0.0-beta.14", + "@docusaurus/core": "2.0.0-beta.15", + "@docusaurus/theme-common": "2.0.0-beta.15", + "@docusaurus/theme-translations": "2.0.0-beta.15", + "@docusaurus/utils-validation": "2.0.0-beta.15", "@philpl/buble": "^0.19.7", "clsx": "^1.1.1", "fs-extra": "^10.0.0", @@ -30,7 +30,7 @@ "tslib": "^2.3.1" }, "devDependencies": { - "@docusaurus/types": "2.0.0-beta.14", + "@docusaurus/types": "2.0.0-beta.15", "@types/buble": "^0.20.1" }, "peerDependencies": { diff --git a/packages/docusaurus-theme-search-algolia/package.json b/packages/docusaurus-theme-search-algolia/package.json index ab5bb1065e..d10c77ea82 100644 --- a/packages/docusaurus-theme-search-algolia/package.json +++ b/packages/docusaurus-theme-search-algolia/package.json @@ -1,6 +1,6 @@ { "name": "@docusaurus/theme-search-algolia", - "version": "2.0.0-beta.14", + "version": "2.0.0-beta.15", "description": "Algolia search component for Docusaurus.", "main": "lib/index.js", "exports": { @@ -25,12 +25,12 @@ }, "dependencies": { "@docsearch/react": "^3.0.0-alpha.39", - "@docusaurus/core": "2.0.0-beta.14", - "@docusaurus/logger": "2.0.0-beta.14", - "@docusaurus/theme-common": "2.0.0-beta.14", - "@docusaurus/theme-translations": "2.0.0-beta.14", - "@docusaurus/utils": "2.0.0-beta.14", - "@docusaurus/utils-validation": "2.0.0-beta.14", + "@docusaurus/core": "2.0.0-beta.15", + "@docusaurus/logger": "2.0.0-beta.15", + "@docusaurus/theme-common": "2.0.0-beta.15", + "@docusaurus/theme-translations": "2.0.0-beta.15", + "@docusaurus/utils": "2.0.0-beta.15", + "@docusaurus/utils-validation": "2.0.0-beta.15", "algoliasearch": "^4.10.5", "algoliasearch-helper": "^3.5.5", "clsx": "^1.1.1", @@ -40,7 +40,7 @@ "utility-types": "^3.10.0" }, "devDependencies": { - "@docusaurus/module-type-aliases": "2.0.0-beta.14", + "@docusaurus/module-type-aliases": "2.0.0-beta.15", "fs-extra": "^10.0.0" }, "peerDependencies": { diff --git a/packages/docusaurus-theme-translations/package.json b/packages/docusaurus-theme-translations/package.json index 0bd360b662..3e6eb9888e 100644 --- a/packages/docusaurus-theme-translations/package.json +++ b/packages/docusaurus-theme-translations/package.json @@ -1,6 +1,6 @@ { "name": "@docusaurus/theme-translations", - "version": "2.0.0-beta.14", + "version": "2.0.0-beta.15", "description": "Docusaurus theme translations.", "main": "lib/index.js", "types": "lib/index.d.ts", @@ -23,8 +23,8 @@ "tslib": "^2.3.1" }, "devDependencies": { - "@docusaurus/core": "2.0.0-beta.14", - "@docusaurus/logger": "2.0.0-beta.14", + "@docusaurus/core": "2.0.0-beta.15", + "@docusaurus/logger": "2.0.0-beta.15", "lodash": "^4.17.20" }, "engines": { diff --git a/packages/docusaurus-types/package.json b/packages/docusaurus-types/package.json index accb99caea..347b485230 100644 --- a/packages/docusaurus-types/package.json +++ b/packages/docusaurus-types/package.json @@ -1,6 +1,6 @@ { "name": "@docusaurus/types", - "version": "2.0.0-beta.14", + "version": "2.0.0-beta.15", "description": "Common types for Docusaurus packages.", "types": "./src/index.d.ts", "publishConfig": { diff --git a/packages/docusaurus-utils-common/package.json b/packages/docusaurus-utils-common/package.json index 004dbdd93a..e9711757a0 100644 --- a/packages/docusaurus-utils-common/package.json +++ b/packages/docusaurus-utils-common/package.json @@ -1,6 +1,6 @@ { "name": "@docusaurus/utils-common", - "version": "2.0.0-beta.14", + "version": "2.0.0-beta.15", "description": "Common (Node/Browser) utility functions for Docusaurus packages.", "main": "./lib/index.js", "types": "./lib/index.d.ts", @@ -21,7 +21,7 @@ "tslib": "^2.3.1" }, "devDependencies": { - "@docusaurus/types": "2.0.0-beta.14" + "@docusaurus/types": "2.0.0-beta.15" }, "engines": { "node": ">=14" diff --git a/packages/docusaurus-utils-validation/package.json b/packages/docusaurus-utils-validation/package.json index bc6b3bbe5e..312e5aca2e 100644 --- a/packages/docusaurus-utils-validation/package.json +++ b/packages/docusaurus-utils-validation/package.json @@ -1,6 +1,6 @@ { "name": "@docusaurus/utils-validation", - "version": "2.0.0-beta.14", + "version": "2.0.0-beta.15", "description": "Node validation utility functions for Docusaurus packages.", "main": "./lib/index.js", "types": "./lib/index.d.ts", @@ -18,8 +18,8 @@ }, "license": "MIT", "dependencies": { - "@docusaurus/logger": "2.0.0-beta.14", - "@docusaurus/utils": "2.0.0-beta.14", + "@docusaurus/logger": "2.0.0-beta.15", + "@docusaurus/utils": "2.0.0-beta.15", "joi": "^17.4.2", "tslib": "^2.3.1" }, diff --git a/packages/docusaurus-utils/package.json b/packages/docusaurus-utils/package.json index e7df00d69e..c3d7b5d9ab 100644 --- a/packages/docusaurus-utils/package.json +++ b/packages/docusaurus-utils/package.json @@ -1,6 +1,6 @@ { "name": "@docusaurus/utils", - "version": "2.0.0-beta.14", + "version": "2.0.0-beta.15", "description": "Node utility functions for Docusaurus packages.", "main": "./lib/index.js", "types": "./lib/index.d.ts", @@ -18,7 +18,7 @@ }, "license": "MIT", "dependencies": { - "@docusaurus/logger": "2.0.0-beta.14", + "@docusaurus/logger": "2.0.0-beta.15", "@mdx-js/runtime": "^1.6.22", "@svgr/webpack": "^6.0.0", "file-loader": "^6.2.0", @@ -39,7 +39,7 @@ "node": ">=14" }, "devDependencies": { - "@docusaurus/types": "2.0.0-beta.14", + "@docusaurus/types": "2.0.0-beta.15", "@types/dedent": "^0.7.0", "@types/github-slugger": "^1.3.0", "@types/micromatch": "^4.0.2", diff --git a/packages/docusaurus/package.json b/packages/docusaurus/package.json index f46997cba1..f423227c57 100644 --- a/packages/docusaurus/package.json +++ b/packages/docusaurus/package.json @@ -1,7 +1,7 @@ { "name": "@docusaurus/core", "description": "Easy to Maintain Open Source Documentation Websites", - "version": "2.0.0-beta.14", + "version": "2.0.0-beta.15", "license": "MIT", "publishConfig": { "access": "public" @@ -41,13 +41,13 @@ "@babel/runtime": "^7.16.3", "@babel/runtime-corejs3": "^7.16.3", "@babel/traverse": "^7.16.3", - "@docusaurus/cssnano-preset": "2.0.0-beta.14", - "@docusaurus/logger": "2.0.0-beta.14", - "@docusaurus/mdx-loader": "2.0.0-beta.14", + "@docusaurus/cssnano-preset": "2.0.0-beta.15", + "@docusaurus/logger": "2.0.0-beta.15", + "@docusaurus/mdx-loader": "2.0.0-beta.15", "@docusaurus/react-loadable": "5.5.2", - "@docusaurus/utils": "2.0.0-beta.14", - "@docusaurus/utils-common": "2.0.0-beta.14", - "@docusaurus/utils-validation": "2.0.0-beta.14", + "@docusaurus/utils": "2.0.0-beta.15", + "@docusaurus/utils-common": "2.0.0-beta.15", + "@docusaurus/utils-validation": "2.0.0-beta.15", "@slorber/static-site-generator-webpack-plugin": "^4.0.0", "@svgr/webpack": "^6.0.0", "autoprefixer": "^10.3.5", @@ -105,8 +105,8 @@ "webpackbar": "^5.0.2" }, "devDependencies": { - "@docusaurus/module-type-aliases": "2.0.0-beta.14", - "@docusaurus/types": "2.0.0-beta.14", + "@docusaurus/module-type-aliases": "2.0.0-beta.15", + "@docusaurus/types": "2.0.0-beta.15", "@types/copy-webpack-plugin": "^8.0.1", "@types/detect-port": "^1.3.0", "@types/mini-css-extract-plugin": "^1.4.3", diff --git a/packages/lqip-loader/package.json b/packages/lqip-loader/package.json index 15836d4550..d10149f1a4 100644 --- a/packages/lqip-loader/package.json +++ b/packages/lqip-loader/package.json @@ -1,6 +1,6 @@ { "name": "@docusaurus/lqip-loader", - "version": "2.0.0-beta.14", + "version": "2.0.0-beta.15", "description": "Low Quality Image Placeholders (LQIP) loader for webpack.", "main": "lib/index.js", "publishConfig": { diff --git a/packages/stylelint-copyright/package.json b/packages/stylelint-copyright/package.json index ded739db8a..c7138d767b 100644 --- a/packages/stylelint-copyright/package.json +++ b/packages/stylelint-copyright/package.json @@ -1,6 +1,6 @@ { "name": "stylelint-copyright", - "version": "2.0.0-beta.14", + "version": "2.0.0-beta.15", "description": "Stylelint plugin to check CSS files for a copyright header.", "main": "index.js", "license": "MIT", diff --git a/website/package.json b/website/package.json index 337d8823a8..1ac8c4bc22 100644 --- a/website/package.json +++ b/website/package.json @@ -1,6 +1,6 @@ { "name": "website", - "version": "2.0.0-beta.14", + "version": "2.0.0-beta.15", "private": true, "scripts": { "docusaurus": "docusaurus", @@ -32,15 +32,15 @@ "dependencies": { "@crowdin/cli": "^3.7.1", "@crowdin/crowdin-api-client": "^1.10.6", - "@docusaurus/core": "2.0.0-beta.14", - "@docusaurus/plugin-client-redirects": "2.0.0-beta.14", - "@docusaurus/plugin-ideal-image": "2.0.0-beta.14", - "@docusaurus/plugin-pwa": "2.0.0-beta.14", - "@docusaurus/preset-classic": "2.0.0-beta.14", - "@docusaurus/remark-plugin-npm2yarn": "2.0.0-beta.14", - "@docusaurus/theme-common": "2.0.0-beta.14", - "@docusaurus/theme-live-codeblock": "2.0.0-beta.14", - "@docusaurus/utils": "2.0.0-beta.14", + "@docusaurus/core": "2.0.0-beta.15", + "@docusaurus/plugin-client-redirects": "2.0.0-beta.15", + "@docusaurus/plugin-ideal-image": "2.0.0-beta.15", + "@docusaurus/plugin-pwa": "2.0.0-beta.15", + "@docusaurus/preset-classic": "2.0.0-beta.15", + "@docusaurus/remark-plugin-npm2yarn": "2.0.0-beta.15", + "@docusaurus/theme-common": "2.0.0-beta.15", + "@docusaurus/theme-live-codeblock": "2.0.0-beta.15", + "@docusaurus/utils": "2.0.0-beta.15", "@popperjs/core": "^2.10.2", "clsx": "^1.1.1", "color": "^4.0.1", diff --git a/website/versioned_docs/version-2.0.0-beta.13/advanced/routing.md b/website/versioned_docs/version-2.0.0-beta.13/advanced/routing.md deleted file mode 100644 index 3f39935659..0000000000 --- a/website/versioned_docs/version-2.0.0-beta.13/advanced/routing.md +++ /dev/null @@ -1,17 +0,0 @@ -# Routing - -This page is only accessible through version-switching. It shows how a versioned doc file becomes a webpage. - -```mdx-code-block -import {useLatestVersion, useActiveDocContext} from '@docusaurus/plugin-content-docs/client'; -import {useLocation} from '@docusaurus/router'; - -export const URLPath = () => {useLocation().pathname}; - -export const FilePath = () => { - const currentVersion = useActiveDocContext('default').activeVersion.name; - return {currentVersion === 'current' ? './docs/' : `./versioned_docs/version-${currentVersion}/`}advanced/routing.md; -} -``` - -This page, , is generated from the file at . The component used is `@theme/DocItem`. diff --git a/website/versioned_docs/version-2.0.0-beta.13/api/plugins/plugin-client-redirects.md b/website/versioned_docs/version-2.0.0-beta.13/api/plugins/plugin-client-redirects.md deleted file mode 100644 index fca62c4555..0000000000 --- a/website/versioned_docs/version-2.0.0-beta.13/api/plugins/plugin-client-redirects.md +++ /dev/null @@ -1,130 +0,0 @@ ---- -sidebar_position: 4 -id: plugin-client-redirects -title: '📦 plugin-client-redirects' -slug: '/api/plugins/@docusaurus/plugin-client-redirects' ---- - -Docusaurus Plugin to generate **client-side redirects**. - -This plugin will write additional HTML pages to your static site, that redirects the user to your existing Docusaurus pages with JavaScript. - -:::note - -This plugin only create redirects for the production build. - -::: - -:::caution - -It is better to use server-side redirects whenever possible. - -Before using this plugin, you should look if your hosting provider doesn't offer this feature. - -::: - -## Installation {#installation} - -```bash npm2yarn -npm install --save @docusaurus/plugin-client-redirects -``` - -## Configuration {#configuration} - -Main usecase: you have `/myDocusaurusPage`, and you want to redirect to this page from `/myDocusaurusPage.html`: - -```js title="docusaurus.config.js" -module.exports = { - plugins: [ - [ - '@docusaurus/plugin-client-redirects', - { - fromExtensions: ['html'], - }, - ], - ], -}; -``` - -Second usecase: you have `/myDocusaurusPage.html`, and you want to redirect to this page from `/myDocusaurusPage`. - -```js title="docusaurus.config.js" -module.exports = { - plugins: [ - [ - '@docusaurus/plugin-client-redirects', - { - toExtensions: ['html'], - }, - ], - ], -}; -``` - -For custom redirect logic, provide your own `createRedirects` function. - -Let's imagine you change the url of an existing page, you might want to make sure the old url still works: - -```js title="docusaurus.config.js" -module.exports = { - plugins: [ - [ - '@docusaurus/plugin-client-redirects', - { - redirects: [ - { - to: '/docs/newDocPath', // string - from: ['/docs/oldDocPathFrom2019', '/docs/legacyDocPathFrom2016'], // string | string[] - }, - ], - }, - ], - ], -}; -``` - -It's possible to use a function to create the redirects for each existing path: - -```js title="docusaurus.config.js" -module.exports = { - plugins: [ - [ - '@docusaurus/plugin-client-redirects', - { - createRedirects: function (existingPath) { - if (existingPath === '/docs/newDocPath') { - return ['/docs/oldDocPathFrom2019', '/docs/legacyDocPathFrom2016']; // string | string[] - } - }, - }, - ], - ], -}; -``` - -Finally, it's possible to use all options at the same time: - -```js title="docusaurus.config.js" -module.exports = { - plugins: [ - [ - '@docusaurus/plugin-client-redirects', - { - fromExtensions: ['html', 'htm'], - toExtensions: ['exe', 'zip'], - redirects: [ - { - to: '/docs/newDocPath', - from: '/docs/oldDocPath', - }, - ], - createRedirects: function (existingPath) { - if (existingPath === '/docs/newDocPath2') { - return ['/docs/oldDocPath2']; - } - }, - }, - ], - ], -}; -``` diff --git a/website/versioned_docs/version-2.0.0-beta.13/api/plugins/plugin-debug.md b/website/versioned_docs/version-2.0.0-beta.13/api/plugins/plugin-debug.md deleted file mode 100644 index 43f57305b5..0000000000 --- a/website/versioned_docs/version-2.0.0-beta.13/api/plugins/plugin-debug.md +++ /dev/null @@ -1,40 +0,0 @@ ---- -sidebar_position: 5 -id: plugin-debug -title: '📦 plugin-debug' -slug: '/api/plugins/@docusaurus/plugin-debug' ---- - -The debug plugin will display useful debug information at [http://localhost:3000/\_\_docusaurus/debug](http://localhost:3000/__docusaurus/debug). - -It is mostly useful for plugin authors, that will be able to inspect more easily the content of the `.docusaurus` folder (like the creates routes), but also be able to inspect data structures that are never written to disk, like the plugin data loaded through the `contentLoaded` lifecycle. - -:::note - -If you report a bug, we will probably ask you to have this plugin turned on in the production, so that we can inspect your deployment config more easily. - -If you don't have any sensitive information, you can keep it on in production [like we do](http://docusaurus.io/__docusaurus/debug). - -::: - -## Installation {#installation} - -```bash npm2yarn -npm install --save @docusaurus/plugin-debug -``` - -:::tip - -If you have installed `@docusaurus/preset-classic`, you don't need to install it as a dependency. You can also configure it through the [classic preset options](presets.md#docusauruspreset-classic) instead of doing it like below. - -By default, it's enabled in dev, and disabled in prod, to avoid exposing potentially sensitive information. - -::: - -## Configuration {#configuration} - -```js title="docusaurus.config.js" -module.exports = { - plugins: ['@docusaurus/plugin-debug'], -}; -``` diff --git a/website/versioned_docs/version-2.0.0-beta.13/api/plugins/plugin-google-analytics.md b/website/versioned_docs/version-2.0.0-beta.13/api/plugins/plugin-google-analytics.md deleted file mode 100644 index c38a45394b..0000000000 --- a/website/versioned_docs/version-2.0.0-beta.13/api/plugins/plugin-google-analytics.md +++ /dev/null @@ -1,94 +0,0 @@ ---- -sidebar_position: 6 -id: plugin-google-analytics -title: '📦 plugin-google-analytics' -slug: '/api/plugins/@docusaurus/plugin-google-analytics' ---- - -The default [Google Analytics](https://developers.google.com/analytics/devguides/collection/analyticsjs/) plugin. It is a JavaScript library for measuring how users interact with your website **in the production build**. If you are using Google Analytics 4 you might need to consider using [plugin-google-gtag](./plugin-google-gtag.md) instead. - -## Installation {#installation} - -```bash npm2yarn -npm install --save @docusaurus/plugin-google-analytics -``` - -:::tip - -If you have installed `@docusaurus/preset-classic`, you don't need to install it as a dependency. - -::: - -## Configuration {#configuration} - -Accepted fields: - - - -| Name | Type | Default | Description | -| --- | --- | --- | --- | -| `trackingID` | `string` | **Required** | The tracking ID of your analytics service. | -| `anonymizeIP` | `boolean` | `false` | Whether the IP should be anonymized when sending requests. | - - - -## Example configuration {#ex-config} - -Here's an example configuration object. - -You can provide it as [preset options](#ex-config-preset) or [plugin options](#ex-config-plugin). - -:::tip - -Most Docusaurus users configure this plugin through the [preset options](#ex-config-preset). - -::: - -```js -const config = { - trackingID: 'UA-141789564-1', - anonymizeIP: true, -}; -``` - -### Preset options {#ex-config-preset} - -If you use a preset, configure this plugin through the [preset options](presets.md#docusauruspreset-classic): - -```js title="docusaurus.config.js" -module.exports = { - presets: [ - [ - '@docusaurus/preset-classic', - { - // highlight-start - googleAnalytics: { - trackingID: 'UA-141789564-1', - anonymizeIP: true, - }, - // highlight-end - }, - ], - ], -}; -``` - -### Plugin options {#ex-config-plugin} - -If you are using a standalone plugin, provide options directly to the plugin: - -```js title="docusaurus.config.js" -module.exports = { - plugins: [ - [ - '@docusaurus/plugin-google-analytics', - // highlight-start - { - trackingID: 'UA-141789564-1', - anonymizeIP: true, - }, - // highlight-end - ], - ], -}; -``` diff --git a/website/versioned_docs/version-2.0.0-beta.13/api/plugins/plugin-google-gtag.md b/website/versioned_docs/version-2.0.0-beta.13/api/plugins/plugin-google-gtag.md deleted file mode 100644 index 756dc83fd4..0000000000 --- a/website/versioned_docs/version-2.0.0-beta.13/api/plugins/plugin-google-gtag.md +++ /dev/null @@ -1,100 +0,0 @@ ---- -sidebar_position: 7 -id: plugin-google-gtag -title: '📦 plugin-google-gtag' -slug: '/api/plugins/@docusaurus/plugin-google-gtag' ---- - -The default [Global Site Tag (gtag.js)](https://developers.google.com/analytics/devguides/collection/gtagjs/) plugin. It is a JavaScript tagging framework and API that allows you to send event data to Google Analytics, Google Ads, and Google Marketing Platform, **in the production build**. This section describes how to configure a Docusaurus site to enable global site tag for Google Analytics. - -:::tip - -You can use [Google's Tag Assistant](https://tagassistant.google.com/) tool to check if your gtag is set up correctly! - -::: - -## Installation {#installation} - -```bash npm2yarn -npm install --save @docusaurus/plugin-google-gtag -``` - -:::tip - -If you have installed `@docusaurus/preset-classic`, you don't need to install it as a dependency. - -::: - -## Configuration {#configuration} - -Accepted fields: - - - -| Name | Type | Default | Description | -| --- | --- | --- | --- | -| `trackingID` | `string` | **Required** | The tracking ID of your gtag service. | -| `anonymizeIP` | `boolean` | `false` | Whether the IP should be anonymized when sending requests. | - - - -## Example configuration {#ex-config} - -Here's an example configuration object. - -You can provide it as [preset options](#ex-config-preset) or [plugin options](#ex-config-plugin). - -:::tip - -Most Docusaurus users configure this plugin through the [preset options](#ex-config-preset). - -::: - -```js -const config = { - trackingID: 'UA-141789564-1', - anonymizeIP: true, -}; -``` - -### Preset options {#ex-config-preset} - -If you use a preset, configure this plugin through the [preset options](presets.md#docusauruspreset-classic): - -```js title="docusaurus.config.js" -module.exports = { - presets: [ - [ - '@docusaurus/preset-classic', - { - // highlight-start - gtag: { - trackingID: 'UA-141789564-1', - anonymizeIP: true, - }, - // highlight-end - }, - ], - ], -}; -``` - -### Plugin options {#ex-config-plugin} - -If you are using a standalone plugin, provide options directly to the plugin: - -```js title="docusaurus.config.js" -module.exports = { - plugins: [ - [ - '@docusaurus/plugin-google-gtag', - // highlight-start - { - trackingID: 'UA-141789564-1', - anonymizeIP: true, - }, - // highlight-end - ], - ], -}; -``` diff --git a/website/versioned_docs/version-2.0.0-beta.13/api/plugins/plugin-ideal-image.md b/website/versioned_docs/version-2.0.0-beta.13/api/plugins/plugin-ideal-image.md deleted file mode 100644 index 363946e698..0000000000 --- a/website/versioned_docs/version-2.0.0-beta.13/api/plugins/plugin-ideal-image.md +++ /dev/null @@ -1,53 +0,0 @@ ---- -sidebar_position: 8 -id: plugin-ideal-image -title: '📦 plugin-ideal-image' -slug: '/api/plugins/@docusaurus/plugin-ideal-image' ---- - -Docusaurus Plugin to generate an almost ideal image (responsive, lazy-loading, and low quality placeholder) **in the production builds**. - -## Installation {#installation} - -```bash npm2yarn -npm install --save @docusaurus/plugin-ideal-image -``` - -## Configuration {#configuration} - -Modify your `docusaurus.config.js` - -```js {3} -module.exports = { - ... - plugins: ['@docusaurus/plugin-ideal-image'], - ... -} -``` - -## Usage {#usage} - -This plugin supports the PNG and JPG formats only. - -```jsx -import Image from '@theme/IdealImage'; -import thumbnail from './path/to/img.png'; - -// your React code - - -// or - -``` - -## Options {#options} - -| Option | Type | Default | Description | -| --- | --- | --- | --- | -| `name` | `string` | `ideal-img/[name].[hash:hex:7].[width].[ext]` | Filename template for output files. | -| `sizes` | `array` | _original size_ | Specify all widths you want to use. If a specified size exceeds the original image's width, the latter will be used (i.e. images won't be scaled up). | -| `size` | `integer` | _original size_ | Specify one width you want to use; if the specified size exceeds the original image's width, the latter will be used (i.e. images won't be scaled up) | -| `min` | `integer` | | As an alternative to manually specifying `sizes`, you can specify `min`, `max` and `steps`, and the sizes will be generated for you. | -| `max` | `integer` | | See `min` above | -| `steps` | `integer` | `4` | Configure the number of images generated between `min` and `max` (inclusive) | -| `quality` | `integer` | `85` | JPEG compression quality | diff --git a/website/versioned_docs/version-2.0.0-beta.13/api/plugins/plugin-sitemap.md b/website/versioned_docs/version-2.0.0-beta.13/api/plugins/plugin-sitemap.md deleted file mode 100644 index 5e61a00b76..0000000000 --- a/website/versioned_docs/version-2.0.0-beta.13/api/plugins/plugin-sitemap.md +++ /dev/null @@ -1,37 +0,0 @@ ---- -sidebar_position: 10 -id: plugin-sitemap -title: '📦 plugin-sitemap' -slug: '/api/plugins/@docusaurus/plugin-sitemap' ---- - -This plugin creates sitemap for your site so that search engine crawlers can crawl your site more accurately. - -## Installation {#installation} - -```bash npm2yarn -npm install --save @docusaurus/plugin-sitemap -``` - -:::tip - -If you have installed `@docusaurus/preset-classic`, you don't need to install it as a dependency. You can also configure it through the [classic preset options](presets.md#docusauruspreset-classic) instead of doing it like below. - -::: - -## Configuration {#configuration} - -```js title="docusaurus.config.js" -module.exports = { - plugins: [ - [ - '@docusaurus/plugin-sitemap', - { - changefreq: 'weekly', - priority: 0.5, - trailingSlash: false, - }, - ], - ], -}; -``` diff --git a/website/versioned_docs/version-2.0.0-beta.13/guides/docs/docs-introduction.md b/website/versioned_docs/version-2.0.0-beta.13/guides/docs/docs-introduction.md deleted file mode 100644 index 0612e7b089..0000000000 --- a/website/versioned_docs/version-2.0.0-beta.13/guides/docs/docs-introduction.md +++ /dev/null @@ -1,86 +0,0 @@ ---- -id: introduction -title: Docs Introduction -sidebar_label: Introduction -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. - -For example, `greeting.md` id is `greeting` and `guide/hello.md` id is `guide/hello`. - -```bash -website # Root directory of your site -└── docs -   ├── greeting.md - └── guide - └── hello.md -``` - -However, the **last part** of the `id` can be defined by user in the front matter. For example, if `guide/hello.md`'s content is defined as below, its final `id` is `guide/part1`. - -```yml ---- -id: part1 ---- -Lorem ipsum -``` - -If you want more control over the last part of the document URL, it is possible to add a `slug` (defaults to the `id`). - -```yml ---- -id: part1 -slug: part1.html ---- -Lorem ipsum -``` - -:::note - -It is possible to use: - -- absolute slugs: `slug: /mySlug`, `slug: /`... -- relative slugs: `slug: mySlug`, `slug: ./../mySlug`... - -::: - -## Home page docs {#home-page-docs} - -If you want a document to be available at the root, and have a path like `https://docusaurus.io/docs/`, you can use the slug frontmatter: - -```yml ---- -id: my-home-doc -slug: / ---- -Lorem ipsum -``` - -## Docs-only mode {#docs-only-mode} - -If you only want the documentation feature, you can run your Docusaurus 2 site without a landing page and display your documentation page as the index page instead. - -To enable docs-only mode, set the docs plugin `routeBasePath: '/'`, and use the frontmatter `slug: /` on the document that should be the index page ([more info](#home-page-docs)). - -:::caution - -You should delete the existing homepage at `./src/pages/index.js`, or else there will be two files mapping to the same route! - -::: - -:::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.mdx#blog-only-mode). - -::: diff --git a/website/versioned_docs/version-2.0.0-beta.13/guides/docs/sidebar.md b/website/versioned_docs/version-2.0.0-beta.13/guides/docs/sidebar.md deleted file mode 100644 index f430b78c71..0000000000 --- a/website/versioned_docs/version-2.0.0-beta.13/guides/docs/sidebar.md +++ /dev/null @@ -1,809 +0,0 @@ ---- -id: sidebar -title: Sidebar -toc_max_heading_level: 5 -slug: /sidebar ---- - -Creating a sidebar is useful to: - -- Group multiple **related documents** -- **Display a sidebar** on each of those documents -- Provide a **paginated navigation**, with next/previous button - -To use sidebars on your Docusaurus site: - -1. Define a file that exports a [sidebar object](#sidebar-object). -1. Pass this object into the `@docusaurus/plugin-docs` plugin directly or via `@docusaurus/preset-classic`. - -```js title="docusaurus.config.js" -module.exports = { - presets: [ - [ - '@docusaurus/preset-classic', - { - docs: { - // highlight-next-line - sidebarPath: require.resolve('./sidebars.js'), - }, - }, - ], - ], -}; -``` - -## Default sidebar - -By default, Docusaurus [automatically generates a sidebar](#sidebar-item-autogenerated) for you, by using the filesystem structure of the `docs` folder: - -```js title="sidebars.js" -module.exports = { - mySidebar: [ - { - type: 'autogenerated', - dirName: '.', // generate sidebar slice from the docs folder (or versioned_docs/) - }, - ], -}; -``` - -You can also define your sidebars explicitly. - -## Sidebar object {#sidebar-object} - -A sidebar is a **tree of [sidebar items](#understanding-sidebar-items)**. - -```typescript -type Sidebar = - // Normal syntax - | SidebarItem[] - - // Shorthand syntax - | Record< - string, // category label - SidebarItem[] // category items - >; -``` - -A sidebars file can contain **multiple sidebar objects**. - -```typescript -type SidebarsFile = Record< - string, // sidebar id - Sidebar ->; -``` - -Example: - -```js title="sidebars.js" -module.exports = { - mySidebar: [ - { - type: 'category', - label: 'Getting Started', - items: ['doc1'], - }, - { - type: 'category', - label: 'Docusaurus', - items: ['doc2', 'doc3'], - }, - ], -}; -``` - -Notice the following: - -- There is a single sidebar `mySidebar`, containing 5 [sidebar items](#understanding-sidebar-items) -- `Getting Started` and `Docusaurus` are sidebar categories -- `doc1`, `doc2` and `doc3` are sidebar documents - -:::tip - -Use the **shorthand syntax** to express this sidebar more concisely: - -```js title="sidebars.js" -module.exports = { - mySidebar: { - 'Getting started': ['doc1'], - Docusaurus: ['doc2', 'doc3'], - }, -}; -``` - -::: - -## Using multiple sidebars {#using-multiple-sidebars} - -You can create a sidebar for each **set of Markdown files** that you want to **group together**. - -:::tip - -The Docusaurus site is a good example of using multiple sidebars: - -- [Docs](../../introduction.md) -- [API](../../cli.md) - -::: - -Example: - -```js title="sidebars.js" -module.exports = { - tutorialSidebar: { - 'Category A': ['doc1', 'doc2'], - }, - apiSidebar: ['doc3', 'doc4'], -}; -``` - -:::note - -The keys `tutorialSidebar` and `apiSidebar` are sidebar **technical ids** and do not matter much. - -::: - -When browsing: - -- `doc1` or `doc2`: the `tutorialSidebar` will be displayed -- `doc3` or `doc4`: the `apiSidebar` will be displayed - -A **paginated navigation** link documents inside the same sidebar with **next and previous buttons**. - -## Understanding sidebar items {#understanding-sidebar-items} - -`SidebarItem` is an item defined in a Sidebar tree. - -There are different types of sidebar items: - -- **[Doc](#sidebar-item-doc)**: link to a doc page, assigning it to the sidebar -- **[Ref](#sidebar-item-ref)**: link to a doc page, without assigning it to the sidebar -- **[Link](#sidebar-item-link)**: link to any internal or external page -- **[Category](#sidebar-item-category)**: create a hierarchy of sidebar items -- **[Autogenerated](#sidebar-item-autogenerated)**: generate a sidebar slice automatically - -### Doc: link to a doc {#sidebar-item-doc} - -Use the `doc` type to link to a doc page and assign that doc to a sidebar: - -```typescript -type SidebarItemDoc = - // Normal syntax - | { - type: 'doc'; - id: string; - label: string; // Sidebar label text - className?: string; // Class name for sidebar label - } - - // Shorthand syntax - | string; // docId shortcut -``` - -Example: - -```js title="sidebars.js" -module.exports = { - mySidebar: [ - // Normal syntax: - // highlight-start - { - type: 'doc', - id: 'doc1', // document id - label: 'Getting started', // sidebar label - }, - // highlight-end - - // Shorthand syntax: - // highlight-start - 'doc2', // document id - // highlight-end - ], -}; -``` - -The `sidebar_label` markdown frontmatter has a higher precedence over the `label` key in `SidebarItemDoc`. - -:::note - -Don't assign the same doc to multiple sidebars: use a [ref](#sidebar-item-ref) instead. - -::: - -### Ref: link to a doc, without sidebar {#sidebar-item-ref} - -Use the `ref` type to link to a doc page without assigning it to a sidebar. - -```typescript -type SidebarItemRef = { - type: 'ref'; - id: string; -}; -``` - -Example: - -```js title="sidebars.js" -module.exports = { - mySidebar: [ - { - type: 'ref', - id: 'doc1', // Document id (string). - }, - ], -}; -``` - -When browsing `doc1`, Docusaurus **will not display** the `mySidebar` sidebar. - -### Link: link to any page {#sidebar-item-link} - -Use the `link` type to link to any page (internal or external) that is not a doc. - -```typescript -type SidebarItemLink = { - type: 'link'; - label: string; - href: string; - className?: string; -}; -``` - -Example: - -```js title="sidebars.js" -module.exports = { - myLinksSidebar: [ - // highlight-start - // External link - { - type: 'link', - label: 'Facebook', // The link label - href: 'https://facebook.com', // The external URL - }, - // highlight-end - - // highlight-start - // Internal link - { - type: 'link', - label: 'Home', // The link label - href: '/', // The internal path - }, - // highlight-end - ], -}; -``` - -### Category: create a hierarchy {#sidebar-item-category} - -Use the `category` type to create a hierarchy of sidebar items. - -```typescript -type SidebarItemCategory = { - type: 'category'; - label: string; // Sidebar label text. - items: SidebarItem[]; // Array of sidebar items. - className?: string; - - // Category options: - collapsible: boolean; // Set the category to be collapsible - collapsed: boolean; // Set the category to be initially collapsed or open by default - link: SidebarItemCategoryLinkDoc | SidebarItemCategoryLinkGeneratedIndex; -}; -``` - -Example: - -```js title="sidebars.js" -module.exports = { - docs: [ - { - type: 'category', - label: 'Guides', - collapsible: true, - collapsed: false, - items: [ - 'creating-pages', - { - type: 'category', - label: 'Docs', - items: ['introduction', 'sidebar', 'markdown-features', 'versioning'], - }, - ], - }, - ], -}; -``` - -:::tip - -Use the **shorthand syntax** when you don't need **category options**: - -```js title="sidebars.js" -module.exports = { - docs: { - Guides: [ - 'creating-pages', - { - Docs: ['introduction', 'sidebar', 'markdown-features', 'versioning'], - }, - ], - }, -}; -``` - -::: - -#### Category links {#category-link} - -With category links, clicking on a category can navigate you to another page. - -:::tip - -Use category links to introduce a category of documents. - -::: - -##### Doc link {#category-doc-link} - -A category can link to an existing document. - -```js title="sidebars.js" -module.exports = { - docs: [ - { - type: 'category', - label: 'Guides', - // highlight-start - link: {type: 'doc', id: 'introduction'}, - // highlight-end - items: ['pages', 'docs', 'blog', 'search'], - }, - ], -}; -``` - -See it in action in the [i18n introduction page](../../i18n/i18n-introduction.md). - -##### Generated index page {#generated-index-page} - -You can auto-generate an index page that displays all the direct children of this category. The `slug` allows you to customize the generated page's route, which defaults to `/category/{{category name}}`. - -```js title="sidebars.js" -module.exports = { - docs: [ - { - type: 'category', - label: 'Guides', - // highlight-start - link: { - type: 'generated-index', - title: 'Docusaurus Guides', - description: 'Learn about the most important Docusaurus concepts!', - slug: '/category/docusaurus-guides', - }, - // highlight-end - items: ['pages', 'docs', 'blog', 'search'], - }, - ], -}; -``` - -See it in action in the [Docusaurus Guides pages](/docs/category/guides). - -:::tip - -Use `generated-index` links as a quick way to get an introductory document. - -::: - -#### Collapsible categories {#collapsible-categories} - -We support the option to expand/collapse categories. Categories are collapsible by default, but you can disable collapsing with `collapsible: false`. - -```js title="sidebars.js" -module.exports = { - docs: [ - { - type: 'category', - label: 'Guides', - items: [ - 'creating-pages', - { - type: 'category', - // highlight-next-line - collapsible: false, - label: 'Docs', - items: ['introduction', 'sidebar', 'markdown-features', 'versioning'], - }, - ], - }, - ], -}; -``` - -To make all categories non-collapsible by default, set the `sidebarCollapsible` option in `plugin-docs` to `false`: - -```js title="docusaurus.config.js" -module.exports = { - presets: [ - [ - '@docusaurus/preset-classic', - { - docs: { - // highlight-next-line - sidebarCollapsible: false, - }, - }, - ], - ], -}; -``` - -:::note - -The option in `sidebars.js` takes precedence over plugin configuration, so it is possible to make certain categories collapsible when `sidebarCollapsible` is set to `false` globally. - -::: - -#### Expanded categories by default {#expanded-categories-by-default} - -Collapsible categories are collapsed by default. If you want them to be expanded on first render, you can set `collapsed` to `false`: - -```js title="sidebars.js" -module.exports = { - docs: { - Guides: [ - 'creating-pages', - { - type: 'category', - label: 'Docs', - // highlight-next-line - collapsed: false, - items: ['markdown-features', 'sidebar', 'versioning'], - }, - ], - }, -}; -``` - -Similar to `collapsible`, you can also set the global configuration `options.sidebarCollapsed` to `false`. Individual `collapsed` options in `sidebars.js` will still take precedence over this configuration. - -```js title="docusaurus.config.js" -module.exports = { - presets: [ - [ - '@docusaurus/preset-classic', - { - docs: { - // highlight-next-line - sidebarCollapsed: false, - }, - }, - ], - ], -}; -``` - -:::caution - -When a category has `collapsed: true` but `collapsible: false` (either through `sidebars.js` or through plugin configuration), the latter takes precedence and the category is still rendered as expanded. - -::: - -### Autogenerated: generate a sidebar {#sidebar-item-autogenerated} - -Docusaurus can **create a sidebar automatically** from your **filesystem structure**: each folder creates a sidebar category. - -An `autogenerated` item is converted by Docusaurus to a **sidebar slice**: a list of items of type `doc` and `category`. - -```typescript -type SidebarItemAutogenerated = { - type: 'autogenerated'; - dirName: string; // Source folder to generate the sidebar slice from (relative to docs) -}; -``` - -Docusaurus can generate a sidebar from your docs folder: - -```js title="sidebars.js" -module.exports = { - myAutogeneratedSidebar: [ - // highlight-start - { - type: 'autogenerated', - dirName: '.', // '.' means the current docs folder - }, - // highlight-end - ], -}; -``` - -You can also use **multiple `autogenerated` items** in a sidebar, and interleave them with regular sidebar items: - -```js title="sidebars.js" -module.exports = { - mySidebar: [ - 'intro', - { - type: 'category', - label: 'Tutorials', - items: [ - 'tutorial-intro', - // highlight-start - { - type: 'autogenerated', - dirName: 'tutorials/easy', // Generate sidebar slice from docs/tutorials/easy - }, - // highlight-end - 'tutorial-medium', - // highlight-start - { - type: 'autogenerated', - dirName: 'tutorials/advanced', // Generate sidebar slice from docs/tutorials/hard - }, - // highlight-end - 'tutorial-end', - ], - }, - // highlight-start - { - type: 'autogenerated', - dirName: 'guides', // Generate sidebar slice from docs/guides - }, - // highlight-end - { - type: 'category', - label: 'Community', - items: ['team', 'chat'], - }, - ], -}; -``` - -#### Category index convention {#category-index-convention} - -Docusaurus can automatically link a category to its index document. - -A category index document is a document following one of those filename conventions: - -- Named as `index` (case-insensitive): `docs/Guides/index.md` -- Named as `README` (case-insensitive): `docs/Guides/README.mdx` -- Same name as parent folder: `docs/Guides/Guides.md` - -This is equivalent to using a category with a [doc link](#category-doc-link): - -```js title="sidebars.js" -module.exports = { - docs: [ - // highlight-start - { - type: 'category', - label: 'Guides', - link: {type: 'doc', id: 'Guides/index'}, - items: [], - }, - // highlight-end - ], -}; -``` - -:::tip - -Naming your introductory document `README.md` makes it show up when browsing the folder using the GitHub interface, while using `index.md` makes the behavior more in line with how HTML files are served. - -::: - -#### Autogenerated sidebar metadata {#autogenerated-sidebar-metadata} - -By default, the sidebar slice will be generated in **alphabetical order** (using files and folders names). - -If the generated sidebar does not look good, you can assign additional metadata to docs and categories. - -**For docs**: use additional front matter: - -```md title="docs/tutorials/tutorial-easy.md" {1-4} ---- -sidebar_label: Easy -sidebar_position: 2 ---- - -# Easy Tutorial - -This is the easy tutorial! -``` - -**For categories**: add a `_category_.json` or `_category_.yml` file in the appropriate folder: - -```json title="docs/tutorials/_category_.json" -{ - "label": "Tutorial", - "position": 3, - "className": "red", - "link": { - "type": "generated-index", - "title": "Tutorial overview" - } -} -``` - -:::info - -If the `link` is explicitly specified, Docusaurus will not apply any [default conventions](#category-index-convention). - -The doc links can be specified relatively, e.g. if the category is generated with the `guides` directory, `"link": {"type": "doc", "id": "intro"}` will be resolved to the ID `guides/intro`, only falling back to `intro` if a doc with the former ID doesn't exist. - -::: - -```yaml title="docs/tutorials/_category_.yml" -label: 'Tutorial' -position: 2.5 # float position is supported -collapsible: true # make the category collapsible -collapsed: false # keep the category open by default -``` - -:::info - -The position metadata is only used **inside a sidebar slice**: Docusaurus does not re-order other items of your sidebar. - -::: - -#### Using number prefixes - -A simple way to order an autogenerated sidebar is to prefix docs and folders by number prefixes: - -```bash -docs -├── 01-Intro.md -├── 02-Tutorial Easy -│   ├── 01-First Part.md -│   ├── 02-Second Part.md -│   └── 03-End.md -├── 03-Tutorial Hard -│   ├── 01-First Part.md -│   ├── 02-Second Part.md -│   ├── 03-Third Part.md -│   └── 04-End.md -└── 04-End.md -``` - -To make it **easier to adopt**, Docusaurus supports **multiple number prefix patterns**. - -By default, Docusaurus will **remove the number prefix** from the doc id, title, label and URL paths. - -:::caution - -**Prefer using [additional metadata](#autogenerated-sidebar-metadata)**. - -Updating a number prefix can be annoying, as it can require **updating multiple existing markdown links**: - -```diff title="docs/02-Tutorial Easy/01-First Part.md" -- Check the [Tutorial End](../04-End.md); -+ Check the [Tutorial End](../05-End.md); -``` - -::: - -#### Customize the sidebar items generator - -You can provide a custom `sidebarItemsGenerator` function in the docs plugin (or preset) config: - -```js title="docusaurus.config.js" -module.exports = { - plugins: [ - [ - '@docusaurus/plugin-content-docs', - { - // highlight-start - sidebarItemsGenerator: async function ({ - defaultSidebarItemsGenerator, - numberPrefixParser, - item, - version, - docs, - }) { - // Example: return an hardcoded list of static sidebar items - return [ - {type: 'doc', id: 'doc1'}, - {type: 'doc', id: 'doc2'}, - ]; - }, - // highlight-end - }, - ], - ], -}; -``` - -:::tip - -**Re-use and enhance the default generator** instead of writing a generator from scratch. - -**Add, update, filter, re-order** the sidebar items according to your use-case: - -```js title="docusaurus.config.js" -// highlight-start -// Reverse the sidebar items ordering (including nested category items) -function reverseSidebarItems(items) { - // Reverse items in categories - const result = items.map((item) => { - if (item.type === 'category') { - return {...item, items: reverseSidebarItems(item.items)}; - } - return item; - }); - // Reverse items at current level - result.reverse(); - return result; -} -// highlight-end - -module.exports = { - plugins: [ - [ - '@docusaurus/plugin-content-docs', - { - // highlight-start - sidebarItemsGenerator: async function ({ - defaultSidebarItemsGenerator, - ...args - }) { - const sidebarItems = await defaultSidebarItemsGenerator(args); - return reverseSidebarItems(sidebarItems); - }, - // highlight-end - }, - ], - ], -}; -``` - -::: - -## Hideable sidebar {#hideable-sidebar} - -Using the enabled `themeConfig.hideableSidebar` option, you can make the entire sidebar hidden, allowing you to better focus your users on the content. This is especially useful when content consumption on medium screens (e.g. on tablets). - -```js title="docusaurus.config.js" -module.exports = { - themeConfig: { - // highlight-start - hideableSidebar: true, - // highlight-end - }, -}; -``` - -## Passing custom props {#passing-custom-props} - -To pass in custom props to a swizzled sidebar item, add the optional `customProps` object to any of the items: - -```js -{ - type: 'doc', - id: 'doc1', - customProps: { - /* props */ - } -} -``` - -## Complex sidebars example {#complex-sidebars-example} - -Real-world example from the Docusaurus site: - -```mdx-code-block -import CodeBlock from '@theme/CodeBlock'; - - - {require('!!raw-loader!@site/sidebars.js') - .default - .split('\n') - // remove comments - .map((line) => !['#','/*','*'].some(commentPattern => line.trim().startsWith(commentPattern)) && line) - .filter(Boolean) - .join('\n')} - -``` diff --git a/website/versioned_docs/version-2.0.0-beta.13/guides/docs/versioning.md b/website/versioned_docs/version-2.0.0-beta.13/guides/docs/versioning.md deleted file mode 100644 index 5a60fecef8..0000000000 --- a/website/versioned_docs/version-2.0.0-beta.13/guides/docs/versioning.md +++ /dev/null @@ -1,216 +0,0 @@ ---- -id: versioning -title: Versioning -slug: /versioning ---- - -You can use the version script to create a new documentation version based on the latest content in the `docs` directory. That specific set of documentation will then be preserved and accessible even as the documentation in the `docs` directory changes moving forward. - -:::caution - -Think about it before starting to version your documentation - it can become difficult for contributors to help improve it! - -::: - -Most of the time, you don't need versioning as it will just increase your build time, and introduce complexity to your codebase. Versioning is **best suited for websites with high-traffic and rapid changes to documentation between versions**. If your documentation rarely changes, don't add versioning to your documentation. - -To better understand how versioning works and see if it suits your needs, you can read on below. - -## Directory structure {#directory-structure} - -```shell -website -├── sidebars.json # sidebar for the current docs version -├── docs # docs directory for the current docs version -│ ├── foo -│ │ └── bar.md # https://mysite.com/docs/next/foo/bar -│ └── hello.md # https://mysite.com/docs/next/hello -├── versions.json # file to indicate what versions are available -├── versioned_docs -│ ├── version-1.1.0 -│ │ ├── foo -│ │ │ └── bar.md # https://mysite.com/docs/foo/bar -│ │ └── hello.md -│ └── version-1.0.0 -│ ├── foo -│ │ └── bar.md # https://mysite.com/docs/1.0.0/foo/bar -│ └── hello.md -├── versioned_sidebars -│ ├── version-1.1.0-sidebars.json -│ └── version-1.0.0-sidebars.json -├── docusaurus.config.js -└── package.json -``` - -The table below explains how a versioned file maps to its version and the generated URL. - -| Path | Version | URL | -| --------------------------------------- | -------------- | ----------------- | -| `versioned_docs/version-1.0.0/hello.md` | 1.0.0 | /docs/1.0.0/hello | -| `versioned_docs/version-1.1.0/hello.md` | 1.1.0 (latest) | /docs/hello | -| `docs/hello.md` | current | /docs/next/hello | - -:::tip - -The files in the `docs` directory belong to the `current` docs version. - -By default, the `current` docs version is labelled as `Next` and hosted under `/docs/next/*`, but is entirely configurable to fit your project's release lifecycle. - -::: - -### Tagging a new version {#tagging-a-new-version} - -1. First, make sure the current docs version (the `docs` directory) is ready to be frozen. -1. Enter a new version number. - -```bash npm2yarn -npm run docusaurus docs:version 1.1.0 -``` - -When tagging a new version, the document versioning mechanism will: - -- Copy the full `docs/` folder contents into a new `versioned_docs/version-/` folder. -- Create a versioned sidebars file based from your current [sidebar](docs-introduction.md#sidebar) configuration (if it exists) - saved as `versioned_sidebars/version--sidebars.json`. -- Append the new version number to `versions.json`. - -## Docs {#docs} - -### Creating new docs {#creating-new-docs} - -1. Place the new file into the corresponding version folder. -1. Include the reference for the new file into the corresponding sidebar file, according to version number. - -**Current version docs** - -```shell -# The new file. -docs/new.md - -# Edit the corresponding sidebar file. -sidebar.js -``` - -**Older version docs** - -```shell -# The new file. -versioned_docs/version-1.0.0/new.md - -# Edit the corresponding sidebar file. -versioned_sidebars/version-1.0.0-sidebars.json -``` - -### Linking docs {#linking-docs} - -- Remember to include the `.md` extension. -- Files will be linked to correct corresponding version. -- Relative paths work as well. - -```md -The [@hello](hello.md#paginate) document is great! - -See the [Tutorial](../getting-started/tutorial.md) for more info. -``` - -## Versions {#versions} - -Each directory in `versioned_docs/` will represent a documentation version. - -### Updating an existing version {#updating-an-existing-version} - -You can update multiple docs versions at the same time because each directory in `versioned_docs/` represents specific routes when published. - -1. Edit any file. -1. Commit and push changes. -1. It will be published to the version. - -Example: When you change any file in `versioned_docs/version-2.6/`, it will only affect the docs for version `2.6`. - -### Deleting an existing version {#deleting-an-existing-version} - -You can delete/remove versions as well. - -1. Remove the version from `versions.json`. - -Example: - -```diff {4} -[ - "2.0.0", - "1.9.0", -- "1.8.0" -] -``` - -2. Delete the versioned docs directory. Example: `versioned_docs/version-1.8.0`. -3. Delete the versioned sidebars file. Example: `versioned_sidebars/version-1.8.0-sidebars.json`. - -## Recommended practices {#recommended-practices} - -### Figure out the behavior for the "current" version {#figure-out-the-behavior-for-the-current-version} - -The "current" version is the version name for the `./docs` folder. - -There are different ways to manage versioning, but two very common patterns are: - -- You release v1, and start immediately working on v2 (including its docs) -- You release v1, and will maintain it for some time before thinking about v2. - -Docusaurus defaults work great for the first usecase. - -**For the 2nd usecase**: if you release v1 and don't plan to work on v2 anytime soon, instead of versioning v1 and having to maintain the docs in 2 folders (`./docs` + `./versioned_docs/version-1.0.0`), you may consider using the following configuration instead: - -```json -{ - "lastVersion": "current", - "versions": { - "current": { - "label": "1.0.0", - "path": "1.0.0" - } - } -} -``` - -The docs in `./docs` will be served at `/docs/1.0.0` instead of `/docs/next`, and `1.0.0` will become the default version we link to in the navbar dropdown, and you will only need to maintain a single `./docs` folder. - -See [docs plugin configuration](../../api/plugins/plugin-content-docs.md) for more details. - -### Version your documentation only when needed {#version-your-documentation-only-when-needed} - -For example, you are building a documentation for your npm package `foo` and you are currently in version 1.0.0. You then release a patch version for a minor bug fix and it's now 1.0.1. - -Should you cut a new documentation version 1.0.1? **You probably shouldn't**. 1.0.1 and 1.0.0 docs shouldn't differ according to semver because there are no new features!. Cutting a new version for it will only just create unnecessary duplicated files. - -### Keep the number of versions small {#keep-the-number-of-versions-small} - -As a good rule of thumb, try to keep the number of your versions below 10. **It is very likely** that you will have a lot of obsolete versioned documentation that nobody even reads anymore. For example, [Jest](https://jestjs.io/versions) is currently in version `24.9`, and only maintains several latest documentation versions with the lowest being `22.X`. Keep it small 😊 - -### Use absolute import within the docs {#use-absolute-import-within-the-docs} - -Don't use relative paths import within the docs. Because when we cut a version the paths no longer work (the nesting level is different, among other reasons). You can utilize the `@site` alias provided by Docusaurus, that points to the `website` directory. Example: - -```diff -- import Foo from '../src/components/Foo'; -+ import Foo from '@site/src/components/Foo'; -``` - -### Global or versioned collocated assets {#global-or-versioned-collocated-assets} - -You should decide if assets like images and files are per version or shared between versions - -If your assets should be versioned, put them in the docs version, and use relative paths: - -```md -![img alt](./myImage.png) - -[download this file](./file.pdf) -``` - -If your assets are global, put them in `/static` and use absolute paths: - -```md -![img alt](/myImage.png) - -[download this file](/file.pdf) -``` diff --git a/website/versioned_docs/version-2.0.0-beta.13/guides/markdown-features/markdown-features-admonitions.mdx b/website/versioned_docs/version-2.0.0-beta.13/guides/markdown-features/markdown-features-admonitions.mdx deleted file mode 100644 index 69784e5dc1..0000000000 --- a/website/versioned_docs/version-2.0.0-beta.13/guides/markdown-features/markdown-features-admonitions.mdx +++ /dev/null @@ -1,123 +0,0 @@ ---- -id: admonitions -title: Admonitions -description: Handling admonitions/callouts in Docusaurus Markdown -slug: /markdown-features/admonitions ---- - -In addition to the basic Markdown syntax, we use [remark-admonitions](https://github.com/elviswolcott/remark-admonitions) alongside MDX to add support for admonitions. Admonitions are wrapped by a set of 3 colons. - -Example: - - :::note - - Some **content** with _markdown_ `syntax`. Check [this `api`](#). - - ::: - - :::tip - - Some **content** with _markdown_ `syntax`. Check [this `api`](#). - - ::: - - :::info - - Some **content** with _markdown_ `syntax`. Check [this `api`](#). - - ::: - - :::caution - - Some **content** with _markdown_ `syntax`. Check [this `api`](#). - - ::: - - :::danger - - Some **content** with _markdown_ `syntax`. Check [this `api`](#). - - ::: - -:::note - -Some **content** with _markdown_ `syntax`. Check [this `api`](#). - -::: - -:::tip - -Some **content** with _markdown_ `syntax`. Check [this `api`](#). - -::: - -:::info - -Some **content** with _markdown_ `syntax`. Check [this `api`](#). - -::: - -:::caution - -Some **content** with _markdown_ `syntax`. Check [this `api`](#). - -::: - -:::danger - -Some **content** with _markdown_ `syntax`. Check [this `api`](#). - -::: - -## Specifying title {#specifying-title} - -You may also specify an optional title - - :::note Your Title - - Some **content** with _markdown_ `syntax`. - - ::: - -:::note Your Title - -Some **content** with _markdown_ `syntax`. - -::: - -## Admonitions with MDX - -You can use MDX inside admonitions too! - -```jsx -import Tabs from '@theme/Tabs'; - -import TabItem from '@theme/TabItem'; - -:::tip Use tabs in admonitions - - - This is an apple 🍎 - This is an orange 🍊 - This is a banana 🍌 - - -::: -``` - -```mdx-code-block -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -``` - -:::tip Use tabs in admonitions - -```mdx-code-block - - This is an apple 🍎 - This is an orange 🍊 - This is a banana 🍌 - -``` - -::: diff --git a/website/versioned_docs/version-2.0.0-beta.13/guides/markdown-features/markdown-features-math-equations.mdx b/website/versioned_docs/version-2.0.0-beta.13/guides/markdown-features/markdown-features-math-equations.mdx deleted file mode 100644 index b37917b4f2..0000000000 --- a/website/versioned_docs/version-2.0.0-beta.13/guides/markdown-features/markdown-features-math-equations.mdx +++ /dev/null @@ -1,116 +0,0 @@ ---- -id: math-equations -title: Math Equations -description: Writing LaTeX Math Equations -slug: /markdown-features/math-equations ---- - -Mathematical equations can be rendered using [KaTeX](https://katex.org). - -## Usage - -Please read [KaTeX](https://katex.org) documentation for more details. - -### Inline - -Write inline math equations by wrapping LaTeX equations between `$`: - -```mdx -Let $f:[a,b] \to \R$ be Riemann integrable. Let $F:[a,b]\to\R$ be $F(x)= -\int_{a}^{x}f(t)dt$. Then $$F$$ is continuous, and at all $x$ such that $f$ is continuous at $x$, $F$ is differentiable at $x$ with $F'(x)=f(x)$. -``` - -Let $f:[a,b] \to \R$ be Riemann integrable. Let $F:[a,b]\to\R$ be $F(x)= -\int_{a}^{x}f(t)dt$. Then $F$ is continuous, and at all $x$ such that $f$ is continuous at $x$, $F$ is differentiable at $x$ with $F'(x)=f(x)$. - -### Blocks - -For equation block or display mode, use line breaks and `$$`: - -```mdx -$$ -I = \int_0^{2\pi} \sin(x) dx -$$ -``` - -$$ -I = \int_0^{2\pi} \sin(x) dx -$$ - -## Configuration - -To enable KaTeX, you need to install `remark-math` and `rehype-katex` plugins. - -```bash npm2yarn -npm install --save remark-math@3 rehype-katex@4 hast-util-is-element@1.1.0 -``` - -:::caution - -Use the exact same versions. The latest versions are incompatible with Docusaurus 2. - -::: - -Import the plugins in `docusaurus.config.js`: - -```js -const math = require('remark-math'); -const katex = require('rehype-katex'); -``` - -Add them to your content plugin or preset options (usually `@docusaurus/preset-classic` docs options): - -```js -remarkPlugins: [math], -rehypePlugins: [katex], -``` - -Include the KaTeX CSS in your config under `stylesheets`: - -```js -stylesheets: [ - { - href: "https://cdn.jsdelivr.net/npm/katex@0.13.11/dist/katex.min.css", - integrity: "sha384-Um5gpz1odJg5Z4HAmzPtgZKdTBHZdw8S29IecapCSB31ligYPhHQZMIlWLYQGVoc", - crossorigin: "anonymous", - }, -], -``` - -Overall the changes look like: - -```js title="docusaurus.config.js" -// highlight-start -const math = require('remark-math'); -const katex = require('rehype-katex'); -// highlight-end - -module.exports = { - title: 'Docusaurus', - tagline: 'Build optimized websites quickly, focus on your content', - presets: [ - [ - '@docusaurus/preset-classic', - { - docs: { - path: 'docs', - // highlight-start - remarkPlugins: [math], - rehypePlugins: [katex], - // highlight-end - }, - }, - ], - ], - // highlight-start - stylesheets: [ - { - href: 'https://cdn.jsdelivr.net/npm/katex@0.13.11/dist/katex.min.css', - integrity: - 'sha384-Um5gpz1odJg5Z4HAmzPtgZKdTBHZdw8S29IecapCSB31ligYPhHQZMIlWLYQGVoc', - crossorigin: 'anonymous', - }, - ], - // highlight-end -}; -``` diff --git a/website/versioned_docs/version-2.0.0-beta.13/guides/markdown-features/markdown-features-react.mdx b/website/versioned_docs/version-2.0.0-beta.13/guides/markdown-features/markdown-features-react.mdx deleted file mode 100644 index 8be1ae86fc..0000000000 --- a/website/versioned_docs/version-2.0.0-beta.13/guides/markdown-features/markdown-features-react.mdx +++ /dev/null @@ -1,218 +0,0 @@ ---- -id: react -title: MDX and React -description: Using the power of React in Docusaurus Markdown documents, thanks to MDX -slug: /markdown-features/react ---- - -# MDX and React - -```mdx-code-block -import BrowserWindow from '@site/src/components/BrowserWindow'; -``` - -## Using JSX in Markdown {#using-jsx-in-markdown} - -Docusaurus has built-in support for [MDX v1](https://mdxjs.com/), which allows you to write JSX within your Markdown files and render them as React components. - -:::note - -While both `.md` and `.mdx` files are parsed using MDX, some of the syntax are treated slightly differently. For the most accurate parsing and better editor support, we recommend using the `.mdx` extension for files containing MDX syntax. - -::: - -:::caution - -MDX is not [100% compatible with CommonMark](https://github.com/facebook/docusaurus/issues/3018). - -Use the **[MDX playground](https://mdx-git-renovate-babel-monorepo-mdx.vercel.app/playground)** to ensure that your syntax is valid MDX. - -::: - -Try this block here: - -```jsx -export const Highlight = ({children, color}) => ( - - {children} - -); - -Docusaurus green and Facebook blue are my favorite colors. - -I can write **Markdown** alongside my _JSX_! -``` - -Notice how it renders both the markup from your React component and the Markdown syntax: - -```mdx-code-block -export const Highlight = ({children, color}) => ( - - {children} - -); - - - -Docusaurus green -{` `}and Facebook blue are my favorite colors. - -I can write **Markdown** alongside my _JSX_! - - -``` - -
- -You can also import your own components defined in other files or third-party components installed via npm! Check out the [MDX docs](https://mdxjs.com/) to see what other fancy stuff you can do with MDX. - -:::caution - -Since all doc files are parsed using MDX, any HTML is treated as JSX. Therefore, if you need to inline-style a component, follow JSX flavor and provide style objects. This behavior is different from Docusaurus 1. See also [Migrating from v1 to v2](../../migration/migration-manual.md#convert-style-attributes-to-style-objects-in-mdx). - -::: - -## Importing code snippets {#importing-code-snippets} - -You can not only import a file containing a component definition, but also import any code file as raw text, and then insert it in a code block, thanks to [Webpack raw-loader](https://webpack.js.org/loaders/raw-loader/). In order to use `raw-loader`, first you need to install it in your project: - -```bash npm2yarn -npm install --save raw-loader -``` - -Now you can import code snippets from another file as it is: - - -```jsx title="myMarkdownFile.mdx" -import CodeBlock from '@theme/CodeBlock'; -import MyComponentSource from '!!raw-loader!./myComponent'; - -{MyComponentSource} -``` - - -```mdx-code-block -import CodeBlock from '@theme/CodeBlock'; -import MyComponentSource from '!!raw-loader!@site/src/pages/examples/_myComponent'; - - - -{MyComponentSource} - - - -
-``` - -You can also pass `title` prop to `CodeBlock` component in order to appear it as header above your codeblock: - -```jsx - - {MyComponentSource} - -``` - -:::note - -You have to use `` rather than the Markdown triple-backtick ` ``` `, because the latter will ship out any of its content as-is, but you want JSX to insert the imported text here. - -::: - -:::warning - -This feature is experimental and might be subject to API breaking changes in the future. - -::: - -## Importing Markdown {#importing-markdown} - -You can use Markdown files as components and import them elsewhere, either in Markdown files or in React pages. - -By convention, using the **`_` filename prefix** will not create any doc page and means the markdown file is a **"partial"**, to be imported by other files. - -```md title="_markdown-partial-example.mdx" -Hello {props.name} - -This is text some content from `_markdown-partial-example.mdx`. -``` - -```jsx title="someOtherDoc.mdx" -import PartialExample from './_markdown-partial-example.mdx'; - -; -``` - -```mdx-code-block -import PartialExample from './_markdown-partial-example.mdx'; - - - - - -
-``` - -This way, you can reuse contents among multiple pages and avoid duplicating materials. - -:::caution - -The table-of-contents does not currently contain the imported Markdown headings. This is a technical limitation that we are trying to solve ([issue](https://github.com/facebook/docusaurus/issues/3915)). - -::: - -## Available exports - -Within the MDX page, the following variables are available as globals: - -- `frontMatter`: the front matter as a record of string keys and values; -- `toc`: the table of contents, as a tree of headings. See also [Inline TOC](./markdown-features-inline-toc.mdx) for a more concrete use-case. -- `contentTitle`: the Markdown title, which is the first `h1` heading in the Markdown text. It's `undefined` if there isn't one (e.g. title specified in the front matter). - -```jsx -import TOCInline from '@theme/TOCInline'; -import CodeBlock from '@theme/CodeBlock'; - -The table of contents for this page, serialized: - -{JSON.stringify(toc, null, 2)} - -The front matter of this page: - -
    - {Object.entries(frontMatter).map(([key, value]) =>
  • {key}: {value}
    • )} -
- -

The title of this page is: {contentTitle}

-``` - -```mdx-code-block -import TOCInline from '@theme/TOCInline'; - - - -The table of contents for this page, serialized: - -{JSON.stringify(toc, null, 2)} - -The front matter of this page: - -
    - {Object.entries(frontMatter).map(([key, value]) =>
  • {key}: {value}
    • )} -
- -

The title of this page is: {contentTitle}

- - -``` diff --git a/website/versioned_docs/version-2.0.0-beta.13/i18n/i18n-tutorial.md b/website/versioned_docs/version-2.0.0-beta.13/i18n/i18n-tutorial.md deleted file mode 100644 index 4e4ce73ebd..0000000000 --- a/website/versioned_docs/version-2.0.0-beta.13/i18n/i18n-tutorial.md +++ /dev/null @@ -1,336 +0,0 @@ ---- -id: tutorial -title: i18n - Tutorial -slug: /i18n/tutorial ---- - -This tutorial will walk you through the basis of the **Docusaurus i18n system**. - -We will add **French** translations to a **newly initialized English Docusaurus website**. - -Initialize a new site with `npx create-docusaurus@latest website classic` (like [this one](https://github.com/facebook/docusaurus/tree/main/examples/classic)). - -## Configure your site {#configure-your-site} - -Modify `docusaurus.config.js` to add the i18n support for the French language. - -### Site configuration {#site-configuration} - -Use the [site i18n configuration](./../api/docusaurus.config.js.md#i18n) to declare the i18n locales: - -```js title="docusaurus.config.js" -module.exports = { - i18n: { - defaultLocale: 'en', - locales: ['en', 'fr'], - }, -}; -``` - -### Theme configuration {#theme-configuration} - -Add a **navbar item** of type `localeDropdown` so that users can select the locale they want: - -```js title="docusaurus.config.js" -module.exports = { - themeConfig: { - navbar: { - items: [ - // highlight-start - { - type: 'localeDropdown', - position: 'left', - }, - // highlight-end - ], - }, - }, -}; -``` - -### Start your site {#start-your-site} - -Start your localized site in dev mode, using the locale of your choice: - -```bash npm2yarn -npm run start -- --locale fr -``` - -Your site is accessible at **`http://localhost:3000/fr/`**. - -We haven't provided any translation, and the site is **mostly untranslated**. - -:::tip - -Docusaurus provides **default translations** for generic theme labels, such as "Next" and "Previous" for the pagination. - -Please help us complete those **[default translations](https://github.com/facebook/docusaurus/tree/main/packages/docusaurus-theme-translations/locales)**. - -::: - -:::caution - -Each locale is a **distinct standalone single-page-application**: it is not possible to start the Docusaurus sites in all locales at the same time. - -::: - -## Translate your site {#translate-your-site} - -The French translations will be added in `website/i18n/fr`. - -Docusaurus is modular, and each content plugin has its own subfolder. - -:::note - -After copying files around, restart your site with `npm run start -- --locale fr`. - -Hot-reload will work better when editing existing files. - -::: - -### Use the translation APIs {#use-the-translation-apis} - -Open the homepage, and use the [translation APIs](../docusaurus-core.md#translate): - -```jsx title="src/pages/index.js" -import React from 'react'; -import Layout from '@theme/Layout'; -import Link from '@docusaurus/Link'; - -// highlight-start -import Translate, {translate} from '@docusaurus/Translate'; -// highlight-end - -export default function Home() { - return ( - -

- {/* highlight-start */} - Welcome to my website - {/* highlight-end */} -

-
- {/* highlight-start */} - blog}}> - {'You can also visit my {blog}'} - - {/* highlight-end */} - - -
- - ); -} -``` - -:::caution - -Docusaurus provides a **very small and lightweight translation runtime** on purpose, and only supports basic [placeholders interpolation](../docusaurus-core.md#interpolate), using a subset of the [ICU Message Format](https://formatjs.io/docs/core-concepts/icu-syntax/). - -Most documentation websites are generally **static** and don't need advanced i18n features (**plurals**, **genders**, etc.). Use a library like [react-intl](https://www.npmjs.com/package/react-intl) for more advanced use-cases. - -::: - -### Translate JSON files {#translate-json-files} - -JSON translation files are used for everything that is not contained in a Markdown document: - -- React/JSX code -- Layout navbar and footer labels -- Docs sidebar category labels -- ... - -Run the [write-translations](../cli.md#docusaurus-write-translations-sitedir) command: - -```bash npm2yarn -npm run write-translations -- --locale fr -``` - -It will extract and initialize the JSON translation files that you need to translate. - -The homepage translations are statically extracted from React source code: - -```json title="i18n/fr/code.json" -{ - "Welcome to my website": { - "message": "Welcome to my website", - "description": "The homepage welcome message" - }, - "Hello": { - "message": "Hello", - "description": "The homepage input placeholder" - } -} -``` - -Plugins and themes will also write their own **JSON translation files**, such as: - -```json title="i18n/fr/docusaurus-theme-classic/navbar.json" -{ - "title": { - "message": "My Site", - "description": "The title in the navbar" - }, - "item.label.Docs": { - "message": "Docs", - "description": "Navbar item with label Docs" - }, - "item.label.Blog": { - "message": "Blog", - "description": "Navbar item with label Blog" - }, - "item.label.GitHub": { - "message": "GitHub", - "description": "Navbar item with label GitHub" - } -} -``` - -Translate the `message` attribute in the JSON files of `i18n/fr`, and your site layout and homepage should now be translated. - -### Translate Markdown files {#translate-markdown-files} - -Official Docusaurus content plugins extensively use Markdown/MDX files, and allow you to translate them. - -#### Translate the docs {#translate-the-docs} - -Copy your docs Markdown files to `i18n/fr/docusaurus-plugin-content-docs/current`, and translate them: - -```bash -mkdir -p i18n/fr/docusaurus-plugin-content-docs/current -cp -r docs/** i18n/fr/docusaurus-plugin-content-docs/current -``` - -:::info - -`current` is needed for the docs versioning feature: each docs version has its own subfolder. - -::: - -#### Translate the blog {#translate-the-blog} - -Copy your blog Markdown files to `i18n/fr/docusaurus-plugin-content-blog`, and translate them: - -```bash -mkdir -p i18n/fr/docusaurus-plugin-content-blog -cp -r blog/** i18n/fr/docusaurus-plugin-content-blog -``` - -#### Translate the pages {#translate-the-pages} - -Copy your pages Markdown files to `i18n/fr/docusaurus-plugin-content-pages`, and translate them: - -```bash -mkdir -p i18n/fr/docusaurus-plugin-content-pages -cp -r src/pages/**.md i18n/fr/docusaurus-plugin-content-pages -cp -r src/pages/**.mdx i18n/fr/docusaurus-plugin-content-pages -``` - -:::caution - -We only copy `.md` and `.mdx` files, as pages React components are translated through JSON translation files already. - -::: - -### Use explicit heading ids {#use-explicit-heading-ids} - -By default, a Markdown heading `### Hello World` will have a generated id `hello-world`. - -Other documents can target it with `[link](#hello-world)`. - -The translated heading becomes `### Bonjour le Monde`, with id `bonjour-le-monde`. - -Generated ids are not always a good fit for localized sites, as it requires you to localize all the anchor links: - -```diff -- [link](#hello-world). -+ [link](#bonjour-le-monde) -``` - -:::tip - -For localized sites, it is recommended to use **[explicit heading ids](../guides/markdown-features/markdown-features-headings.mdx#explicit-ids)**. - -::: - -## Deploy your site {#deploy-your-site} - -You can choose to deploy your site under a **single domain**, or use **multiple (sub)domains**. - -### Single-domain deployment {#single-domain-deployment} - -Run the following command: - -```bash npm2yarn -npm run build -``` - -Docusaurus will build **one single-page application per locale**: - -- `website/build`: for the default, English language -- `website/build/fr`: for the French language - -You can now [deploy](../deployment.mdx) the `build` folder to the static hosting solution of your choice. - -:::note - -The Docusaurus v2 website use this strategy: - -- [https://docusaurus.io](https://docusaurus.io) -- [https://docusaurus.io/fr](https://docusaurus.io/fr) - -::: - -:::tip - -Static hosting providers generally redirect `/unknown/urls` to `/404.html` by convention, always showing an **English 404 page**. - -**Localize your 404 pages** by configuring your host to redirect `/fr/*` to `/fr/404.html`. - -This is not always possible, and depends on your host: GitHub Pages can't do this, [Netlify](https://docs.netlify.com/routing/redirects/redirect-options/#custom-404-page-handling) can. - -::: - -### Multi-domain deployment {#multi-domain-deployment} - -You can also build your site for a single locale: - -```bash npm2yarn -npm run build -- --locale fr -``` - -Docusaurus will not add the `/fr/` URL prefix. - -On your [static hosting provider](../deployment.mdx): - -- create one deployment per locale -- configure the appropriate build command, using the `--locale` option -- configure the (sub)domain of your choice for each deployment - -:::caution - -This strategy is **not possible** with Github Pages, as it is only possible to **have a single deployment**. - -::: - -### Hybrid {#hybrid} - -It is possible to have some locales using sub-paths, and others using subdomains. - -It is also possible to deploy each locale as a separate subdomain, assemble the subdomains in a single unified domain at the CDN level: - -- Deploy your site as `fr.docusaurus.io` -- Configure a CDN to serve it from `docusaurus.io/fr` diff --git a/website/versioned_docs/version-2.0.0-beta.13/presets.md b/website/versioned_docs/version-2.0.0-beta.13/presets.md deleted file mode 100644 index e359ca404b..0000000000 --- a/website/versioned_docs/version-2.0.0-beta.13/presets.md +++ /dev/null @@ -1,137 +0,0 @@ ---- -id: presets -title: Presets ---- - -Presets are collections of plugins and themes. - -## Using presets {#using-presets} - -A preset is usually a npm package, so you install them like other npm packages using npm. - -```bash npm2yarn -npm install --save @docusaurus/preset-classic -``` - -Then, add it in your site's `docusaurus.config.js`'s `presets` option: - -```jsx {3} title="docusaurus.config.js" -module.exports = { - // ... - presets: ['@docusaurus/preset-classic'], -}; -``` - -To load presets from your local directory, specify how to resolve them: - -```jsx {5} title="docusaurus.config.js" -const path = require('path'); - -module.exports = { - // ... - presets: [path.resolve(__dirname, '/path/to/docusaurus-local-presets')], -}; -``` - -## Presets -> themes and plugins {#presets---themes-and-plugins} - -Presets are a shorthand function to add plugins and themes to your Docusaurus config. For example, you can specify a preset that includes the following themes and plugins, - -```js -module.exports = function preset(context, opts = {}) { - return { - themes: ['@docusaurus/theme-cool', opts.cool], - plugins: ['@docusaurus/plugin-blog', opts.blog], - }; -}; -``` - -then in your Docusaurus config, you may configure the preset instead: - -```jsx {3} title="docusaurus.config.js" -module.exports = { - presets: [ - '@docusaurus/preset-my-own', - {cool: {hello: 'world'}, blog: {path: '/blog'}}, - ], -}; -``` - -This is equivalent of doing: - -```jsx title="docusaurus.config.js" -module.exports = { - themes: ['@docusaurus/themes-cool', {hello: 'world'}], - plugins: ['@docusaurus/plugin-blog', {path: '/blog'}], -}; -``` - -This is especially useful when some plugins and themes are intended to be used together. - -## Official presets {#official-presets} - -### `@docusaurus/preset-classic` {#docusauruspreset-classic} - -The classic preset that is usually shipped by default to new Docusaurus website. It is a set of plugins and themes. - -| Themes | Plugins | -| --- | --- | -| [`@docusaurus/theme-classic`](./api/themes/theme-configuration.md) | [`@docusaurus/plugin-content-docs`](./api/plugins/plugin-content-docs.md) | -| [`@docusaurus/theme-search-algolia`](./api/themes/theme-search-algolia.md) | [`@docusaurus/plugin-content-blog`](./api/plugins/plugin-content-blog.md) | -| | [`@docusaurus/plugin-content-pages`](./api/plugins/plugin-content-pages.md) | -| | [`@docusaurus/plugin-debug`](./api/plugins/plugin-debug.md) | -| | [`@docusaurus/plugin-google-analytics`](./api/plugins/plugin-google-analytics.md) | -| | [`@docusaurus/plugin-google-gtag`](./api/plugins/plugin-google-gtag.md) | -| | [`@docusaurus/plugin-sitemap`](./api/plugins/plugin-sitemap.md) | - -To specify plugin options individually, you can provide the necessary fields to certain plugins, i.e. `customCss` for `@docusaurus/theme-classic`, pass them in the preset field, like this: - -```js title="docusaurus.config.js" -module.exports = { - presets: [ - [ - '@docusaurus/preset-classic', - { - // Debug defaults to true in dev, false in prod - debug: undefined, - // Will be passed to @docusaurus/theme-classic. - theme: { - customCss: [require.resolve('./src/css/custom.css')], - }, - // Will be passed to @docusaurus/plugin-content-docs (false to disable) - docs: {}, - // Will be passed to @docusaurus/plugin-content-blog (false to disable) - blog: {}, - // Will be passed to @docusaurus/plugin-content-pages (false to disable) - pages: {}, - // Will be passed to @docusaurus/plugin-content-sitemap (false to disable) - sitemap: {}, - // Will be passed to @docusaurus/plugin-google-gtag (only enabled when explicitly specified) - gtag: {}, - // Will be passed to @docusaurus/plugin-google-analytics (only enabled when explicitly specified) - googleAnalytics: {}, - }, - ], - ], -}; -``` - -In addition to these plugins and themes, `@docusaurus/theme-classic` adds [`remark-admonitions`](https://github.com/elviswolcott/remark-admonitions) as a remark plugin to `@docusaurus/plugin-content-blog` and `@docusaurus/plugin-content-docs`. - -The `admonitions` key will be passed as the [options](https://github.com/elviswolcott/remark-admonitions#options) to `remark-admonitions`. Passing `false` will prevent the plugin from being added to MDX. - -```js title="docusaurus.config.js" -module.exports = { - presets: [ - [ - '@docusaurus/preset-classic', - { - docs: { - // options for remark-admonitions - admonitions: {}, - }, - }, - ], - ], -}; -``` diff --git a/website/versioned_docs/version-2.0.0-beta.13/static-assets.md b/website/versioned_docs/version-2.0.0-beta.13/static-assets.md deleted file mode 100644 index b37f1c6b13..0000000000 --- a/website/versioned_docs/version-2.0.0-beta.13/static-assets.md +++ /dev/null @@ -1,71 +0,0 @@ ---- -id: static-assets -title: Static Assets ---- - -Every website needs assets: images, stylesheets, favicons etc. By default, you are suggested to put these assets in the `static` folder. - -Every file you put into **that directory will be copied** into the root of the generated `build` folder with the directory hierarchy preserved. E.g. if you add a file named `sun.jpg` to the static folder, it will be copied to `build/sun.jpg`. - -This means that: - -- for site `baseUrl: '/'`, the image `/static/img/docusaurus.png` will be served at `/img/docusaurus.png`. -- for site `baseUrl: '/subpath/'`, the image `/static/img/docusaurus.png` will be served at `/subpath/img/docusaurus.png`. - -You can customize the static directory sources in `docusaurus.config.js`. For example, we can add `public` as another possible path: - -```js title="docusaurus.config.js" -module.exports = { - title: 'My site', - staticDirectories: ['public', 'static'], - // ... -}; -``` - -Now, all files in `public` as well as `static` will be copied to the build output. - -## Referencing your static asset {#referencing-your-static-asset} - -In JSX, you can reference assets from the `static` folder in your code using absolute paths, but this is not ideal because changing the site `baseUrl` will **break those links**. For the image `` served at `https://example.com/test`, the browser will try to resolve it from the URL root, i.e. as `https://example.com/img/docusaurus.png`, which will fail because it's actually served at `https://example.com/test/img/docusaurus.png`. - -You can `import` / `require()` the static asset (recommended), or use the `useBaseUrl` utility function: both prepend the `baseUrl` to paths for you. - -:::info - -In Markdown, things are different: you can stick to use absolute paths because Docusaurus actually handles them as `require` calls instead of URLs when parsing the Markdown. See [Markdown static assets](./guides/markdown-features/markdown-features-assets.mdx). - -::: - -### Examples {#examples} - -```jsx title="MyComponent.js" -import DocusaurusImageUrl from '@site/static/img/docusaurus.png'; - -; -``` - -```jsx title="MyComponent.js" - -``` - -```jsx title="MyComponent.js" -import useBaseUrl from '@docusaurus/useBaseUrl'; - -; -``` - -You can also import SVG files: they will be transformed into React components. - -```jsx title="MyComponent.js" -import DocusaurusLogoWithKeytar from '@site/static/img/docusaurus_keytar.svg'; - -; -``` - -### Caveats {#caveats} - -Keep in mind that: - -- By default, none of the files in `static` folder will be post-processed, hashed or minified. -- Missing files referenced via hardcoded absolute paths will not be detected at compilation time, and will result in a 404 error. -- By default, GitHub Pages runs published files through [Jekyll](https://jekyllrb.com/). Since Jekyll will discard any files that begin with `_`, it is recommended that you disable Jekyll by adding an empty file named `.nojekyll` file to your `static` directory if you are using GitHub pages for hosting. diff --git a/website/versioned_docs/version-2.0.0-beta.13/using-plugins.md b/website/versioned_docs/version-2.0.0-beta.13/using-plugins.md deleted file mode 100644 index 745ff93adf..0000000000 --- a/website/versioned_docs/version-2.0.0-beta.13/using-plugins.md +++ /dev/null @@ -1,209 +0,0 @@ ---- -id: using-plugins -title: Plugins ---- - -Plugins are the building blocks of features in a Docusaurus 2 site. Each plugin handles its own individual feature. Plugins may work and be distributed as part of bundle via [presets](presets.md). - -## Available plugins {#available-plugins} - -We maintain a [list of official plugins](./api/plugins/overview.md), but the community has also created some [unofficial plugins](/community/resources#community-plugins). - -## Installing a plugin {#installing-a-plugin} - -A plugin is usually a npm package, so you install them like other npm packages using npm. - -```bash npm2yarn -npm install --save docusaurus-plugin-name -``` - -Then you add it in your site's `docusaurus.config.js`'s `plugins` option: - -```jsx {3} title="docusaurus.config.js" -module.exports = { - // ... - plugins: ['@docusaurus/plugin-content-pages'], -}; -``` - -Docusaurus can also load plugins from your local directory, you can do something like the following: - -```jsx {5} title="docusaurus.config.js" -const path = require('path'); - -module.exports = { - // ... - plugins: [path.resolve(__dirname, '/path/to/docusaurus-local-plugin')], -}; -``` - -## Configuring plugins {#configuring-plugins} - -For the most basic usage of plugins, you can provide just the plugin name or the absolute path to the plugin. - -However, plugins can have options specified by wrapping the name and an options object in an array inside your config. This style is usually called `Babel Style`. - -```js {4-9} title="docusaurus.config.js" -module.exports = { - // ... - plugins: [ - [ - '@docusaurus/plugin-xxx', - { - /* options */ - }, - ], - ], -}; -``` - -Example: - -```js title="docusaurus.config.js" -module.exports = { - plugins: [ - // Basic usage. - '@docusaurus/plugin-google-analytics', - - // With options object (babel style) - [ - '@docusaurus/plugin-sitemap', - { - changefreq: 'weekly', - }, - ], - ], -}; -``` - -## Multi-instance plugins and plugin ids {#multi-instance-plugins-and-plugin-ids} - -All Docusaurus content plugins can support multiple plugin instances. - -The Docs plugin has [additional multi-instance documentation](./guides/docs/docs-multi-instance.mdx) - -It is required to assign a unique id to each plugin instance. - -By default, the plugin id is `default`. - -```js {6,13} title="docusaurus.config.js" -module.exports = { - plugins: [ - [ - '@docusaurus/plugin-xxx', - { - id: 'plugin-xxx-1', - // other options - }, - ], - [ - '@docusaurus/plugin-xxx', - { - id: 'plugin-xxx-2', - // other options - }, - ], - ], -}; -``` - -:::note - -At most one plugin instance can be the "default plugin instance", by omitting the `id` attribute, or using `id: 'default'`. - -::: - -## Plugins design {#plugins-design} - -Docusaurus' implementation of the plugins system provides us with a convenient way to hook into the website's lifecycle to modify what goes on during development/build, which involves (but not limited to) extending the webpack config, modifying the data being loaded and creating new components to be used in a page. - -## Creating plugins {#creating-plugins} - -A plugin is a function that takes two parameters: `context` and `options`. - -It returns a plugin instance object, containing plugin [lifecycle APIs](./api/plugin-methods/README.md). - -It can be defined as a function or a module. - -### Functional definition {#functional-definition} - -You can use a plugin as a function, directly in the Docusaurus config file: - -```js title="docusaurus.config.js" -module.exports = { - // ... - plugins: [ - // highlight-start - function myPlugin(context, options) { - // ... - return { - name: 'my-plugin', - async loadContent() { - // ... - }, - async contentLoaded({content, actions}) { - // ... - }, - /* other lifecycle API */ - }; - }, - // highlight-end - ], -}; -``` - -### Module definition {#module-definition} - -You can use a plugin as a module, loading it from a separate file or NPM package: - -```js title="docusaurus.config.js" -module.exports = { - // ... - plugins: [ - // without options: - './my-plugin', - // or with options: - ['./my-plugin', options], - ], -}; -``` - -Then in the folder `my-plugin` you can create an index.js such as this - -```js title="my-plugin.js" -module.exports = function myPlugin(context, options) { - // ... - return { - name: 'my-plugin', - async loadContent() { - /* ... */ - }, - async contentLoaded({content, actions}) { - /* ... */ - }, - /* other lifecycle API */ - }; -}; -``` - -#### `context` {#context} - -`context` is plugin-agnostic, and the same object will be passed into all plugins used for a Docusaurus website. The `context` object contains the following fields: - -```ts -interface LoadContext { - siteDir: string; - generatedFilesDir: string; - siteConfig: DocusaurusConfig; - outDir: string; - baseUrl: string; -} -``` - -#### `options` {#options} - -`options` are the [second optional parameter when the plugins are used](using-plugins.md#configuring-plugins). `options` are plugin-specific and are specified by users when they use them in `docusaurus.config.js`. Alternatively, if preset contains the plugin, the preset will then be in charge of passing the correct options into the plugin. It is up to individual plugin to define what options it takes. - -#### Return value {#return-value} - -The returned object value should implement the [lifecycle APIs](./api/plugin-methods/README.md). diff --git a/website/versioned_docs/version-2.0.0-beta.13/using-themes.md b/website/versioned_docs/version-2.0.0-beta.13/using-themes.md deleted file mode 100644 index 129f95476b..0000000000 --- a/website/versioned_docs/version-2.0.0-beta.13/using-themes.md +++ /dev/null @@ -1,247 +0,0 @@ ---- -id: using-themes -title: Themes ---- - -Like plugins, themes are designed to add functionality to your Docusaurus site. As a good rule of thumb, themes are mostly focused on client-side, where plugins are more focused on server-side functionalities. Themes are also designed to be replace-able with other themes. - -## Available themes {#available-themes} - -We maintain a [list of official themes](./api/themes/overview.md). - -## Using themes {#using-themes} - -To use themes, specify the themes in your `docusaurus.config.js`. You may use multiple themes: - -```js {3} title="docusaurus.config.js" -module.exports = { - // ... - themes: ['@docusaurus/theme-classic', '@docusaurus/theme-live-codeblock'], -}; -``` - -## Theme components {#theme-components} - -Most of the time, theme is used to provide a set of React components, e.g. `Navbar`, `Layout`, `Footer`. - -Users can use these components in their code by importing them using the `@theme` webpack alias: - -```js -import Navbar from '@theme/Navbar'; -``` - -The alias `@theme` can refer to a few directories, in the following priority: - -1. A user's `website/src/theme` directory, which is a special directory that has the higher precedence. -1. A Docusaurus theme packages's `theme` directory. -1. Fallback components provided by Docusaurus core (usually not needed). - -Given the following structure - -``` -website -├── node_modules -│ └── docusaurus-theme -│ └── theme -│ └── Navbar.js -└── src - └── theme - └── Navbar.js -``` - -`website/src/theme/Navbar.js` takes precedence whenever `@theme/Navbar` is imported. This behavior is called component swizzling. In iOS, method swizzling is the process of changing the implementation of an existing selector (method). In the context of a website, component swizzling means providing an alternative component that takes precedence over the component provided by the theme. - -**Themes are for providing UI components to present the content.** Most content plugins need to be paired with a theme in order to be actually useful. The UI is a separate layer from the data schema, so it makes it easy to swap out the themes for other designs. - -For example, a Docusaurus blog consists of a blog plugin and a blog theme. - -```js title="docusaurus.config.js" -{ - theme: ['theme-blog'], - plugins: ['plugin-content-blog'], -} -``` - -And if you want to use Bootstrap styling, you can swap out the theme with `theme-blog-bootstrap` (fictitious non-existing theme): - -```js title="docusaurus.config.js" -{ - theme: ['theme-blog-bootstrap'], - plugins: ['plugin-content-blog'], -} -``` - -## Wrapping your site with `` {#wrapper-your-site-with-root} - -A `` theme component is rendered at the very top of your Docusaurus site. - -It allows you to wrap your site with additional logic, by creating a file at `src/theme/Root.js`: - -```js title="website/src/theme/Root.js" -import React from 'react'; - -// Default implementation, that you can customize -function Root({children}) { - return <>{children}; -} - -export default Root; -``` - -This component is applied above the router and the theme ``, and will **never unmount**. - -:::tip - -Use this component to render React Context providers and global stateful logic. - -::: - -## Swizzling theme components {#swizzling-theme-components} - -```mdx-code-block -import SwizzleWarning from "./_partials/swizzleWarning.mdx" - - -``` - -Docusaurus Themes' components are designed to be replaceable. To make it easier for you, we created a command for you to replace theme components called `swizzle`. - -To swizzle a component for a theme, run the following command in your doc site: - -```bash npm2yarn -npm run swizzle [component name] -``` - -As an example, to swizzle the `
` component in `@docusaurus/theme-classic` for your site, run: - -```bash npm2yarn -npm run swizzle @docusaurus/theme-classic Footer -``` - -This will copy the current `
` component used by the theme to a `src/theme/Footer` directory under the root of your site, which is where Docusaurus will look for swizzled components. Docusaurus will then use swizzled component in place of the original one from the theme. - -Although we highly discourage swizzling of all components, if you wish to do that, run: - -```bash npm2yarn -npm run swizzle @docusaurus/theme-classic -``` - -**Note**: You need to restart your webpack dev server in order for Docusaurus to know about the new component. - -## Wrapping theme components {#wrapping-theme-components} - -Sometimes, you just want to wrap an existing theme component with additional logic, and it can be a pain to have to maintain an almost duplicate copy of the original theme component. - -In such case, you should swizzle the component you want to wrap, but import the original theme component in your customized version to wrap it. - -### For site owners {#for-site-owners} - -The `@theme-original` alias allows you to import the original theme component. - -Here is an example to display some text just above the footer, with minimal code duplication. - -```js title="src/theme/Footer.js" -// Note: importing from "@theme/Footer" would fail due to the file importing itself -import OriginalFooter from '@theme-original/Footer'; -import React from 'react'; - -export default function Footer(props) { - return ( - <> -
Before footer
- - - ); -} -``` - -### For plugin authors {#for-plugin-authors} - -One theme can wrap a component from another theme, by importing the component from the initial theme, using the `@theme-init` import. - -Here's an example of using this feature to enhance the default theme `CodeBlock` component with a `react-live` playground feature. - -```js -import InitialCodeBlock from '@theme-init/CodeBlock'; -import React from 'react'; - -export default function CodeBlock(props) { - return props.live ? ( - - ) : ( - - ); -} -``` - -Check the code of `docusaurus-theme-live-codeblock` for details. - -:::caution - -Unless you want publish to npm a "theme enhancer" (like `docusaurus-theme-live-codeblock`), you likely don't need `@theme-init`. - -::: - -
- -How are theme aliases resolved? - -It can be quite hard to wrap your mind around these aliases. Let's imagine the following case with a super convoluted setup where three themes/plugins and the site itself all try to define the same component. Internally, Docusaurus loads these themes as a "stack". - -```text -+-------------------------------------------------+ -| `website/src/theme/CodeBlock.js` | <-- `@theme/CodeBlock` always points to the top -+-------------------------------------------------+ -| `theme-live-codeblock/theme/CodeBlock/index.js` | <-- `@theme-original/CodeBlock` points to the topmost non-swizzled component -+-------------------------------------------------+ -| `plugin-awesome-codeblock/theme/CodeBlock.js` | -+-------------------------------------------------+ -| `theme-classic/theme/CodeBlock/index.js` | <-- `@theme-init/CodeBlock` always points to the bottom -+-------------------------------------------------+ -``` - -The components in this "stack" are pushed in the order of `preset plugins > preset themes > plugins > themes > site`, so the swizzled component in `website/src/theme` always comes out on top because it's loaded last. - -`@theme/*` always points to the topmost component—when code block is swizzled, all other components requesting `@theme/CodeBlock` receive the swizzled version. - -`@theme-original/*` always points to the topmost non-swizzled component. That's why you can import `@theme-original/CodeBlock` in the swizzled component—it points to the next one in the "component stack", a theme-provided one. Plugin authors should not try to use this because your component could be the topmost component and cause a self-import. - -`@theme-init/*` always points to the bottommost component—usually this comes from the theme or plugin that first provides this component. Individual plugins / themes trying to enhance code block can safely use `@theme-init/CodeBlock` to get its basic version. Site creators should generally not use this because you likely want to enhance the _topmost_ instead of the _bottommost_ component. It's also possible that the `@theme-init/CodeBlock` alias does not exist at all—Docusaurus only creates it when it points to a different one from `@theme-original/CodeBlock`, i.e. when it's provided by more than one theme. We don't waste aliases! - -
- -## Themes design {#themes-design} - -While themes share the exact same lifecycle methods with plugins, their implementations can look very different from those of plugins based on themes' designed objectives. - -Themes are designed to complete the build of your Docusaurus site and supply the components used by your site, plugins, and the themes themselves. So a typical theme implementation would look like a `src/index.js` file that hooks it up to the lifecycle methods. Most likely they would not use `loadContent`, which plugins would use. And it is typically accompanied by a `src/theme` directory full of components. - -To summarize: - -- Themes share the same lifecycle methods with Plugins -- Themes are run after all existing Plugins -- Themes exist to add component aliases by extending the webpack config - -## Writing customized Docusaurus themes {#writing-customized-docusaurus-themes} - -A Docusaurus theme normally includes an `index.js` file where you hook up to the lifecycle methods, alongside with a `theme/` directory of components. A typical Docusaurus `theme` folder looks like this: - -```shell {5-7} -website -├── package.json -└── src - ├── index.js - └── theme - ├── MyThemeComponent - └── AnotherThemeComponent.js -``` - -There are two lifecycle methods that are essential to theme implementation: - -- [`getThemePath()`](./api/plugin-methods/extend-infrastructure.md#getThemePath) -- [`getClientModules()`](./api/plugin-methods/lifecycle-apis.md#getClientModules) - -These lifecycle methods are not essential but recommended: - -- [`validateThemeConfig({themeConfig, validate})`](./api/plugin-methods/static-methods.md#validateThemeConfig) -- [`validateOptions({options, validate})`](./api/plugin-methods/static-methods.md#validateOptions) diff --git a/website/versioned_docs/version-2.0.0-beta.13/_partials/swizzleWarning.mdx b/website/versioned_docs/version-2.0.0-beta.15/_partials/swizzleWarning.mdx similarity index 100% rename from website/versioned_docs/version-2.0.0-beta.13/_partials/swizzleWarning.mdx rename to website/versioned_docs/version-2.0.0-beta.15/_partials/swizzleWarning.mdx diff --git a/website/versioned_docs/version-2.0.0-beta.15/advanced/architecture.md b/website/versioned_docs/version-2.0.0-beta.15/advanced/architecture.md new file mode 100644 index 0000000000..778b68eabd --- /dev/null +++ b/website/versioned_docs/version-2.0.0-beta.15/advanced/architecture.md @@ -0,0 +1,28 @@ +--- +description: How Docusaurus works to build your app +--- + +# Architecture + +```mdx-code-block +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import Zoom from '@site/src/components/Zoom'; +``` + + + +![Architecture overview](/img/architecture.png) + + + +This diagram shows how Docusaurus works to build your app. Plugins each collect their content and emit JSON data; themes provide layout components which receive the JSON data as route modules. The bundler bundles all the components and emits a server bundle and a client bundle. + +Although you (either plugin authors or site creators) are writing JavaScript all the time, bear in mind that the JS is actually run in different environments: + +- All plugin lifecycle methods are run in Node. Therefore, until we support ES Modules in our codebase, plugin source code must be provided as CommonJS that can be `require`'d. +- The theme code is built with Webpack. They can be provided as ESM—following React conventions. + +Plugin code and theme code never directly import each other: they only communicate through protocols (in our case, through JSON temp files and calls to `addRoute`). A useful mental model is to imagine that the plugins are not written in JavaScript, but in another language like Rust. The only way to interact with plugins for the user is through `docusaurus.config.js`, which itself is run in Node (hence you can use `require` and pass callbacks as plugin options). + +During bundling, the config file itself is serialized and bundled, allowing the theme to access config options like `themeConfig` or `baseUrl` through [`useDocusaurusContext()`](../docusaurus-core.md#useDocusaurusContext). However, the `siteConfig` object only contains **serializable values** (values that are preserved after `JSON.stringify()`). Functions, regexes, etc. would be lost on the client side. The `themeConfig` is designed to be entirely serializable. diff --git a/website/versioned_docs/version-2.0.0-beta.15/advanced/index.md b/website/versioned_docs/version-2.0.0-beta.15/advanced/index.md new file mode 100644 index 0000000000..afe7f1a570 --- /dev/null +++ b/website/versioned_docs/version-2.0.0-beta.15/advanced/index.md @@ -0,0 +1,12 @@ +# Advanced Tutorials + +This section is not going to be very structured, but we will cover the following topics: + +```mdx-code-block +import DocCardList from '@theme/DocCardList'; +import {useCurrentSidebarCategory} from '@docusaurus/theme-common'; + + +``` + +We will assume that you have finished the guides, and know the basics like how to configure plugins, how to write React components, etc. These sections will have plugin authors and code contributors in mind, so we may occasionally refer to [plugin APIs](../api/plugin-methods/README.md) or other architecture details. Don't panic if you don't understand everything😉 diff --git a/website/versioned_docs/version-2.0.0-beta.15/advanced/plugins.md b/website/versioned_docs/version-2.0.0-beta.15/advanced/plugins.md new file mode 100644 index 0000000000..c309f4b536 --- /dev/null +++ b/website/versioned_docs/version-2.0.0-beta.15/advanced/plugins.md @@ -0,0 +1,129 @@ +# Plugins + +Plugins are the building blocks of features in a Docusaurus 2 site. Each plugin handles its own individual feature. Plugins may work and be distributed as part of a bundle via presets. + +## Creating plugins {#creating-plugins} + +A plugin is a function that takes two parameters: `context` and `options`. It returns a plugin instance object (or a promise). You can create plugins as functions or modules. For more information, refer to the [plugin method references section](./api/plugin-methods/README.md). + +### Function definition {#function-definition} + +You can use a plugin as a function directly included in the Docusaurus config file: + +```js title="docusaurus.config.js" +module.exports = { + // ... + plugins: [ + // highlight-start + async function myPlugin(context, options) { + // ... + return { + name: 'my-plugin', + async loadContent() { + // ... + }, + async contentLoaded({content, actions}) { + // ... + }, + /* other lifecycle API */ + }; + }, + // highlight-end + ], +}; +``` + +### Module definition {#module-definition} + +You can use a plugin as a module path referencing a separate file or NPM package: + +```js title="docusaurus.config.js" +module.exports = { + // ... + plugins: [ + // without options: + './my-plugin', + // or with options: + ['./my-plugin', options], + ], +}; +``` + +Then in the folder `my-plugin`, you can create an `index.js` such as this: + +```js title="my-plugin.js" +module.exports = async function myPlugin(context, options) { + // ... + return { + name: 'my-plugin', + async loadContent() { + /* ... */ + }, + async contentLoaded({content, actions}) { + /* ... */ + }, + /* other lifecycle API */ + }; +}; +``` + +--- + +You can view all plugins installed in your site using the [debug plugin's metadata panel](/__docusaurus/debug/metadata). + +Plugins come as several types: + +- `package`: an external package you installed +- `project`: a plugin you created in your project, given to Docusaurus as a local file path +- `local`: a plugin created using the function definition +- `synthetic`: a "fake plugin" Docusaurus created internally, so we take advantage of our modular architecture and don't let the core do much special work. You won't see this in the metadata because it's an implementation detail. + +You can access them on the client side with `useDocusaurusContext().siteMetadata.pluginVersions`. + +## Plugin design + +Docusaurus' implementation of the plugins system provides us with a convenient way to hook into the website's lifecycle to modify what goes on during development/build, which involves (but is not limited to) extending the webpack config, modifying the data loaded, and creating new components to be used in a page. + +### Theme design + +When plugins have loaded their content, the data is made available to the client side through actions like [`createData` + `addRoute`](../api/plugin-methods/lifecycle-apis.md#addRoute) or [`setGlobalData`](../api/plugin-methods/lifecycle-apis.md#setGlobalData). This data has to be _serialized_ to plain strings, because [plugins and themes run in different environments](./architecture.md). Once the data arrives on the client side, the rest becomes familiar to React developers: data is passed along components, components are bundled with Webpack, and rendered to the window through `ReactDOM.render`... + +**Themes provide the set of UI components to render the content.** Most content plugins need to be paired with a theme in order to be actually useful. The UI is a separate layer from the data schema, which makes swapping designs easy. + +For example, a Docusaurus blog may consist of a blog plugin and a blog theme. + +:::note + +This is a contrived example: in practice, `@docusaurus/theme-classic` provides the theme for docs, blog, and layouts. + +::: + +```js title="docusaurus.config.js" +module.exports = { + // highlight-next-line + themes: ['theme-blog'], + plugins: ['plugin-content-blog'], +}; +``` + +And if you want to use Bootstrap styling, you can swap out the theme with `theme-blog-bootstrap` (another fictitious non-existing theme): + +```js title="docusaurus.config.js" +module.exports = { + // highlight-next-line + themes: ['theme-blog-bootstrap'], + plugins: ['plugin-content-blog'], +}; +``` + +Now, although the theme receives the same data from the plugin, how the theme chooses to _render_ the data as UI can be drastically different. + +While themes share the exact same lifecycle methods with plugins, themes' implementations can look very different from those of plugins based on themes' designed objectives. + +Themes are designed to complete the build of your Docusaurus site and supply the components used by your site, plugins, and the themes themselves. A theme still acts like a plugin and exposes some lifecycle methods, but most likely they would not use [`loadContent`](../api/plugin-methods/lifecycle-apis.md#loadContent), since they only receive data from plugins, but don't generate data themselves; themes are typically also accompanied by an `src/theme` directory full of components, which are made known to the core through the [`getThemePath`](../api/plugin-methods/extend-infrastructure.md#getThemePath) lifecycle. + +To summarize: + +- Themes share the same lifecycle methods with Plugins +- Themes are run after all existing Plugins +- Themes add component aliases by providing `getThemePath`. diff --git a/website/versioned_docs/version-2.0.0-beta.15/advanced/routing.md b/website/versioned_docs/version-2.0.0-beta.15/advanced/routing.md new file mode 100644 index 0000000000..09bc837490 --- /dev/null +++ b/website/versioned_docs/version-2.0.0-beta.15/advanced/routing.md @@ -0,0 +1,277 @@ +--- +description: "Docusaurus' routing system follows single-page application conventions: one route, one component." +--- + +# Routing + +```mdx-code-block +import Link from '@docusaurus/Link'; +import {useLatestVersion, useActiveDocContext} from '@docusaurus/plugin-content-docs/client'; +import {useLocation} from '@docusaurus/router'; +import BrowserWindow from '@site/src/components/BrowserWindow'; +``` + +Docusaurus' routing system follows single-page application conventions: one route, one component. In this section, we will begin by talking about routing within the three content plugins (docs, blog, and pages), and then go beyond to talk about the underlying routing system. + +## Routing in content plugins + +Every content plugin provides a `routeBasePath` option. It defines where the plugins append their routes to. By default, the docs plugin puts its routes under `/docs`; the blog plugin, `/blog`; and the pages plugin, `/`. You can think about the route structure like this: + +![plugin routes model](/img/routes.png#gh-light-mode-only)![plugin routes model](/img/routes-dark.png#gh-dark-mode-only) + +Any route will be matched against this nested route config until a good match is found. For example, when given a route `/docs/configuration`, Docusaurus first enters the `/docs` branch, and then searches among the subroutes created by the docs plugin. + +Changing `routeBasePath` can effectively alter your site's route structure. For example, in [Docs-only mode](../guides/docs/docs-introduction.md#docs-only-mode), we mentioned that configuring `routeBasePath: '/'` for docs means that all routes that the docs plugin create would not have the `/docs` prefix, yet it doesn't prevent you from having more subroutes like `/blog` created by other plugins. + +Next, let's look at how the three plugins structure their own "boxes of subroutes". + +### Pages routing + +Pages routing are straightforward: the file paths directly map to URLs, without any other way to customize. See the [pages docs](../guides/creating-pages.md#routing) for more information. + +The component used for Markdown pages is `@theme/MDXPage`. React pages are directly used as the route's component. + +### Blog routing + +The blog creates the following routes: + +- **Posts list pages**: `/`, `/page/2`, `/page/3`... + - The component is `@theme/BlogListPage`. +- **Post pages**: `/2021/11/21/algolia-docsearch-migration`, `/2021/05/12/announcing-docusaurus-two-beta`... + - Generated from each Markdown post. + - The routes are fully customizable through the `slug` front matter. + - The component is `@theme/BlogPostPage`. +- **Tags list page**: `/tags` + - The route is customizable through the `tagsBasePath` option. + - The component is `@theme/BlogTagsListPage`. +- **Tag pages**: `/tags/adoption`, `/tags/beta`... + - Generated through the tags defined in each post's front matter. + - The routes always have base defined in `tagsBasePath`, but the subroutes are customizable through the tag's `permalink` field. + - The component is `@theme/BlogTagsPostsPage`. +- **Archive page**: `/archive` + - The route is customizable through the `archiveBasePath` option. + - The component is `@theme/BlogArchivePage`. + +### Docs routing + +The docs is the only plugin that creates **nested routes**. At the top, it registers [**version paths**](../guides/docs/versioning.md): `/`, `/next`, `/2.0.0-beta.13`... which provide the version context, including the layout and sidebar. This ensures that when switching between individual docs, the sidebar's state is preserved, and that you can switch between versions through the navbar dropdown while staying on the same doc. The component used is `@theme/DocPage`. + +```mdx-code-block +export const URLPath = () => {useLocation().pathname}; + +export const FilePath = () => { + const currentVersion = useActiveDocContext('default').activeVersion.name; + return {currentVersion === 'current' ? './docs/' : `./versioned_docs/version-${currentVersion}/`}advanced/routing.md; +} +``` + +The individual docs are rendered in the remaining space after the navbar, footer, sidebar, etc. have all been provided by the `DocPage` component. For example, this page, , is generated from the file at . The component used is `@theme/DocItem`. + +The doc's `slug` front matter customizes the last part of the route, but the base route is always defined by the plugin's `routeBasePath` and the version's `path`. + +### File paths and URL paths + +Throughout the documentation, we always try to be unambiguous about whether we are talking about file paths or URL paths. Content plugins usually map file paths directly to URL paths, for example, `./docs/advanced/routing.md` will become `/docs/advanced/routing`. However, with `slug`, you can make URLs totally decoupled from the file structure. + +When writing links in Markdown, you could either mean a _file path_, or a _URL path_, which Docusaurus would use several heuristics to determine. + +- If the path doesn't have an extension, it is a URL path. For example, a link `[page](../plugins)` on a page with URL `/docs/advanced/routing` will link to `/docs/plugins`. Docusaurus will only detect broken links when building your site (when it knows the full route structure), but will make no assumptions about the existence of a file. It is exactly equivalent to writing `page` in a JSX file. +- If the path has an `.md(x)` extension, Docusaurus would try to resolve that Markdown file to a URL, and replace the file path with a URL path. +- If the path has any other extension, Docusaurus would treat it as [an asset](../guides/markdown-features/markdown-features-assets.mdx) and bundle it. + +The following directory structure may help you visualize this file -> URL mapping. Assume that there's no slug customization in any page. + +
+ +A sample site structure + +```bash +. +├── blog # blog plugin has routeBasePath: '/blog' +│ ├── 2019-05-28-first-blog-post.md # -> /blog/2019/05/28/first-blog-post +│ ├── 2019-05-29-long-blog-post.md # -> /blog/2019/05/29/long-blog-post +│ ├── 2021-08-01-mdx-blog-post.mdx # -> /blog/2021/08/01/mdx-blog-post +│ └── 2021-08-26-welcome +│ ├── docusaurus-plushie-banner.jpeg +│ └── index.md # -> /blog/2021/08/26/welcome +├── docs # docs plugin has routeBasePath: '/docs'; current version has base path '/' +│ ├── intro.md # -> /docs/intro +│ ├── tutorial-basics +│ │ ├── _category_.json +│ │ ├── congratulations.md # -> /docs/tutorial-basics/congratulations +│ │ └── markdown-features.mdx # -> /docs/tutorial-basics/congratulations +│ └── tutorial-extras +│ ├── _category_.json +│ ├── manage-docs-versions.md # -> /docs/tutorial-extras/manage-docs-versions +│ └── translate-your-site.md # -> /docs/tutorial-extras/translate-your-site +├── src +│ └── pages # pages plugin has routeBasePath: '/' +│ ├── index.module.css +│ ├── index.tsx # -> / +│ └── markdown-page.md # -> /markdown-page +└── versioned_docs + └── version-1.0.0 # version has base path '/1.0.0' + ├── intro.md # -> /docs/1.0.0/intro + ├── tutorial-basics + │ ├── _category_.json + │ ├── congratulations.md # -> /docs/1.0.0/tutorial-basics/congratulations + │ └── markdown-features.mdx # -> /docs/1.0.0/tutorial-basics/congratulations + └── tutorial-extras + ├── _category_.json + ├── manage-docs-versions.md # -> /docs/1.0.0/tutorial-extras/manage-docs-versions + └── translate-your-site.md # -> /docs/1.0.0/tutorial-extras/translate-your-site +``` + +
+ +So much about content plugins. Let's take one step back and talk about how routing works in a Docusaurus app in general. + +## Routes become HTML files + +Because Docusaurus is a server-side rendering framework, all routes generated will be server-side rendered into static HTML files. If you are familiar with the behavior of HTTP servers like [Apache2](https://httpd.apache.org/docs/trunk/getting-started.html), you will understand how this is done: when the browser sends a request to the route `/docs/advanced/routing`, the server interprets that as request for the HTML file `/docs/advanced/routing/index.html`, and returns that. + +The `/docs/advanced/routing` route can correspond to either `/docs/advanced/routing/index.html` or `/docs/advanced/routing.html`. Some hosting providers differentiate between them using the presence of a trailing slash, and may or may not tolerate the other. Read more in the [trailing slash guide](https://github.com/slorber/trailing-slash-guide). + +For example, the build output of the directory above is (ignoring other assets and JS bundle): + +
+ +Output of the above workspace + +```bash +build +├── 404.html # /404/ +├── blog +│ ├── archive +│ │ └── index.html # /blog/archive/ +│ ├── first-blog-post +│ │ └── index.html # /blog/first-blog-post/ +│ ├── index.html # /blog/ +│ ├── long-blog-post +│ │ └── index.html # /blog/long-blog-post/ +│ ├── mdx-blog-post +│ │ └── index.html # /blog/mdx-blog-post/ +│ ├── tags +│ │ ├── docusaurus +│ │ │ └── index.html # /blog/tags/docusaurus/ +│ │ ├── hola +│ │ │ └── index.html # /blog/tags/hola/ +│ │ └── index.html # /blog/tags/ +│ └── welcome +│ └── index.html # /blog/welcome/ +├── docs +│ ├── 1.0.0 +│ │ ├── intro +│ │ │ └── index.html # /docs/1.0.0/intro/ +│ │ ├── tutorial-basics +│ │ │ ├── congratulations +│ │ │ │ └── index.html # /docs/1.0.0/tutorial-basics/congratulations/ +│ │ │ └── markdown-features +│ │ │ └── index.html # /docs/1.0.0/tutorial-basics/markdown-features/ +│ │ └── tutorial-extras +│ │ ├── manage-docs-versions +│ │ │ └── index.html # /docs/1.0.0/tutorial-extras/manage-docs-versions/ +│ │ └── translate-your-site +│ │ └── index.html # /docs/1.0.0/tutorial-extras/translate-your-site/ +│ ├── intro +│ │ └── index.html # /docs/1.0.0/intro/ +│ ├── tutorial-basics +│ │ ├── congratulations +│ │ │ └── index.html # /docs/tutorial-basics/congratulations/ +│ │ └── markdown-features +│ │ └── index.html # /docs/tutorial-basics/markdown-features/ +│ └── tutorial-extras +│ ├── manage-docs-versions +│ │ └── index.html # /docs/tutorial-extras/manage-docs-versions/ +│ └── translate-your-site +│ └── index.html # /docs/tutorial-extras/translate-your-site/ +├── index.html # / +└── markdown-page + └── index.html # /markdown-page/ +``` + +
+ +If `trailingSlash` is set to `false`, the build would emit `intro.html` instead of `intro/index.html`. + +All HTML files will reference its JS assets using absolute URLs, so in order for the correct assets to be located, you have to configure the `baseUrl` field. Note that `baseUrl` doesn't affect the emitted bundle's file structure: the base URL is one level above the Docusaurus routing system. You can see the aggregate of `url` and `baseUrl` as the actual location of your Docusaurus site. + +For example, the emitted HTML would contain links like ``. Because absolute URLs are resolved from the host, if the bundle placed under the path `https://example.com/base/`, the link will point to `https://example.com/assets/js/runtime~main.7ed5108a.js`, which is, well, non-existent. By specifying `/base/` as base URL, the link will correctly point to `/base/assets/js/runtime~main.7ed5108a.js`. + +Localized sites have the locale as part of the base URL as well. For example, `https://docusaurus.io/zh-CN/docs/advanced/routing/` has base URL `/zh-CN/`. + +## Generating and accessing routes + +The `addRoute` lifecycle action is used to generate routes. It registers a piece of route config to the route tree, giving a route, a component, and props that the component needs. The props and the component are both provided as paths for the bundler to `require`, because as explained in the [architecture overview](architecture.md), server and client only communicate through temp files. + +All routes are aggregated in `.docusaurus/routes.js`, which you can view with the debug plugin's [routes panel](/__docusaurus/debug/routes). + +On the client side, we offer `@docusaurus/router` to access the page's route. `@docusaurus/router` is a re-export of the [`react-router-dom`](https://www.npmjs.com/package/react-router-dom/v/5.3.0) package. For example, you can use `useLocation` to get the current page's [location](https://developer.mozilla.org/en-US/docs/Web/API/Location), and `useHistory` to access the [history object](https://developer.mozilla.org/en-US/docs/Web/API/History). (They are not the same as the browser API, although similar in functionality. Refer to the React Router documentation for specific APIs.) + +This API is **SSR safe**, as opposed to the browser-only `window.location`. + +```jsx title="myComponent.js" +import React from 'react'; +import {useLocation} from '@docusaurus/router'; + +export function PageRoute() { + // React router provides the current component's route, even in SSR + const location = useLocation(); + return ( + + We are currently on {location.pathname} + + ); +} +``` + +```mdx-code-block +export function PageRoute() { + const location = useLocation(); + return ( + + We are currently on {location.pathname} + + ); +} + + + + + + +``` + +## Escaping from SPA redirects + +Docusaurus builds a [single-page application](https://developer.mozilla.org/en-US/docs/Glossary/SPA), where route transitions are done through the `history.push()` method of React router. This operation is done on the client side. However, the prerequisite for a route transition to happen this way is that the target URL is known to our router. Otherwise, the router catches this path and displays a 404 page instead. + +If you put some HTML pages under the `static` folder, they will be copied to the build output and therefore become accessible as part of your website, yet it's not part of the Docusaurus route system. We provide a `pathname://` protocol that allows you to redirect to another part of your domain in a non-SPA fashion, as if this route is an external link. Try the following two links: + +```md +- [/pure-html](/pure-html) +- [pathname:///pure-html](pathname:///pure-html) +``` + + + +- /pure-html +- [pathname:///pure-html](pathname:///pure-html) + + + +:::tip + +The first link will trigger a "broken links detected" check during the production build. + +::: + +The `pathname://` protocol is useful for referencing any content in the static folder. For example, Docusaurus would convert [all Markdown static assets to require() calls](../guides/markdown-features/markdown-features-assets.mdx#static-assets). You can use `pathname://` to keep it a regular link instead of being hashed by Webpack. + +```md title="my-doc.md" +![An image from the static](pathname:///img/docusaurus.png) + +[An asset from the static](pathname:///files/asset.pdf) +``` + +Docusaurus will only strip the `pathname://` prefix without processing the content. diff --git a/website/versioned_docs/version-2.0.0-beta.15/advanced/ssg.md b/website/versioned_docs/version-2.0.0-beta.15/advanced/ssg.md new file mode 100644 index 0000000000..6c478e67e5 --- /dev/null +++ b/website/versioned_docs/version-2.0.0-beta.15/advanced/ssg.md @@ -0,0 +1,206 @@ +--- +sidebar_label: Static site generation +description: Docusaurus statically renders your React code into HTML, allowing faster load speed and better SEO. +--- + +# Static site generation (SSG) + +In [architecture](architecture.md), we mentioned that the theme is run in Webpack. But beware: that doesn't mean it always has access to browser globals! The theme is built twice: + +- During **server-side rendering**, the theme is compiled in a sandbox called [React DOM Server](https://reactjs.org/docs/react-dom-server.html). You can see this as a "headless browser", where there is no `window` or `document`, only React. SSR produces static HTML pages. +- During **client-side rendering**, the theme is compiled with standard React DOM, and has access to browser variables. CSR produces dynamic JavaScript. + +:::info SSR or SSG? + +_Server-side rendering_ and _static site generation_ can be different concepts, but we use them interchangeably. + +::: + +Therefore, while you probably know not to access Node globals like `process` ([or can we?](#node-env)) or the `'fs'` module, you can't freely access browser globals either. + +```jsx +import React from 'react'; + +export default function WhereAmI() { + return {window.location.href}; +} +``` + +This looks like idiomatic React, but if you run `docusaurus build`, you will get an error: + +``` +ReferenceError: window is not defined +``` + +This is because during server-side rendering, the Docusaurus app isn't actually run in browser, and it doesn't know what `window` is. + +
+ +What about process.env.NODE_ENV? + +One exception to the "no Node globals" rule is `process.env.NODE_ENV`. In fact, you can use it in React, because Webpack injects this variable as a global: + +```jsx +import React from 'react'; + +export default function expensiveComp() { + if (process.env.NODE_ENV === 'development') { + return <>This component is not shown in development; + } + const res = someExpensiveOperationThatLastsALongTime(); + return <>{res}; +} +``` + +During Webpack build, the `process.env.NODE_ENV` will be replaced with the value, either `'development'` or `'production'`. You will then get different build results after dead code elimination: + +import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; + + + + +```diff +import React from 'react'; + +export default function expensiveComp() { + // highlight-next-line + if ('development' === 'development') { ++ return <>This component is not shown in development; + } +- const res = someExpensiveOperationThatLastsALongTime(); +- return <>{res}; +} +``` + + + + +```diff +import React from 'react'; + +export default function expensiveComp() { + // highlight-next-line +- if ('production' === 'development') { +- return <>This component is not shown in development; +- } ++ const res = someExpensiveOperationThatLastsALongTime(); ++ return <>{res}; +} +``` + + + +
+ +## Understanding SSR + +React is not just a dynamic UI runtime—it's also a templating engine. Because Docusaurus sites mostly contain static contents, it should be able to work without any JavaScript (which React runs in), but only plain HTML/CSS. And that's what server-side rendering offers: statically rendering your React code into HTML, without any dynamic content. An HTML file has no concept of client state (it's purely markup), hence it shouldn't rely on browser APIs. + +These HTML files are the first to arrive at the user's browser screen when a URL is visited (see [routing](routing.md)). Afterwards, the browser fetches and runs other JS code to provide the "dynamic" parts of your site—anything implemented with JavaScript. However, before that, the main content of your page is already visible, allowing faster loading. + +In CSR-only apps, all DOM elements are generated on client side with React, and the HTML file only ever contains one root element for React to mount DOM to; in SSR, React is already facing a fully built HTML page, and it only needs to correlate the DOM elements with the virtual DOM in its model. This step is called "hydration". After React has hydrated the static markup, the app starts to work as any normal React app. + +## Escape hatches + +If you want to render any dynamic content on your screen that relies on the browser API to be functional at all, for example: + +- Our [live codeblock](../guides/markdown-features/markdown-features-code-blocks.mdx#interactive-code-editor), which runs in the browser's JS runtime +- Our [themed image](../guides/markdown-features/markdown-features-assets.mdx#themed-images) that detects the user's color scheme to display different images +- The JSON viewer of our debug panel which uses the `window` global for styling + +You may need to escape from SSR since static HTML can't display anything useful without knowing the client state. + +:::caution + +It is important for the first client-side render to produce the exact same DOM structure as server-side rendering, otherwise, React will correlate virtual DOM with the wrong DOM elements. + +Therefore, the naïve attempt of `if (typeof window !== 'undefined) {/* render something */}` won't work appropriately as a browser vs. server detection, because the first client render would instantly render different markup from the server-generated one. + +You can read more about this pitfall in [The Perils of Rehydration](https://www.joshwcomeau.com/react/the-perils-of-rehydration/). + +::: + +We provide several more reliable ways to escape SSR. + +### `` + +If you need to render some component in browser only (for example, because the component relies on browser specifics to be functional at all), one common approach is to wrap your component with [``](../docusaurus-core.md#browseronly) to make sure it's invisible during SSR and only rendered in CSR. + +```jsx +import BrowserOnly from '@docusaurus/BrowserOnly'; + +function MyComponent(props) { + return ( + // highlight-start + Loading...
}> + {() => { + const LibComponent = + require('some-lib-that-accesses-window').LibComponent; + return ; + }} + + // highlight-end + ); +} +``` + +It's important to realize that the children of `` is not a JSX element, but a function that _returns_ an element. This is a design decision. Consider this code: + +```jsx +import BrowserOnly from '@docusaurus/BrowserOnly'; + +function MyComponent() { + return ( + + {/* highlight-start */} + {/* DON'T DO THIS - doesn't actually work */} + page url = {window.location.href} + {/* highlight-end */} + + ); +} +``` + +While you may expect that `BrowserOnly` hides away the children during server-side rendering, it actually can't. When the React renderer tries to render this JSX tree, it does see the `{window.location.href}` variable as a node of this tree and tries to render it, although it's actually not used! Using a function ensures that we only let the renderer see the browser-only component when it's needed. + +### `useIsBrowser` + +You can also use the `useIsBrowser()` hook to test if the component is currently in a browser environment. It returns `false` in SSR and `true` is CSR, after first client render. Use this hook if you only need to perform certain conditional operations on client-side, but not render an entirely different UI. + +```jsx +import useIsBrowser from '@docusaurus/useIsBrowser'; + +function MyComponent() { + const isBrowser = useIsBrowser(); + const location = isBrowser ? window.location.href : 'fetching location...'; + return {location}; +} +``` + +### `useEffect` + +Lastly, you can put your logic in `useEffect()` to delay its execution until after first CSR. This is most appropriate if you are only performing side-effects but don't _get_ data from the client state. + +```jsx +function MyComponent() { + useEffect(() => { + // Only logged in the browser console; nothing is logged during server-side rendering + console.log("I'm now in the browser"); + }, []); + return Some content...; +} +``` + +### `ExecutionEnvironment` + +The [`ExecutionEnvironment`](../docusaurus-core.md#executionenvironment) namespace contains several values, and `canUseDOM` is an effective way to detect browser environment. + +Beware that it essentially checked `typeof window !== 'undefined'` under the hood, so you should not use it for rendering-related logic, but only imperative code, like reacting to user input by sending web requests, or dynamically importing libraries, where DOM isn't updated at all. + +```js title="a-client-module.js" +import ExecutionEnvironment from '@docusaurus/ExecutionEnvironment'; + +if (ExecutionEnvironment.canUseDOM) { + document.title = "I'm loaded!"; +} +``` diff --git a/website/versioned_docs/version-2.0.0-beta.15/advanced/swizzling.md b/website/versioned_docs/version-2.0.0-beta.15/advanced/swizzling.md new file mode 100644 index 0000000000..4163bb6e63 --- /dev/null +++ b/website/versioned_docs/version-2.0.0-beta.15/advanced/swizzling.md @@ -0,0 +1,195 @@ +--- +description: Customize your site's appearance through creating your own theme components +--- + +# Swizzling + +In this section, we will introduce how customization of layout is done in Docusaurus. + +> Déja vu...? + +This section is similar to [Styling and Layout](../styling-layout.md), but this time, we are going to write more code and go deeper into the internals instead of playing with stylesheets. We will talk about a central concept in Docusaurus customization: **swizzling**, from how to swizzle, to how it works under the hood. + +We know you are busy, so we will start with the "how" before going into the "why". + +## Swizzling + +```mdx-code-block +import SwizzleWarning from "../_partials/swizzleWarning.mdx" + + +``` + +Docusaurus Themes' components are designed to be replaceable. The replacing is called "swizzle". In Objective C, method swizzling is the process of changing the implementation of an existing selector (method). **In the context of a website, component swizzling means providing an alternative component that takes precedence over the component provided by the theme.** (To gain a deeper understanding of this, you have to understand [how theme components are resolved](#theme-aliases)). To help you get started, we created a command called `docusaurus swizzle`. + +### Ejecting theme components + +To eject a component provided by the theme, run the following command in your doc site: + +```bash npm2yarn +npm run swizzle [theme name] [component name] +``` + +As an example, to swizzle the `