mirror of
https://github.com/facebook/docusaurus.git
synced 2025-08-02 08:19:07 +02:00
fix(theme): make warning a first-class admonition, and deprecate caution admonition (#9308)
This commit is contained in:
Sébastien Lorber
GitHub
parent
58be496da2
commit
f5ae537d3e
339 changed files with 666 additions and 515 deletions
|
|
@ -129,7 +129,7 @@ my-website
|
|||
.
|
||||
```
|
||||
|
||||
:::caution
|
||||
:::warning
|
||||
|
||||
All JavaScript/TypeScript files within the `src/pages/` directory will have corresponding website paths generated for them. If you want to create reusable components into that directory, use the `exclude` option (by default, files prefixed with `_`, test files(`.test.js`), and files in `__tests__` directory are not turned into pages).
|
||||
|
||||
|
|
|
|||
|
|
@ -95,7 +95,7 @@ slug: /
|
|||
This page will be the home page when users visit https://example.com/.
|
||||
```
|
||||
|
||||
:::caution
|
||||
:::warning
|
||||
|
||||
If you added `slug: /` to a doc to make it the homepage, you should delete the existing homepage at `./src/pages/index.js`, or else there will be two files mapping to the same route!
|
||||
|
||||
|
|
|
|||
|
|
@ -29,7 +29,7 @@ If you build a cross-platform mobile SDK, you may have 2 documentations:
|
|||
|
||||
In this case, you can use a distinct docs plugin instance per mobile SDK documentation.
|
||||
|
||||
:::caution
|
||||
:::warning
|
||||
|
||||
If each documentation instance is very large, you should rather create 2 distinct Docusaurus sites.
|
||||
|
||||
|
|
@ -55,7 +55,7 @@ Suppose you have 2 documentations:
|
|||
|
||||
In this case, you should use the same plugin twice in your site configuration.
|
||||
|
||||
:::caution
|
||||
:::warning
|
||||
|
||||
`@docusaurus/preset-classic` already includes a docs plugin instance for you!
|
||||
|
||||
|
|
|
|||
|
|
@ -408,7 +408,7 @@ To make it **easier to adopt**, Docusaurus supports **multiple number prefix pat
|
|||
|
||||
By default, Docusaurus will **remove the number prefix** from the doc id, title, label, and URL paths.
|
||||
|
||||
:::caution
|
||||
:::warning
|
||||
|
||||
**Prefer using [additional metadata](#autogenerated-sidebar-metadata)**.
|
||||
|
||||
|
|
|
|||
|
|
@ -398,7 +398,7 @@ module.exports = {
|
|||
};
|
||||
```
|
||||
|
||||
:::caution
|
||||
:::warning
|
||||
|
||||
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.
|
||||
|
||||
|
|
|
|||
|
|
@ -11,7 +11,7 @@ import Tabs from '@theme/Tabs';
|
|||
import TabItem from '@theme/TabItem';
|
||||
```
|
||||
|
||||
:::caution
|
||||
:::warning
|
||||
|
||||
Think about it before starting to version your documentation - it can become difficult for contributors to help improve it!
|
||||
|
||||
|
|
|
|||
|
|
@ -80,7 +80,7 @@ Because a Prism theme is just a JS object, you can also write your own theme if
|
|||
|
||||
By default, Docusaurus comes with a subset of [commonly used languages](https://github.com/FormidableLabs/prism-react-renderer/blob/master/packages/generate-prism-languages/index.ts#L9-L23).
|
||||
|
||||
:::caution
|
||||
:::warning
|
||||
|
||||
Some popular languages like Java, C#, or PHP are not enabled by default.
|
||||
|
||||
|
|
@ -510,7 +510,7 @@ function Clock(props) {
|
|||
|
||||
### Imports {#imports}
|
||||
|
||||
:::caution react-live and imports
|
||||
:::warning react-live and imports
|
||||
|
||||
It is not possible to import components directly from the react-live code editor, you have to define available imports upfront.
|
||||
|
||||
|
|
@ -642,13 +642,13 @@ If you want to embed HTML markup such as anchor links or bold type, you can use
|
|||
</pre>
|
||||
</BrowserWindow>
|
||||
|
||||
:::caution MDX is whitespace insensitive
|
||||
:::warning MDX is whitespace insensitive
|
||||
|
||||
MDX is in line with JSX behavior: line break characters, even when inside `<pre>`, are turned into spaces. You have to explicitly write the new line character for it to be printed out.
|
||||
|
||||
:::
|
||||
|
||||
:::caution
|
||||
:::warning
|
||||
|
||||
Syntax highlighting only works on plain strings. Docusaurus will not attempt to parse code block content containing JSX children.
|
||||
|
||||
|
|
|
|||
|
|
@ -12,7 +12,7 @@ Documentation is one of your product's interfaces with your users. A well-writte
|
|||
|
||||
Docusaurus 2 uses modern tooling to help you compose your interactive documentation with ease. You may embed React components, or build live coding blocks where your users may play with the code on the spot. Start sharing your eureka moments with the code your audience cannot walk away from. It is perhaps the most effective way of attracting potential users.
|
||||
|
||||
:::important
|
||||
:::info
|
||||
|
||||
This section assumes you are using the official Docusaurus content plugins.
|
||||
|
||||
|
|
|
|||
|
|
@ -57,7 +57,7 @@ To enable KaTeX, you need to install `remark-math` and `rehype-katex` plugins.
|
|||
npm install --save remark-math@3 rehype-katex@5 hast-util-is-element@1.1.0
|
||||
```
|
||||
|
||||
:::caution
|
||||
:::warning
|
||||
|
||||
Use the exact same versions. The latest versions are incompatible with Docusaurus 2.
|
||||
|
||||
|
|
|
|||
|
|
@ -72,7 +72,7 @@ I can write **Markdown** alongside my _JSX_!
|
|||
</BrowserWindow>
|
||||
```
|
||||
|
||||
:::caution MDX is JSX
|
||||
:::warning MDX is JSX
|
||||
|
||||
Since all doc files are parsed using MDX, anything that looks like HTML is actually JSX. Therefore, if you need to inline-style a component, follow JSX flavor and provide style objects.
|
||||
|
||||
|
|
@ -202,7 +202,7 @@ From MDX v2+ onward (Docusaurus v3+), lower-case tag names are always rendered a
|
|||
|
||||
:::
|
||||
|
||||
:::caution
|
||||
:::warning
|
||||
|
||||
This feature is powered by [a wrapper provider](https://mdx-git-renovate-babel-monorepo-mdx.vercel.app/advanced/components#mdxprovider). If you are importing Markdown in a React page, you have to supply this provider yourself through the `MDXContent` theme component.
|
||||
|
||||
|
|
@ -525,7 +525,7 @@ import PartialExample from './_markdown-partial-example.mdx';
|
|||
|
||||
This way, you can reuse content among multiple pages and avoid duplicating materials.
|
||||
|
||||
:::caution
|
||||
:::warning
|
||||
|
||||
Currently, the table of contents does not contain the imported Markdown headings. This is a technical limitation that we are trying to solve ([issue](https://github.com/facebook/docusaurus/issues/3915)).
|
||||
|
||||
|
|
|
|||
|
|
@ -53,7 +53,7 @@ Use the **[`write-heading-ids`](../../cli.mdx#docusaurus-write-heading-ids-sited
|
|||
|
||||
:::
|
||||
|
||||
:::caution Avoid colliding IDs
|
||||
:::warning Avoid colliding IDs
|
||||
|
||||
Generated heading IDs will be guaranteed to be unique on each page, but if you use custom IDs, make sure each one appears exactly once on each page, or there will be two DOM elements with the same ID, which is invalid HTML semantics, and will lead to one heading being unlinkable.
|
||||
|
||||
|
|
@ -174,7 +174,7 @@ The ability to ergonomically insert extra headings or ignore certain headings is
|
|||
|
||||
---
|
||||
|
||||
:::caution
|
||||
:::warning
|
||||
|
||||
Below is just some dummy content to have more table of contents items available on the current page.
|
||||
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue