diff --git a/website/docs/cli.md b/website/docs/cli.md index 87324205f0..f696b83877 100644 --- a/website/docs/cli.md +++ b/website/docs/cli.md @@ -62,7 +62,11 @@ Compiles your site for production. ### `docusaurus swizzle` -> ⚠️ We would like to discourage swizzling of components until we've minimally reached a Beta stage. The components APIs have been changing rapidly and are likely to keep changing until we reach Beta. Stick with the default appearance for now if possible to save yourself some potential pain in future. +:::caution + +We would like to discourage swizzling of components until we've minimally reached a Beta stage. The components APIs have been changing rapidly and are likely to keep changing until we reach Beta. Stick with the default appearance for now if possible to save yourself some potential pain in future. + +::: Swizzle any Docusaurus Theme components with your own component with `docusaurus swizzle`. diff --git a/website/docs/configuration.md b/website/docs/configuration.md index 3b9a289a42..9c377a58d2 100644 --- a/website/docs/configuration.md +++ b/website/docs/configuration.md @@ -142,4 +142,8 @@ const Hello = () => { }; ``` -> If you just want to use those fields on the client side, you could create your own JS files and import them as ES6 modules, there is no need to put them in `docusaurus.config.js`. +:::tip + +If you just want to use those fields on the client side, you could create your own JS files and import them as ES6 modules, there is no need to put them in `docusaurus.config.js`. + +::: diff --git a/website/docs/design-principles.md b/website/docs/design-principles.md index 05d13d38b7..327b7dbc8b 100644 --- a/website/docs/design-principles.md +++ b/website/docs/design-principles.md @@ -3,7 +3,11 @@ id: design-principles title: Design Principles --- -> :warning: _This section is a work in progress._ +:::caution + +_This section is a work in progress._ + +::: - **Little to learn** - Docusaurus should be easy to learn and use as the API is quite small. Most things will still be achievable by users, even if it takes them more code and more time to write. Not having abstractions is better than having the wrong abstractions, and we don't want users to have to hack around the wrong abstractions. Mandatory talk - [Minimal API Surface Area](https://www.youtube.com/watch?v=4anAwXYqLG8). - **Intuitive** - Users will not feel overwhelmed when looking at the project directory of a Docusaurus project or adding new features. It should look intuitive and easy to build on top of, using approaches they are familiar with. diff --git a/website/docs/lifecycle-apis.md b/website/docs/lifecycle-apis.md index 59403e3490..c19c11fbca 100644 --- a/website/docs/lifecycle-apis.md +++ b/website/docs/lifecycle-apis.md @@ -3,7 +3,11 @@ id: lifecycle-apis title: Lifecycle APIs --- -> :warning: _This section is a work in progress._ +:::caution + +_This section is a work in progress._ + +::: Lifecycle APIs are shared by Themes and Plugins. diff --git a/website/docs/migrating-from-v1-to-v2.md b/website/docs/migrating-from-v1-to-v2.md index 2ef14b2469..56d80185b8 100644 --- a/website/docs/migrating-from-v1-to-v2.md +++ b/website/docs/migrating-from-v1-to-v2.md @@ -519,9 +519,17 @@ For any questions, you can ask in the [`#docusaurus-1-to-2-migration` Discord ch ## Versioned Site -> :warning: _This section is a work in progress._ +:::caution -> ⚠️ Although we've implemented docs versioning since 2.0.0-alpha.37, we'd like to test it out for v2 users first before we recommend v1 users to migrate to v2. There are some changes in how v2 versioning works compared to v1. In the future, we might create a script to migrate your versioned docs easier. However, if you are adventurous enough to manually migrate, feel free to do so. Be warned though, the manual migration requires lot of work. +_This section is a work in progress._ + +::: + +:::warning + +Although we've implemented docs versioning since 2.0.0-alpha.37, we'd like to test it out for v2 users first before we recommend v1 users to migrate to v2. There are some changes in how v2 versioning works compared to v1. In the future, we might create a script to migrate your versioned docs easier. However, if you are adventurous enough to manually migrate, feel free to do so. Be warned though, the manual migration requires lot of work. + +::: ## Changes from v1 diff --git a/website/docs/styling-layout.md b/website/docs/styling-layout.md index 3e33fab5d9..c24be0a17e 100644 --- a/website/docs/styling-layout.md +++ b/website/docs/styling-layout.md @@ -126,4 +126,8 @@ The class names which will be processed by webpack into a globally unique class ### CSS-in-JS -> :warning: _This section is a work in progress._ [Welcoming PRs](https://github.com/facebook/docusaurus/issues/1640).\_ +:::caution + +_This section is a work in progress._ [Welcoming PRs](https://github.com/facebook/docusaurus/issues/1640).\_ + +::: diff --git a/website/docs/theme-classic.md b/website/docs/theme-classic.md index 4f2e0b362d..c2d088041d 100644 --- a/website/docs/theme-classic.md +++ b/website/docs/theme-classic.md @@ -3,7 +3,11 @@ id: theme-classic title: '@docusaurus/theme-classic' --- -> :warning: _This section is a work in progress._ +:::caution + +_This section is a work in progress._ + +::: ## Common diff --git a/website/docs/using-plugins.md b/website/docs/using-plugins.md index 5b1fb658f2..7bb7d4a4d2 100644 --- a/website/docs/using-plugins.md +++ b/website/docs/using-plugins.md @@ -137,7 +137,11 @@ Provides the [Blog](blog.md) feature and is the default blog plugin for Docusaur npm install --save @docusaurus/plugin-content-blog ``` -> 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. +:::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. + +::: ```js // docusaurus.config.js @@ -174,7 +178,7 @@ module.exports = { * Truncate marker, can be a regex or string. */ truncateMarker: //, - /** + /** * Blog feed * If feedOptions is undefined, no rss feed will be generated */ @@ -201,7 +205,11 @@ Provides the [Docs](markdown-features.mdx) functionality and is the default docs npm install --save @docusaurus/plugin-content-docs ``` -> 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. +:::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. + +::: ```js // docusaurus.config.js @@ -264,7 +272,11 @@ The default pages plugin for Docusaurus. The classic template ships with this pl npm install --save @docusaurus/plugin-content-pages ``` -> 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. +:::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. + +::: ```js // docusaurus.config.js @@ -301,7 +313,11 @@ The default [Google Analytics](https://developers.google.com/analytics/devguides npm install --save @docusaurus/plugin-google-analytics ``` -> If you have installed `@docusaurus/preset-classic`, you don't need to install it as a dependency. +:::tip + +If you have installed `@docusaurus/preset-classic`, you don't need to install it as a dependency. + +::: **Configuration** @@ -329,7 +345,11 @@ The default [Global Site Tag (gtag.js)](https://developers.google.com/analytics/ npm install --save @docusaurus/plugin-google-gtag ``` -> If you have installed `@docusaurus/preset-classic`, you don't need to install it as a dependency. +:::tip + +If you have installed `@docusaurus/preset-classic`, you don't need to install it as a dependency. + +::: **Configuration** @@ -357,7 +377,11 @@ This plugin creates sitemap for your site so that search engine crawlers can cra npm install --save @docusaurus/plugin-sitemap ``` -> 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. +:::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. + +::: ```js // docusaurus.config.js diff --git a/website/docs/using-themes.md b/website/docs/using-themes.md index 6dbe8ac79c..68a362f28b 100644 --- a/website/docs/using-themes.md +++ b/website/docs/using-themes.md @@ -74,7 +74,11 @@ The content plugin remains the same and the only thing you need to change is the ## Swizzling theme components -> ⚠️ We would like to discourage swizzling of components until we've minimally reached a Beta stage. The components APIs have been changing rapidly and are likely to keep changing until we reach Beta. Stick with the default appearance for now if possible to save yourself some potential pain in future. +:::caution + +We would like to discourage swizzling of components until we've minimally reached a Beta stage. The components APIs have been changing rapidly and are likely to keep changing until we reach Beta. Stick with the default appearance for now if possible to save yourself some potential pain in future. + +::: 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`. @@ -104,7 +108,11 @@ The classic theme for Docusaurus. You can refer to [classic theme configuration] npm install --save @docusaurus/theme-classic ``` -> If you have installed `@docusaurus/preset-classic`, you don't need to install it as a dependency. +:::tip + +If you have installed `@docusaurus/preset-classic`, you don't need to install it as a dependency. + +::: ### `@docusaurus/theme-search-algolia` @@ -114,7 +122,11 @@ This theme provides a `@theme/SearchBar` component that integrates with Algolia npm install --save @docusaurus/theme-search-algolia ``` -> If you have installed `@docusaurus/preset-classic`, you don't need to install it as a dependency. +:::tip + +If you have installed `@docusaurus/preset-classic`, you don't need to install it as a dependency. + +::: ### `@docusaurus/theme-live-codeblock` diff --git a/website/docs/versioning.md b/website/docs/versioning.md index 5d1413af9f..270bea9778 100644 --- a/website/docs/versioning.md +++ b/website/docs/versioning.md @@ -6,7 +6,11 @@ You can use the version script to cut a new documentation version based on the l ## :warning: Disclaimer -> Consider it really well before starting to version your documentation. +:::important + +Consider it really well before starting to version your documentation. + +::: Most of the times, you don't need versioning and it will just increase your build time and introduces complexity to your codebase. Versioning is **best suited for website with high-traffic and rapid changes in documentation between version**. If your documentation rarely changes, don't version.