diff --git a/admin/publish.md b/admin/publish.md index def8c7fc6e..48e563f8cd 100644 --- a/admin/publish.md +++ b/admin/publish.md @@ -121,7 +121,7 @@ Test running the website with the new version locally. To keep versions number small, delete the oldest version and add a link to it in `archivedVersions.json`. -Check [Netlify site deployments](https://app.netlify.com/sites/docusaurus-2/deploys) to pick a recent immutable deployment url. +Check [Netlify site deployments](https://app.netlify.com/sites/docusaurus-2/deploys) to pick a recent immutable deployment URL. ### 5. Create a Pull Request diff --git a/packages/create-docusaurus/templates/shared/docs/tutorial-basics/create-a-document.md b/packages/create-docusaurus/templates/shared/docs/tutorial-basics/create-a-document.md index 06aa83ef4c..3c92695c51 100644 --- a/packages/create-docusaurus/templates/shared/docs/tutorial-basics/create-a-document.md +++ b/packages/create-docusaurus/templates/shared/docs/tutorial-basics/create-a-document.md @@ -12,7 +12,7 @@ Documents are **groups of pages** connected through: ## Create your first Doc -Create a markdown file at `docs/hello.md`: +Create a Markdown file at `docs/hello.md`: ```md title="docs/hello.md" # Hello diff --git a/packages/docusaurus-mdx-loader/src/remark/transformLinks/__tests__/__fixtures__/asset.md b/packages/docusaurus-mdx-loader/src/remark/transformLinks/__tests__/__fixtures__/asset.md index a23a16a928..6a8a0e44ab 100644 --- a/packages/docusaurus-mdx-loader/src/remark/transformLinks/__tests__/__fixtures__/asset.md +++ b/packages/docusaurus-mdx-loader/src/remark/transformLinks/__tests__/__fixtures__/asset.md @@ -38,6 +38,6 @@ [Stylized link to asset file](./asset.pdf) -[json](./data.json) +[JSON](./data.json) -[static json](/static-json.json) +[static JSON](/static-json.json) diff --git a/packages/docusaurus-mdx-loader/src/remark/transformLinks/__tests__/__snapshots__/index.test.ts.snap b/packages/docusaurus-mdx-loader/src/remark/transformLinks/__tests__/__snapshots__/index.test.ts.snap index 0daf646c05..2e6d8d8648 100644 --- a/packages/docusaurus-mdx-loader/src/remark/transformLinks/__tests__/__snapshots__/index.test.ts.snap +++ b/packages/docusaurus-mdx-loader/src/remark/transformLinks/__tests__/__snapshots__/index.test.ts.snap @@ -50,8 +50,8 @@ exports[`transformAsset plugin transform md links to 1`] = ` /node_modules/file-loader/dist/cjs.js?name=assets/files/[name]-[contenthash].[ext]!./asset.pdf').default}>Stylized link to asset file -/node_modules/file-loader/dist/cjs.js?name=assets/files/[name]-[contenthash].[ext]!./data.json').default}>json +/node_modules/file-loader/dist/cjs.js?name=assets/files/[name]-[contenthash].[ext]!./data.json').default}>JSON -/node_modules/file-loader/dist/cjs.js?name=assets/files/[name]-[contenthash].[ext]!./static/static-json.json').default}>static json +/node_modules/file-loader/dist/cjs.js?name=assets/files/[name]-[contenthash].[ext]!./static/static-json.json').default}>static JSON " `; diff --git a/packages/docusaurus-plugin-content-docs/src/__tests__/__fixtures__/simple-site/docs/foo/baz.md b/packages/docusaurus-plugin-content-docs/src/__tests__/__fixtures__/simple-site/docs/foo/baz.md index 3407ccd1b0..c3f676e276 100644 --- a/packages/docusaurus-plugin-content-docs/src/__tests__/__fixtures__/simple-site/docs/foo/baz.md +++ b/packages/docusaurus-plugin-content-docs/src/__tests__/__fixtures__/simple-site/docs/foo/baz.md @@ -10,7 +10,7 @@ tags: permalink: tag2-custom-permalink --- -# Baz markdown title +# Baz Markdown title ## Images diff --git a/packages/docusaurus-plugin-content-pages/src/__tests__/__fixtures__/website/i18n/fr/docusaurus-plugin-content-pages/hello/translatedMd.md b/packages/docusaurus-plugin-content-pages/src/__tests__/__fixtures__/website/i18n/fr/docusaurus-plugin-content-pages/hello/translatedMd.md index 51a19b7d48..23291b31bb 100644 --- a/packages/docusaurus-plugin-content-pages/src/__tests__/__fixtures__/website/i18n/fr/docusaurus-plugin-content-pages/hello/translatedMd.md +++ b/packages/docusaurus-plugin-content-pages/src/__tests__/__fixtures__/website/i18n/fr/docusaurus-plugin-content-pages/hello/translatedMd.md @@ -1 +1 @@ -translated markdown page (fr) +translated Markdown page (fr) diff --git a/packages/docusaurus-plugin-content-pages/src/__tests__/__fixtures__/website/src/pages/hello/mdxPage.mdx b/packages/docusaurus-plugin-content-pages/src/__tests__/__fixtures__/website/src/pages/hello/mdxPage.mdx index 54ce38beb5..27b0b9f9be 100644 --- a/packages/docusaurus-plugin-content-pages/src/__tests__/__fixtures__/website/src/pages/hello/mdxPage.mdx +++ b/packages/docusaurus-plugin-content-pages/src/__tests__/__fixtures__/website/src/pages/hello/mdxPage.mdx @@ -1,5 +1,5 @@ --- -title: mdx page -description: my mdx page +title: MDX page +description: my MDX page --- MDX page diff --git a/packages/docusaurus-plugin-content-pages/src/__tests__/__fixtures__/website/src/pages/hello/translatedMd.md b/packages/docusaurus-plugin-content-pages/src/__tests__/__fixtures__/website/src/pages/hello/translatedMd.md index d39c88c732..9e232d95ab 100644 --- a/packages/docusaurus-plugin-content-pages/src/__tests__/__fixtures__/website/src/pages/hello/translatedMd.md +++ b/packages/docusaurus-plugin-content-pages/src/__tests__/__fixtures__/website/src/pages/hello/translatedMd.md @@ -1 +1 @@ -translated markdown page +translated Markdown page diff --git a/packages/docusaurus-plugin-content-pages/src/__tests__/__snapshots__/index.test.ts.snap b/packages/docusaurus-plugin-content-pages/src/__tests__/__snapshots__/index.test.ts.snap index bc0f5cef29..c4c22e8492 100644 --- a/packages/docusaurus-plugin-content-pages/src/__tests__/__snapshots__/index.test.ts.snap +++ b/packages/docusaurus-plugin-content-pages/src/__tests__/__snapshots__/index.test.ts.snap @@ -21,14 +21,14 @@ exports[`docusaurus-plugin-content-pages loads simple pages 1`] = ` "type": "mdx", }, { - "description": "my mdx page", + "description": "my MDX page", "frontMatter": { - "description": "my mdx page", - "title": "mdx page", + "description": "my MDX page", + "title": "MDX page", }, "permalink": "/hello/mdxPage", "source": "@site/src/pages/hello/mdxPage.mdx", - "title": "mdx page", + "title": "MDX page", "type": "mdx", }, { @@ -37,7 +37,7 @@ exports[`docusaurus-plugin-content-pages loads simple pages 1`] = ` "type": "jsx", }, { - "description": "translated markdown page", + "description": "translated Markdown page", "frontMatter": {}, "permalink": "/hello/translatedMd", "source": "@site/src/pages/hello/translatedMd.md", @@ -73,14 +73,14 @@ exports[`docusaurus-plugin-content-pages loads simple pages with french translat "type": "mdx", }, { - "description": "my mdx page", + "description": "my MDX page", "frontMatter": { - "description": "my mdx page", - "title": "mdx page", + "description": "my MDX page", + "title": "MDX page", }, "permalink": "/fr/hello/mdxPage", "source": "@site/src/pages/hello/mdxPage.mdx", - "title": "mdx page", + "title": "MDX page", "type": "mdx", }, { @@ -89,7 +89,7 @@ exports[`docusaurus-plugin-content-pages loads simple pages with french translat "type": "jsx", }, { - "description": "translated markdown page (fr)", + "description": "translated Markdown page (fr)", "frontMatter": {}, "permalink": "/fr/hello/translatedMd", "source": "@site/i18n/fr/docusaurus-plugin-content-pages/hello/translatedMd.md", diff --git a/website/_dogfooding/README.md b/website/_dogfooding/README.md index 8acadfac2e..f0a8a5719c 100644 --- a/website/_dogfooding/README.md +++ b/website/_dogfooding/README.md @@ -15,4 +15,4 @@ Fancy things we can test for here: - \_ prefix convention - Huge sidebars impact - Using folders with spaces on purpose -- Importing md docs that are out of content plugin folders as partials (such as this README file!) +- Importing MD docs that are out of content plugin folders as partials (such as this README file!) diff --git a/website/_dogfooding/_docs tests/toc/toc-test-bad.mdx b/website/_dogfooding/_docs tests/toc/toc-test-bad.mdx index b894a0a17e..8f91e5217c 100644 --- a/website/_dogfooding/_docs tests/toc/toc-test-bad.mdx +++ b/website/_dogfooding/_docs tests/toc/toc-test-bad.mdx @@ -3,7 +3,7 @@ toc_min_heading_level: 2 toc_max_heading_level: 6 --- -Test the TOC behavior of a real-world md doc with invalid headings +Test the TOC behavior of a real-world MD doc with invalid headings --- diff --git a/website/_dogfooding/_docs tests/toc/toc-test-good.mdx b/website/_dogfooding/_docs tests/toc/toc-test-good.mdx index 6f85a62fea..c8f9f45342 100644 --- a/website/_dogfooding/_docs tests/toc/toc-test-good.mdx +++ b/website/_dogfooding/_docs tests/toc/toc-test-good.mdx @@ -3,7 +3,7 @@ toc_min_heading_level: 2 toc_max_heading_level: 6 --- -Test the TOC behavior of a real-world md doc with valid headings +Test the TOC behavior of a real-world MD doc with valid headings --- diff --git a/website/_dogfooding/_pages tests/markdown-tests.md b/website/_dogfooding/_pages tests/markdown-tests.md index 80d9ea8bad..48420cb718 100644 --- a/website/_dogfooding/_pages tests/markdown-tests.md +++ b/website/_dogfooding/_pages tests/markdown-tests.md @@ -1,6 +1,6 @@ # Markdown tests -This is a test page to see if Docusaurus markdown features are working properly +This is a test page to see if Docusaurus Markdown features are working properly ## Linking to assets diff --git a/website/_dogfooding/_pages tests/markdownPageTests.md b/website/_dogfooding/_pages tests/markdownPageTests.md index c3428f517c..8dcbf82a82 100644 --- a/website/_dogfooding/_pages tests/markdownPageTests.md +++ b/website/_dogfooding/_pages tests/markdownPageTests.md @@ -6,7 +6,7 @@ wrapperClassName: docusaurus-markdown-example # Markdown page tests -This is a page generated from markdown to illustrate the Markdown page feature and test some edge cases. +This is a page generated from Markdown to illustrate the Markdown page feature and test some edge cases. :::info diff --git a/website/blog/2017-12-14-introducing-docusaurus.md b/website/blog/2017-12-14-introducing-docusaurus.md index 309a8ba2c3..a882e2352a 100644 --- a/website/blog/2017-12-14-introducing-docusaurus.md +++ b/website/blog/2017-12-14-introducing-docusaurus.md @@ -17,7 +17,7 @@ We created [Docusaurus](https://docusaurus.io) for the following reasons: -Docusaurus is a tool designed to make it easy for teams to publish documentation websites without having to worry about the infrastructure and design details. At its core, all a user has to provide are documentation files written in markdown, customization of a provided home page written in React, and a few configuration modifications. Docusaurus handles the rest by providing default styles, site formatting, and simple document navigation. Getting started is easy, as users can [install](https://v1.docusaurus.io/docs/en/installation.html) it using `npm` or `yarn` via a simple initialization script that [creates a working example website out of the box](https://v1.docusaurus.io/docs/en/site-preparation.html). +Docusaurus is a tool designed to make it easy for teams to publish documentation websites without having to worry about the infrastructure and design details. At its core, all a user has to provide are documentation files written in Markdown, customization of a provided home page written in React, and a few configuration modifications. Docusaurus handles the rest by providing default styles, site formatting, and simple document navigation. Getting started is easy, as users can [install](https://v1.docusaurus.io/docs/en/installation.html) it using `npm` or `yarn` via a simple initialization script that [creates a working example website out of the box](https://v1.docusaurus.io/docs/en/site-preparation.html). Docusaurus also provides core website and documentation features out-of-the-box including [blog support](https://v1.docusaurus.io/docs/en/blog.html), [internationalization](https://v1.docusaurus.io/docs/en/translation.html), [search](https://v1.docusaurus.io/docs/en/search.html), and [versioning](https://v1.docusaurus.io/docs/en/versioning.html). While some projects may not require any of these features, enabling them is generally a matter of updating configuration options instead of having to add the infrastructure from the ground up. As more features get added to Docusaurus, users just can easily update to the latest version. This can be done by simply running npm or yarn update and updating configuration options. Users or teams will no longer need to manually rework their entire website infrastructure each time a new feature gets added. @@ -67,11 +67,11 @@ root-of-repo │ └── static ``` -With the exception of node_modules and package.json, all the directories and files you see are where you customize and add content to your Docusaurus-based website. The docs folder is where you add your markdown that represents your documentation; the blog folder is where you add your markdown for your [blog posts](https://v1.docusaurus.io/docs/en/blog.html); `siteConfig.js` is where you make most of the [customizations](https://v1.docusaurus.io/docs/en/site-config.html) for your site; `sidebars.json` is where you maintain the layout and content of the [sidebar](https://v1.docusaurus.io/docs/en/navigation.html) for your documentation; the `pages` folder is where you add [custom](https://v1.docusaurus.io/docs/en/custom-pages.html) pages for your site; the `static` folder is where all of your static assets go (e.g., CSS stylesheets and images); and the `core` folder is where you can customize core components of the site, in this case the footer. +With the exception of node_modules and package.json, all the directories and files you see are where you customize and add content to your Docusaurus-based website. The docs folder is where you add your Markdown that represents your documentation; the blog folder is where you add your Markdown for your [blog posts](https://v1.docusaurus.io/docs/en/blog.html); `siteConfig.js` is where you make most of the [customizations](https://v1.docusaurus.io/docs/en/site-config.html) for your site; `sidebars.json` is where you maintain the layout and content of the [sidebar](https://v1.docusaurus.io/docs/en/navigation.html) for your documentation; the `pages` folder is where you add [custom](https://v1.docusaurus.io/docs/en/custom-pages.html) pages for your site; the `static` folder is where all of your static assets go (e.g., CSS stylesheets and images); and the `core` folder is where you can customize core components of the site, in this case the footer. ## How does Docusaurus work? -Docusaurus is written primarily in JavaScript and [React](https://facebook.github.io/react), replacing Jekyll which we used in the old template. We use [Remarkable](https://github.com/jonschlinkert/remarkable) for our markdown rendering and [highlight.js](https://highlightjs.org/) for our code block syntax highlighting. The core of Docusaurus' functionality is in the [lib directory](https://github.com/facebookexperimental/Docusaurus/tree/master/lib) of the [Docusaurus repo](https://github.com/facebook/docusaurus/). The general structure looks like: +Docusaurus is written primarily in JavaScript and [React](https://facebook.github.io/react), replacing Jekyll which we used in the old template. We use [Remarkable](https://github.com/jonschlinkert/remarkable) for our Markdown rendering and [highlight.js](https://highlightjs.org/) for our code block syntax highlighting. The core of Docusaurus' functionality is in the [lib directory](https://github.com/facebookexperimental/Docusaurus/tree/master/lib) of the [Docusaurus repo](https://github.com/facebook/docusaurus/). The general structure looks like: ```bash root-of-Docusaurus @@ -92,12 +92,12 @@ root-of-Docusaurus │ └── write-translations.js ``` -The key files here are build-files.js and start-server.js. There are many similarities between these two files: `build-files.js` is used to build the physical artifacts for serving by an external web server. `start-server.js` is used to run the Docusaurus server and locally test your site. Both go through the following general process to take all of the markdown and configuration to create a runnable website: +The key files here are build-files.js and start-server.js. There are many similarities between these two files: `build-files.js` is used to build the physical artifacts for serving by an external web server. `start-server.js` is used to run the Docusaurus server and locally test your site. Both go through the following general process to take all of the Markdown and configuration to create a runnable website: 1. Process your website settings in `siteConfig.js` -1. Read the document metadata that exists in all the markdown files in your docs directory. -1. Create a table of contents for your documents based upon the ids extracted from the metadata. -1. Convert the markdown to HTML, including doing link replacement. +1. Read the document metadata that exists in all the Markdown files in your docs directory. +1. Create a table of contents for your documents based upon the IDs extracted from the metadata. +1. Convert the Markdown to HTML, including doing link replacement. 1. These files will go in a build/docs directory of the compiled site, and any translated versions will go into a language specific folder within the build/docs folder. 1. Repeat 1-3 for blog posts. 1. The blog file will go in a build/blog directory of the compiled site. diff --git a/website/blog/2018-04-30-How-I-Converted-Profilo-To-Docusaurus.md b/website/blog/2018-04-30-How-I-Converted-Profilo-To-Docusaurus.md index cf42f021b6..bb2022089f 100644 --- a/website/blog/2018-04-30-How-I-Converted-Profilo-To-Docusaurus.md +++ b/website/blog/2018-04-30-How-I-Converted-Profilo-To-Docusaurus.md @@ -7,7 +7,7 @@ authorTwitter: abernathyca tags: [profilo, adoption] --- -> _“Joel and I were discussing having a website and how it would have been great to launch with it. So I challenged myself to add Docusaurus support. It took just over an hour and a half. I'm going to send you a PR with the addition so you can take a look and see if you like it. Your workflow for adding docs wouldn't be much different from editing those markdown files.”_ +> _“Joel and I were discussing having a website and how it would have been great to launch with it. So I challenged myself to add Docusaurus support. It took just over an hour and a half. I'm going to send you a PR with the addition so you can take a look and see if you like it. Your workflow for adding docs wouldn't be much different from editing those Markdown files.”_ > > _— Note sent to the Profilo team_ diff --git a/website/blog/2018-09-11-Towards-Docusaurus-2.md b/website/blog/2018-09-11-Towards-Docusaurus-2.md index 8f9c5c1355..0472a926b8 100644 --- a/website/blog/2018-09-11-Towards-Docusaurus-2.md +++ b/website/blog/2018-09-11-Towards-Docusaurus-2.md @@ -83,9 +83,9 @@ For Docusaurus 2, **layout and styling should be controlled by the user**. Docus ### Markdown -Our markdown parsing is currently powered by [Remarkable](https://github.com/jonschlinkert/remarkable). What if the user wants to use [markdown-it](https://github.com/markdown-it/markdown-it) or even [MDX](https://github.com/mdx-js/mdx)? And then there is an issue of which syntax highlighter to use, (e.g: [Prism](https://prismjs.com/) vs [Highlight.js](https://highlightjs.org/)). We should leave these choices open to the user. +Our Markdown parsing is currently powered by [Remarkable](https://github.com/jonschlinkert/remarkable). What if the user wants to use [Markdown-it](https://github.com/Markdown-it/Markdown-it) or even [MDX](https://github.com/mdx-js/mdx)? And then there is an issue of which syntax highlighter to use, (e.g: [Prism](https://prismjs.com/) vs [Highlight.js](https://highlightjs.org/)). We should leave these choices open to the user. -For Docusaurus 2, **users can eject and choose their own markdown parser**. It does not matter if they want to use another markdown parser such as [Remark](https://github.com/remarkjs/remark), or even their own in-house markdown parser. As a rule of thumb, the user has to provide a React component, in which we will provide a children props containing the _RAW string of markdown_. By default, we will use Remarkable for the markdown parser and Highlight.js for the syntax highlighting. The default parser could still change in the future as we're still experimenting with different markdown parsers. +For Docusaurus 2, **users can eject and choose their own Markdown parser**. It does not matter if they want to use another Markdown parser such as [Remark](https://github.com/remarkjs/remark), or even their own in-house Markdown parser. As a rule of thumb, the user has to provide a React component, in which we will provide a children props containing the _RAW string of Markdown_. By default, we will use Remarkable for the Markdown parser and Highlight.js for the syntax highlighting. The default parser could still change in the future as we're still experimenting with different Markdown parsers. ### Search diff --git a/website/docs/api/docusaurus.config.js.md b/website/docs/api/docusaurus.config.js.md index 0b0a6ecf88..45142e79ed 100644 --- a/website/docs/api/docusaurus.config.js.md +++ b/website/docs/api/docusaurus.config.js.md @@ -63,7 +63,7 @@ module.exports = { - Type: `string` -URL for your website. This can also be considered the top-level hostname. For example, `https://facebook.github.io` is the URL of https://facebook.github.io/metro/, and `https://docusaurus.io` is the URL for https://docusaurus.io. This field is related to the [baseUrl](#baseurl) field. +URL for your website. This can also be considered the top-level hostname. For example, `https://facebook.github.io` is the URL of https://facebook.github.io/metro/, and `https://docusaurus.io` is the URL for https://docusaurus.io. This field is related to the [`baseUrl`](#baseUrl) field. ```js title="docusaurus.config.js" module.exports = { @@ -75,7 +75,7 @@ module.exports = { - Type: `string` -Base URL for your site. Can be considered as the path after the host. For example, `/metro/` is the base URL of https://facebook.github.io/metro/. For URLs that have no path, the baseUrl should be set to `/`. This field is related to the [url](#url) field. Always has both leading and trailing slash. +Base URL for your site. Can be considered as the path after the host. For example, `/metro/` is the base URL of https://facebook.github.io/metro/. For URLs that have no path, the baseUrl should be set to `/`. This field is related to the [`url`](#url) field. Always has both leading and trailing slash. ```js title="docusaurus.config.js" module.exports = { @@ -152,7 +152,7 @@ module.exports = { - `locales`: List of locales deployed on your site. Must contain `defaultLocale`. - `localeConfigs`: Individual options for each locale. - `label`: The label displayed for this locale in the locales dropdown. - - `direction`: `ltr` (default) or `rtl` (for [right-to-left languages](https://developer.mozilla.org/en-US/docs/Glossary/rtl) like Farsi, Arabic, Hebrew, etc.). Used to select the locale's CSS and html meta attribute. + - `direction`: `ltr` (default) or `rtl` (for [right-to-left languages](https://developer.mozilla.org/en-US/docs/Glossary/rtl) like Farsi, Arabic, Hebrew, etc.). Used to select the locale's CSS and HTML meta attribute. - `htmlLang`: BCP 47 language tag to use in `` and in `` - `calendar`: the [calendar](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/Locale/calendar) used to calculate the date era. Note that it doesn't control the actual string displayed: `MM/DD/YYYY` and `DD/MM/YYYY` are both `gregory`. To choose the format (`DD/MM/YYYY` or `MM/DD/YYYY`), set your locale name to `en-GB` or `en-US` (`en` means `en-US`). @@ -188,9 +188,9 @@ The broken links detection is only available for a production build (`docusaurus - Type: `'ignore' | 'log' | 'warn' | 'error' | 'throw'` -The behavior of Docusaurus when it detects any broken markdown link. +The behavior of Docusaurus when it detects any broken Markdown link. -By default, it prints a warning, to let you know about your broken markdown link, but you can change this security if needed. +By default, it prints a warning, to let you know about your broken Markdown link, but you can change this security if needed. ### `onDuplicateRoutes` {#onDuplicateRoutes} @@ -547,7 +547,7 @@ module.exports = { }; ``` -### `baseUrlIssueBanner` {#baseurlIssueBanner} +### `baseUrlIssueBanner` {#baseUrlIssueBanner} - Type: `boolean` diff --git a/website/docs/api/plugin-methods/i18n-lifecycles.md b/website/docs/api/plugin-methods/i18n-lifecycles.md index 83f1087cc4..1002dd74a3 100644 --- a/website/docs/api/plugin-methods/i18n-lifecycles.md +++ b/website/docs/api/plugin-methods/i18n-lifecycles.md @@ -103,7 +103,7 @@ module.exports = function (context, options) { Themes using the `` API can provide default code translation messages. -It should return messages in `Record`, where keys are translation ids and values are messages (without the description) localized using the site's current locale. +It should return messages in `Record`, where keys are translation IDs and values are messages (without the description) localized using the site's current locale. Example: diff --git a/website/docs/api/plugins/plugin-content-blog.md b/website/docs/api/plugins/plugin-content-blog.md index 552bed3562..696b410285 100644 --- a/website/docs/api/plugins/plugin-content-blog.md +++ b/website/docs/api/plugins/plugin-content-blog.md @@ -199,7 +199,7 @@ Accepted fields: | `keywords` | `string[]` | `undefined` | Keywords meta tag, which will become the `` in ``, used by search engines. | | `description` | `string` | The first line of Markdown content | The description of your document, which will become the `` and `` in ``, used by search engines. | | `image` | `string` | `undefined` | Cover or thumbnail image that will be used when displaying the link to your post. | -| `slug` | `string` | File path | Allows to customize the blog post url (`//`). Support multiple patterns: `slug: my-blog-post`, `slug: /my/path/to/blog/post`, slug: `/`. | +| `slug` | `string` | File path | Allows to customize the blog post URL (`//`). Support multiple patterns: `slug: my-blog-post`, `slug: /my/path/to/blog/post`, slug: `/`. | ```mdx-code-block diff --git a/website/docs/api/plugins/plugin-content-docs.md b/website/docs/api/plugins/plugin-content-docs.md index fdced719db..84680c46c9 100644 --- a/website/docs/api/plugins/plugin-content-docs.md +++ b/website/docs/api/plugins/plugin-content-docs.md @@ -284,7 +284,7 @@ Accepted fields: | `keywords` | `string[]` | `undefined` | Keywords meta tag for the document page, for search engines. | | `description` | `string` | The first line of Markdown content | The description of your document, which will become the `` and `` in ``, used by search engines. | | `image` | `string` | `undefined` | Cover or thumbnail image that will be used when displaying the link to your post. | -| `slug` | `string` | File path | Allows to customize the document url (`//`). Support multiple patterns: `slug: my-doc`, `slug: /my/path/myDoc`, `slug: /`. | +| `slug` | `string` | File path | Allows to customize the document URL (`//`). Support multiple patterns: `slug: my-doc`, `slug: /my/path/myDoc`, `slug: /`. | | `tags` | `Tag[]` | `undefined` | A list of strings or objects of two string fields `label` and `permalink` to tag to your docs. | | `draft` | `boolean` | `false` | A boolean flag to indicate that a document is a work-in-progress. Draft documents will only be displayed during development. | | `last_update` | `FileChange` | `undefined` | Allows overriding the last updated author and/or date. Date can be any [parsable date string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/parse). | diff --git a/website/docs/api/plugins/plugin-pwa.md b/website/docs/api/plugins/plugin-pwa.md index 79fd6b9284..71f63febc6 100644 --- a/website/docs/api/plugins/plugin-pwa.md +++ b/website/docs/api/plugins/plugin-pwa.md @@ -160,7 +160,7 @@ module.exports = { modifyURLPrefix: { //... }, - // We already add regular static assets (html, images...) to be available offline + // We already add regular static assets (HTML, images...) to be available offline // You can add more files according to your needs globPatterns: ['**/*.{pdf,docx,xlsx}'], // ... diff --git a/website/docs/api/themes/theme-configuration.md b/website/docs/api/themes/theme-configuration.md index 2a64ec15da..356d61f62a 100644 --- a/website/docs/api/themes/theme-configuration.md +++ b/website/docs/api/themes/theme-configuration.md @@ -90,7 +90,7 @@ module.exports = { ### Metadata {#metadata} -You can configure additional html metadata (and override existing ones). +You can configure additional HTML metadata (and override existing ones). Accepted fields: @@ -901,7 +901,7 @@ Accepted fields of each `FooterItem`: | `label` | `string` | **Required** | Text to be displayed for this link. | | `to` | `string` | **Required** | Client-side routing, used for navigating within the website. The baseUrl will be automatically prepended to this value. | | `href` | `string` | **Required** | A full-page navigation, used for navigating outside of the website. **Only one of `to` or `href` should be used.** | -| `html` | `string` | `undefined` | Renders the html pass-through instead of a simple link. In case `html` is used, no other options should be provided. | +| `html` | `string` | `undefined` | Renders the HTML pass-through instead of a simple link. In case `html` is used, no other options should be provided. | ```mdx-code-block diff --git a/website/docs/cli.md b/website/docs/cli.md index 92bf71a806..5fb2356e77 100644 --- a/website/docs/cli.md +++ b/website/docs/cli.md @@ -41,7 +41,7 @@ Builds and serves a preview of your site locally with [Webpack Dev Server](https | `--host` | `localhost` | Specify a host to use. For example, if you want your server to be accessible externally, you can use `--host 0.0.0.0`. | | `--hot-only` | `false` | Enables Hot Module Replacement without page refresh as a fallback in case of build failures. More information [here](https://webpack.js.org/configuration/dev-server/#devserverhotonly). | | `--no-open` | `false` | Do not open automatically the page in the browser. | -| `--config` | `undefined` | Path to docusaurus config file, default to `[siteDir]/docusaurus.config.js` | +| `--config` | `undefined` | Path to Docusaurus config file, default to `[siteDir]/docusaurus.config.js` | | `--poll [optionalIntervalMs]` | `false` | Use polling of files rather than watching for live reload as a fallback in environments where watching doesn't work. More information [here](https://webpack.js.org/configuration/watch/#watchoptionspoll). | | `--no-minify` | `false` | Build website without minimizing JS/CSS bundles. | @@ -87,7 +87,7 @@ Compiles your site for production. | --- | --- | --- | | `--bundle-analyzer` | `false` | Analyze your bundle with the [webpack bundle analyzer](https://github.com/webpack-contrib/webpack-bundle-analyzer). | | `--out-dir` | `build` | The full path for the new output directory, relative to the current workspace. | -| `--config` | `undefined` | Path to docusaurus config file, default to `[siteDir]/docusaurus.config.js` | +| `--config` | `undefined` | Path to Docusaurus config file, default to `[siteDir]/docusaurus.config.js` | | `--no-minify` | `false` | Build website without minimizing JS/CSS bundles. | :::info @@ -137,7 +137,7 @@ Deploys your site with [GitHub Pages](https://pages.github.com/). Check out the | --- | --- | --- | | `--out-dir` | `build` | The full path for the new output directory, relative to the current workspace. | | `--skip-build` | `false` | Deploy website without building it. This may be useful when using a custom deploy script. | -| `--config` | `undefined` | Path to docusaurus config file, default to `[siteDir]/docusaurus.config.js` | +| `--config` | `undefined` | Path to Docusaurus config file, default to `[siteDir]/docusaurus.config.js` | ### `docusaurus serve [siteDir]` {#docusaurus-serve-sitedir} @@ -148,7 +148,7 @@ Serve your built website locally. | `--port` | `3000` | Use specified port | | `--dir` | `build` | The full path for the output directory, relative to the current workspace | | `--build` | `false` | Build website before serving | -| `--config` | `undefined` | Path to docusaurus config file, default to `[siteDir]/docusaurus.config.js` | +| `--config` | `undefined` | Path to Docusaurus config file, default to `[siteDir]/docusaurus.config.js` | | `--host` | `localhost` | Specify a host to use. For example, if you want your server to be accessible externally, you can use `--host 0.0.0.0`. | | `--no-open` | `false` locally, `true` in CI | Do not open a browser window to the server location. | @@ -168,12 +168,12 @@ By default, the files are written in `website/i18n//...`. | --- | --- | --- | | `--locale` | `` | Define which locale folder you want to write translations the JSON files in | | `--override` | `false` | Override existing translation messages | -| `--config` | `undefined` | Path to docusaurus config file, default to `[siteDir]/docusaurus.config.js` | +| `--config` | `undefined` | Path to Docusaurus config file, default to `[siteDir]/docusaurus.config.js` | | `--messagePrefix` | `''` | Allows adding a prefix to each translation message, to help you highlight untranslated strings | ### `docusaurus write-heading-ids [siteDir] [files]` {#docusaurus-write-heading-ids-sitedir} -Add [explicit heading ids](./guides/markdown-features/markdown-features-toc.mdx#explicit-ids) to the Markdown documents of your site. +Add [explicit heading IDs](./guides/markdown-features/markdown-features-toc.mdx#explicit-ids) to the Markdown documents of your site. | Name | Default | Description | | --- | --- | --- | diff --git a/website/docs/configuration.md b/website/docs/configuration.md index fcfc92e0bc..eb192c6f92 100644 --- a/website/docs/configuration.md +++ b/website/docs/configuration.md @@ -179,4 +179,4 @@ module.exports = { }; ``` -Most of the time, this configuration will work just fine. If you want to customize your babel configuration (e.g. to add support for Flow), you can directly edit this file. For your changes to take effect, you need to restart the Docusaurus dev server. +Most of the time, this configuration will work just fine. If you want to customize your Babel configuration (e.g. to add support for Flow), you can directly edit this file. For your changes to take effect, you need to restart the Docusaurus dev server. diff --git a/website/docs/deployment.mdx b/website/docs/deployment.mdx index 8170837272..f951d73d7b 100644 --- a/website/docs/deployment.mdx +++ b/website/docs/deployment.mdx @@ -183,8 +183,8 @@ Some Docusaurus sites put the `docs` folder outside of `website` (most likely fo ```bash repo # git root -├── docs # md files -└── website # docusaurus root +├── docs # MD files +└── website # Docusaurus root ``` If you decide to use the `website` folder as Netlify's base directory, Netlify will not trigger builds when you update the `docs` folder, and you need to configure a [custom `ignore` command](https://docs.netlify.com/configure-builds/common-configurations/ignore-builds/): @@ -622,7 +622,7 @@ steps: ### Using Drone {#using-drone} 1. Create a new SSH key that will be the [deploy key](https://docs.github.com/en/free-pro-team@latest/developers/overview/managing-deploy-keys#deploy-keys) for your project. -2. Name your private and public keys to be specific and so that it does not overwrite your other [ssh keys](https://docs.github.com/en/free-pro-team@latest/github/authenticating-to-github/generating-a-new-ssh-key-and-adding-it-to-the-ssh-agent). +2. Name your private and public keys to be specific and so that it does not overwrite your other [SSH keys](https://docs.github.com/en/free-pro-team@latest/github/authenticating-to-github/generating-a-new-ssh-key-and-adding-it-to-the-ssh-agent). 3. Go to `https://github.com/USERNAME/REPO/settings/keys` and add a new deploy key by pasting in the public key you just generated. 4. Open your Drone.io dashboard and log in. The URL looks like `https://cloud.drone.io/USERNAME/REPO`. 5. Click on the repository, click on activate repository, and add a secret called `git_deploy_private_key` with your private key value that you just generated. diff --git a/website/docs/docusaurus-core.md b/website/docs/docusaurus-core.md index 807727872e..ee932f0eed 100644 --- a/website/docs/docusaurus-core.md +++ b/website/docs/docusaurus-core.md @@ -479,7 +479,7 @@ Prefer a `require()` call for [assets](./guides/markdown-features/markdown-featu ### `useBaseUrlUtils` {#useBaseUrlUtils} -Sometimes `useBaseUrl` is not good enough. This hook return additional utils related to your site's base url. +Sometimes `useBaseUrl` is not good enough. This hook return additional utils related to your site's base URL. - `withBaseUrl`: useful if you need to add base URLs to multiple URLs at once. diff --git a/website/docs/guides/docs/sidebar/autogenerated.md b/website/docs/guides/docs/sidebar/autogenerated.md index a8268f4581..88361f969d 100644 --- a/website/docs/guides/docs/sidebar/autogenerated.md +++ b/website/docs/guides/docs/sidebar/autogenerated.md @@ -411,7 +411,7 @@ By default, Docusaurus will **remove the number prefix** from the doc id, title, **Prefer using [additional metadata](#autogenerated-sidebar-metadata)**. -Updating a number prefix can be annoying, as it can require **updating multiple existing markdown links**: +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); diff --git a/website/docs/guides/docs/sidebar/items.md b/website/docs/guides/docs/sidebar/items.md index 097e3293eb..6a67d8ee58 100644 --- a/website/docs/guides/docs/sidebar/items.md +++ b/website/docs/guides/docs/sidebar/items.md @@ -60,7 +60,7 @@ module.exports = { }; ``` -If you use the doc shorthand or [autogenerated](#sidebar-item-autogenerated) sidebar, you would lose the ability to customize the sidebar label through item definition. You can, however, use the `sidebar_label` markdown front matter within that doc, which has higher precedence over the `label` key in the sidebar item. Similarly, you can use `sidebar_custom_props` to declare custom metadata for a doc page. +If you use the doc shorthand or [autogenerated](#sidebar-item-autogenerated) sidebar, you would lose the ability to customize the sidebar label through item definition. You can, however, use the `sidebar_label` Markdown front matter within that doc, which has higher precedence over the `label` key in the sidebar item. Similarly, you can use `sidebar_custom_props` to declare custom metadata for a doc page. :::note diff --git a/website/docs/guides/markdown-features/markdown-features-admonitions.mdx b/website/docs/guides/markdown-features/markdown-features-admonitions.mdx index 53858f86d0..719dd371c9 100644 --- a/website/docs/guides/markdown-features/markdown-features-admonitions.mdx +++ b/website/docs/guides/markdown-features/markdown-features-admonitions.mdx @@ -18,31 +18,31 @@ Example: ```md :::note -Some **content** with _markdown_ `syntax`. Check [this `api`](#). +Some **content** with _Markdown_ `syntax`. Check [this `api`](#). ::: :::tip -Some **content** with _markdown_ `syntax`. Check [this `api`](#). +Some **content** with _Markdown_ `syntax`. Check [this `api`](#). ::: :::info -Some **content** with _markdown_ `syntax`. Check [this `api`](#). +Some **content** with _Markdown_ `syntax`. Check [this `api`](#). ::: :::caution -Some **content** with _markdown_ `syntax`. Check [this `api`](#). +Some **content** with _Markdown_ `syntax`. Check [this `api`](#). ::: :::danger -Some **content** with _markdown_ `syntax`. Check [this `api`](#). +Some **content** with _Markdown_ `syntax`. Check [this `api`](#). ::: ``` @@ -52,31 +52,31 @@ Some **content** with _markdown_ `syntax`. Check [this `api`](#). :::note -Some **content** with _markdown_ `syntax`. Check [this `api`](#). +Some **content** with _Markdown_ `syntax`. Check [this `api`](#). ::: :::tip -Some **content** with _markdown_ `syntax`. Check [this `api`](#). +Some **content** with _Markdown_ `syntax`. Check [this `api`](#). ::: :::info -Some **content** with _markdown_ `syntax`. Check [this `api`](#). +Some **content** with _Markdown_ `syntax`. Check [this `api`](#). ::: :::caution -Some **content** with _markdown_ `syntax`. Check [this `api`](#). +Some **content** with _Markdown_ `syntax`. Check [this `api`](#). ::: :::danger -Some **content** with _markdown_ `syntax`. Check [this `api`](#). +Some **content** with _Markdown_ `syntax`. Check [this `api`](#). ::: @@ -112,7 +112,7 @@ You may also specify an optional title ```md :::note Your Title -Some **content** with _markdown_ `syntax`. +Some **content** with _Markdown_ `syntax`. ::: ``` @@ -122,7 +122,7 @@ Some **content** with _markdown_ `syntax`. :::note Your Title -Some **content** with _markdown_ `syntax`. +Some **content** with _Markdown_ `syntax`. ::: diff --git a/website/docs/guides/markdown-features/markdown-features-assets.mdx b/website/docs/guides/markdown-features/markdown-features-assets.mdx index 87212049b2..58c875c810 100644 --- a/website/docs/guides/markdown-features/markdown-features-assets.mdx +++ b/website/docs/guides/markdown-features/markdown-features-assets.mdx @@ -110,7 +110,7 @@ or -:::info markdown links are always file paths +:::info Markdown links are always file paths If you use the Markdown image or link syntax, all asset paths will be resolved as file paths by Docusaurus and automatically converted to `require()` calls. You don't need to use `require()` in Markdown unless you use the JSX syntax, which you do have to handle yourself. diff --git a/website/docs/guides/markdown-features/markdown-features-code-blocks.mdx b/website/docs/guides/markdown-features/markdown-features-code-blocks.mdx index f6b47f22ac..92d3f540b0 100644 --- a/website/docs/guides/markdown-features/markdown-features-code-blocks.mdx +++ b/website/docs/guides/markdown-features/markdown-features-code-blocks.mdx @@ -455,7 +455,7 @@ To use the plugin, create a code block with `live` attached to the language meta function Clock(props) { const [date, setDate] = useState(new Date()); useEffect(() => { - var timerID = setInterval(() => tick(), 1000); + const timerID = setInterval(() => tick(), 1000); return function cleanup() { clearInterval(timerID); @@ -485,7 +485,7 @@ The code block will be rendered as an interactive editor. Changes to the code wi function Clock(props) { const [date, setDate] = useState(new Date()); useEffect(() => { - var timerID = setInterval(() => tick(), 1000); + const timerID = setInterval(() => tick(), 1000); return function cleanup() { clearInterval(timerID); diff --git a/website/docs/guides/markdown-features/markdown-features-math-equations.mdx b/website/docs/guides/markdown-features/markdown-features-math-equations.mdx index 1f6e322825..631a9dbaa5 100644 --- a/website/docs/guides/markdown-features/markdown-features-math-equations.mdx +++ b/website/docs/guides/markdown-features/markdown-features-math-equations.mdx @@ -132,7 +132,7 @@ module.exports = { ## Self-hosting KaTeX assets {#self-hosting-katex-assets} -Loading stylesheets, fonts, and javascript libraries from CDN sources is a good practice for popular libraries and assets, since it reduces the amount of assets you have to host. In case you prefer to self-host the `katex.min.css` (along with required KaTeX fonts), you can download the latest version from [KaTeX GitHub releases](https://github.com/KaTeX/KaTeX/releases), extract and copy `katex.min.css` and `fonts` directory (only `.woff2` font types should be enough) to your site's `static` directory, and in `docusaurus.config.js`, replace the stylesheet's `href` from the CDN url to your local path (say, `/katex/katex.min.css`). +Loading stylesheets, fonts, and JavaScript libraries from CDN sources is a good practice for popular libraries and assets, since it reduces the amount of assets you have to host. In case you prefer to self-host the `katex.min.css` (along with required KaTeX fonts), you can download the latest version from [KaTeX GitHub releases](https://github.com/KaTeX/KaTeX/releases), extract and copy `katex.min.css` and `fonts` directory (only `.woff2` font types should be enough) to your site's `static` directory, and in `docusaurus.config.js`, replace the stylesheet's `href` from the CDN URL to your local path (say, `/katex/katex.min.css`). ```js title="docusaurus.config.js" module.exports = { diff --git a/website/docs/guides/markdown-features/markdown-features-react.mdx b/website/docs/guides/markdown-features/markdown-features-react.mdx index b8cc840b6a..5c6b8a5a90 100644 --- a/website/docs/guides/markdown-features/markdown-features-react.mdx +++ b/website/docs/guides/markdown-features/markdown-features-react.mdx @@ -471,7 +471,7 @@ This feature is experimental and might be subject to breaking API changes in the 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. +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} diff --git a/website/docs/guides/markdown-features/markdown-features-toc.mdx b/website/docs/guides/markdown-features/markdown-features-toc.mdx index 3917a6ef38..b31e041822 100644 --- a/website/docs/guides/markdown-features/markdown-features-toc.mdx +++ b/website/docs/guides/markdown-features/markdown-features-toc.mdx @@ -49,7 +49,7 @@ A special Markdown syntax lets you set an **explicit heading id**: :::tip -Use the **[write-heading-ids](../../cli.md#docusaurus-write-heading-ids-sitedir)** CLI command to add explicit ids to all your Markdown documents. +Use the **[write-heading-ids](../../cli.md#docusaurus-write-heading-ids-sitedir)** CLI command to add explicit IDs to all your Markdown documents. ::: @@ -61,7 +61,7 @@ Generated heading IDs will be guaranteed to be unique on each page, but if you u ## Inline table of contents {#inline-table-of-contents} -Each Markdown document displays a table of contents on the top-right corner. But it is also possible to display an inline table of contents directly inside a markdown document, thanks to MDX. +Each Markdown document displays a table of contents on the top-right corner. But it is also possible to display an inline table of contents directly inside a Markdown document, thanks to MDX. The `toc` variable is available in any MDX document and contains all the headings of an MDX document. By default, only `h2` and `h3` headings are displayed in the TOC. You can change which heading levels are visible by setting `minHeadingLevel` or `maxHeadingLevel` for individual `TOCInline` components. @@ -121,7 +121,7 @@ The table-of-contents is generated by parsing the Markdown source with a [Remark Markdown headings within hideable areas will still show up in the TOC. For example, headings within [`Tabs`](./markdown-features-tabs.mdx) and [`details`](./markdown-features-intro.mdx#details) will not be excluded. -Non-markdown headings will not show up in the TOC. This can be used to your advantage to tackle the aforementioned issue. +Non-Markdown headings will not show up in the TOC. This can be used to your advantage to tackle the aforementioned issue. ```md
diff --git a/website/docs/i18n/i18n-crowdin.mdx b/website/docs/i18n/i18n-crowdin.mdx index b9de9024b0..b8b1270e9b 100644 --- a/website/docs/i18n/i18n-crowdin.mdx +++ b/website/docs/i18n/i18n-crowdin.mdx @@ -444,7 +444,7 @@ Crowdin has an [In-Context localization](https://support.crowdin.com/in-context- Unfortunately, it does not work yet for technical reasons, but we have good hope it can be solved. -Crowdin replaces markdown strings with technical ids such as `crowdin:id12345`, but it does so too aggressively, including hidden strings, and messes up with front matter, admonitions, JSX... +Crowdin replaces Markdown strings with technical IDs such as `crowdin:id12345`, but it does so too aggressively, including hidden strings, and messes up with front matter, admonitions, JSX... ::: diff --git a/website/docs/i18n/i18n-tutorial.md b/website/docs/i18n/i18n-tutorial.md index 37f48cc026..b7914e87b4 100644 --- a/website/docs/i18n/i18n-tutorial.md +++ b/website/docs/i18n/i18n-tutorial.md @@ -420,18 +420,18 @@ We only copy `.md` and `.mdx` files, as React pages are translated through JSON ::: -:::tip Use explicit heading ids +:::tip Use explicit heading IDs -By default, a Markdown heading `### Hello World` will have a generated id `hello-world`. Other documents can link it with `[link](#hello-world)`. However, after translation, the heading becomes `### Bonjour le Monde`, with id `bonjour-le-monde`. +By default, a Markdown heading `### Hello World` will have a generated ID `hello-world`. Other documents can link it with `[link](#hello-world)`. However, after translation, the 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: +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) ``` -For localized sites, it is recommended to use **[explicit heading ids](../guides/markdown-features/markdown-features-toc.mdx#explicit-ids)**. +For localized sites, it is recommended to use **[explicit heading IDs](../guides/markdown-features/markdown-features-toc.mdx#explicit-ids)**. ::: diff --git a/website/docs/introduction.md b/website/docs/introduction.md index 799b8072c0..894f88e826 100644 --- a/website/docs/introduction.md +++ b/website/docs/introduction.md @@ -108,7 +108,7 @@ Our shared goal—to help your users quickly find what they need and understand - HTML files are statically generated for every possible path. - Page-specific SEO to help your users land on your official docs directly relating their problems at hand. - 📝 **Powered by MDX**: - - Write interactive components via JSX and React embedded in markdown. + - Write interactive components via JSX and React embedded in Markdown. - Share your code in live editors to get your users to love your products on the spot. - 🔍 **Search**: Your full site is searchable. - 💾 **Document Versioning**: Helps you keep documentation in sync with project releases. diff --git a/website/docs/migration/migration-manual.md b/website/docs/migration/migration-manual.md index 7d425480fb..804a3ca52a 100644 --- a/website/docs/migration/migration-manual.md +++ b/website/docs/migration/migration-manual.md @@ -418,8 +418,8 @@ The following fields are all deprecated, you may remove from your configuration - `facebookPixelId` - `fonts` - `highlight` - We now use [Prism](https://prismjs.com/) instead of [highlight.js](https://highlightjs.org/). -- `markdownOptions` - We use MDX in v2 instead of Remarkable. Your markdown options have to be converted to Remark/Rehype plugins. -- `markdownPlugins` - We use MDX in v2 instead of Remarkable. Your markdown plugins have to be converted to Remark/Rehype plugins. +- `markdownOptions` - We use MDX in v2 instead of Remarkable. Your Markdown options have to be converted to Remark/Rehype plugins. +- `markdownPlugins` - We use MDX in v2 instead of Remarkable. Your Markdown plugins have to be converted to Remark/Rehype plugins. - `manifest` - `onPageNav` - This is turned on by default now. - `separateCss` - It can imported in the same manner as `custom.css` mentioned above. @@ -470,7 +470,7 @@ module.exports = { }; ``` -If you want to keep the `.html` extension as the canonical url of a page, docs can declare a `slug: installation.html` front matter. +If you want to keep the `.html` extension as the canonical URL of a page, docs can declare a `slug: installation.html` front matter. ## Components {#components} @@ -577,7 +577,7 @@ This feature is replaced by [inline table of content](../guides/markdown-feature ### Update Markdown syntax to be MDX-compatible {#update-markdown-syntax-to-be-mdx-compatible} -In Docusaurus 2, the markdown syntax has been changed to [MDX](https://mdxjs.com/). Hence there might be some broken syntax in the existing docs which you would have to update. A common example is self-closing tags like `` and `
` which are valid in HTML would have to be explicitly closed now ( `` and `
`). All tags in MDX documents have to be valid JSX. +In Docusaurus 2, the Markdown syntax has been changed to [MDX](https://mdxjs.com/). Hence there might be some broken syntax in the existing docs which you would have to update. A common example is self-closing tags like `` and `
` which are valid in HTML would have to be explicitly closed now ( `` and `
`). All tags in MDX documents have to be valid JSX. Front matter is parsed by [gray-matter](https://github.com/jonschlinkert/gray-matter). If your front matter use special characters like `:`, you now need to quote it: `title: Part 1: my part1 title` → `title: "Part 1: my part1 title"`. diff --git a/website/docs/migration/migration-overview.md b/website/docs/migration/migration-overview.md index 9ad84cdc1a..1c450ea03a 100644 --- a/website/docs/migration/migration-overview.md +++ b/website/docs/migration/migration-overview.md @@ -68,7 +68,7 @@ There are multiple things to migrate to obtain a fully functional Docusaurus 2 w - packages - CLI commands - site configuration -- markdown files +- Markdown files - sidebars file - pages, components and CSS - versioned docs diff --git a/website/docs/migration/migration-translated-sites.md b/website/docs/migration/migration-translated-sites.md index 2db50af546..e8ed65a0d0 100644 --- a/website/docs/migration/migration-translated-sites.md +++ b/website/docs/migration/migration-translated-sites.md @@ -110,21 +110,21 @@ Unfortunately, Crowdin does not have any "Duplicate/clone Project" feature, whic - Download the Crowdin translations locally - Try to run/build your site and see if there are any errors -You will likely have errors on your first-try: the pre-translation might try to translate things that it should not be translated (front matter, admonition, code blocks...), and the translated md files might be invalid for the MDX parser. +You will likely have errors on your first-try: the pre-translation might try to translate things that it should not be translated (front matter, admonition, code blocks...), and the translated MD files might be invalid for the MDX parser. -You will have to fix all the errors until your site builds. You can do that by modifying the translated md files locally, and fix your site for one locale at a time using `docusaurus build --locale fr`. +You will have to fix all the errors until your site builds. You can do that by modifying the translated MD files locally, and fix your site for one locale at a time using `docusaurus build --locale fr`. There is no ultimate guide we could write to fix these errors, but common errors are due to: - Not marking enough strings as "hidden strings" in Crowdin, leading to pre-translation trying to translate these strings. -- Having bad v1 translations, leading to invalid markup in v2: bad html elements inside translations and unclosed tags +- Having bad v1 translations, leading to invalid markup in v2: bad HTML elements inside translations and unclosed tags - Anything rejected by the MDX parser, like using HTML elements instead of JSX elements (use the [MDX playground](https://mdxjs.com/playground/) for debugging) You might want to repeat this pre-translation process, eventually trying the "Perfect" option and limiting pre-translation only some languages/files. :::tip -Use [`mdx-code-block`](../i18n/i18n-crowdin.mdx#mdx-solutions) around problematic markdown elements: Crowdin is less likely mess things up with code blocks. +Use [`mdx-code-block`](../i18n/i18n-crowdin.mdx#mdx-solutions) around problematic Markdown elements: Crowdin is less likely mess things up with code blocks. ::: diff --git a/website/docs/migration/migration-versioned-sites.md b/website/docs/migration/migration-versioned-sites.md index 247b1f4b7b..ff9a412271 100644 --- a/website/docs/migration/migration-versioned-sites.md +++ b/website/docs/migration/migration-versioned-sites.md @@ -14,7 +14,7 @@ The versioned docs should normally be migrated correctly by the [migration CLI]( ## Migrate your `versioned_docs` front matter {#migrate-your-versioned_docs-front-matter} -Unlike v1, The markdown header for each versioned doc is no longer altered by using `version-${version}-${original_id}` as the value for the actual ID field. See scenario below for better explanation. +Unlike v1, The Markdown header for each versioned doc is no longer altered by using `version-${version}-${original_id}` as the value for the actual ID field. See scenario below for better explanation. For example, if you have a `docs/hello.md`. diff --git a/website/docs/static-assets.md b/website/docs/static-assets.md index 08fbacb9e5..eb9d319b3c 100644 --- a/website/docs/static-assets.md +++ b/website/docs/static-assets.md @@ -69,7 +69,7 @@ You write a link like this: [Download this document](/files/note.docx) Docusaurus changes that to: Download this document ``` -:::caution use markdown syntax +:::caution use Markdown syntax Docusaurus will only parse links that are in Markdown syntax. If your asset references are using the JSX tag `` / ``, nothing will be done. diff --git a/website/docs/using-plugins.md b/website/docs/using-plugins.md index 7681f8bfa4..e6f83f13e1 100644 --- a/website/docs/using-plugins.md +++ b/website/docs/using-plugins.md @@ -79,7 +79,7 @@ module.exports = { }; ``` -## Multi-instance plugins and plugin ids {#multi-instance-plugins-and-plugin-ids} +## Multi-instance plugins and plugin IDs {#multi-instance-plugins-and-plugin-ids} All Docusaurus content plugins can support multiple plugin instances. For example, it may be useful to have [multiple docs plugin instances](./guides/docs/docs-multi-instance.mdx) or [multiple blogs](./blog.mdx#multiple-blogs). It is required to assign a unique ID to each plugin instance, and by default, the plugin ID is `default`.