diff --git a/website/docs/guides/markdown-features/markdown-features-admonitions.mdx b/website/docs/guides/markdown-features/markdown-features-admonitions.mdx index 82e307b653..82f936abfd 100644 --- a/website/docs/guides/markdown-features/markdown-features-admonitions.mdx +++ b/website/docs/guides/markdown-features/markdown-features-admonitions.mdx @@ -6,6 +6,9 @@ slug: /markdown-features/admonitions --- import BrowserWindow from '@site/src/components/BrowserWindow'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import Admonition from '@theme/Admonition'; 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. @@ -141,10 +144,7 @@ import TabItem from '@theme/TabItem'; ::: ``` -```mdx-code-block -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -``` + :::tip Use tabs in admonitions @@ -158,6 +158,8 @@ import TabItem from '@theme/TabItem'; ::: + + ## Usage in JSX Outside of Markdown, you can use the `@theme/Admonition` component to get the same output. @@ -187,12 +189,11 @@ The types that are accepted are the same as above: `note`, `tip`, `danger`, `inf ``` -```mdx-code-block -import Admonition from '@theme/Admonition'; - - -

Use plugins to introduce shorter syntax for the most commonly used JSX elements in your project.

- + +

+ Use plugins to introduce shorter syntax for the most commonly used JSX + elements in your project. +

+ -``` diff --git a/website/docs/guides/markdown-features/markdown-features-assets.mdx b/website/docs/guides/markdown-features/markdown-features-assets.mdx index b0c11acc73..07b0f2c8a8 100644 --- a/website/docs/guides/markdown-features/markdown-features-assets.mdx +++ b/website/docs/guides/markdown-features/markdown-features-assets.mdx @@ -5,6 +5,8 @@ description: Handling assets in Docusaurus Markdown slug: /markdown-features/assets --- +import BrowserWindow from '@site/src/components/BrowserWindow'; + Sometimes you want to link to assets (e.g. docx files, images...) directly from Markdown files, and it is convenient to co-locate the asset next to the Markdown file using it. Let's imagine the following file structure: @@ -47,8 +49,12 @@ import myImageUrl from './assets/docusaurus-asset-example-banner.png'; This results in displaying the image: + + ![My image alternative text](../../assets/docusaurus-asset-example-banner.png) + + :::note If you are using [@docusaurus/plugin-ideal-image](../../api/plugins/plugin-ideal-image.md), you need to use the dedicated image component, as documented. @@ -73,6 +79,8 @@ or [Download this docx using Markdown](./assets/docusaurus-asset-example.docx) ``` + + @@ -81,6 +89,8 @@ or [Download this docx using Markdown](../../assets/docusaurus-asset-example.docx) + + ## Inline SVGs {#inline-svgs} Docusaurus supports inlining SVGs out of the box. @@ -91,10 +101,14 @@ import DocusaurusSvg from './docusaurus.svg'; ; ``` + + import DocusaurusSvg from '@site/static/img/docusaurus.svg'; + + This can be useful if you want to alter the part of the SVG image via CSS. For example, you can change one of the SVG colors based on the current theme. ```jsx @@ -113,7 +127,9 @@ html[data-theme='dark'] .themedDocusaurus [fill='#FFFF50'] { } ``` - + + + ## Themed Images {#themed-images} @@ -135,6 +151,7 @@ import ThemedImage from '@theme/ThemedImage'; import useBaseUrl from '@docusaurus/useBaseUrl'; import ThemedImage from '@theme/ThemedImage'; + + ``` ## Static assets {#static-assets} 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 3361ba7b2b..c362434897 100644 --- a/website/docs/guides/markdown-features/markdown-features-code-blocks.mdx +++ b/website/docs/guides/markdown-features/markdown-features-code-blocks.mdx @@ -5,6 +5,8 @@ description: Handling code blocks in Docusaurus Markdown slug: /markdown-features/code-blocks --- +import BrowserWindow from '@site/src/components/BrowserWindow'; + Code blocks within documentation are super-powered 💪. ## Code title {#code-title} @@ -17,12 +19,16 @@ You can add a title to the code block by adding a `title` key after the language } ``` + + ```jsx title="/src/components/HelloCodeTitle.js" function HelloCodeTitle(props) { return

Hello, {props.name}

; } ``` + + ## Syntax highlighting {#syntax-highlighting} Code blocks are text blocks wrapped around by strings of 3 backticks. You may check out [this reference](https://github.com/mdx-js/specification) for the specifications of MDX. @@ -35,10 +41,14 @@ Code blocks are text blocks wrapped around by strings of 3 backticks. You may ch Use the matching language meta string for your code block, and Docusaurus will pick up syntax highlighting automatically, powered by [Prism React Renderer](https://github.com/FormidableLabs/prism-react-renderer). + + ```jsx console.log('Every repo must come with a mascot.'); ``` + + ### Theming {#theming} By default, the Prism [syntax highlighting theme](https://github.com/FormidableLabs/prism-react-renderer#theming) we use is [Palenight](https://github.com/FormidableLabs/prism-react-renderer/blob/master/src/themes/palenight.js). You can change this to another theme by passing `theme` field in `prism` as `themeConfig` in your docusaurus.config.js. @@ -134,6 +144,9 @@ You can use comments with `highlight-next-line`, `highlight-start`, and `highlig } ``` +````mdx-code-block + + ```jsx function HighlightSomeText(highlight) { if (highlight) { @@ -155,6 +168,9 @@ function HighlightMoreText(highlight) { } ``` + +```` + Supported commenting syntax: | Language | Syntax | @@ -201,6 +217,8 @@ You can also specify highlighted line ranges within the language meta string (le export default MyComponent; ``` + + ```jsx {1,4-6,11} import React from 'react'; @@ -215,6 +233,8 @@ function MyComponent(props) { export default MyComponent; ``` + + :::tip prefer comments Prefer highlighting with comments where you can. By inlining highlight in the code, you don't have to manually count the lines if your code block becomes long. If you add/remove lines, you also don't have to offset your line ranges. @@ -286,6 +306,8 @@ To use the plugin, create a code block with `live` attached to the language meta The code block will be rendered as an interactive editor. Changes to the code will reflect on the result panel live. + + ```jsx live function Clock(props) { const [date, setDate] = useState(new Date()); @@ -309,6 +331,8 @@ function Clock(props) { } ``` + + ### Imports {#imports} :::caution react-live and imports @@ -353,6 +377,8 @@ export default ReactLiveScope; The `ButtonExample` component is now available to use: + + ```jsx live function MyPlayground(props) { return ( @@ -363,6 +389,8 @@ function MyPlayground(props) { } ``` + + ## Using JSX markup in code blocks Code block in Markdown always preserves its content as plain text, meaning you can't do something like: @@ -388,10 +416,12 @@ If you want to embed HTML markup such as anchor links or bold type, you can use ``` -
-  Input: 1 2 3 4{'\n'}
-  Output: "366300745"{'\n'}
-
+ + 
+    Input: 1 2 3 4{'\n'}
+    Output: "366300745"{'\n'}
+
+ :::caution MDX is whitespace insensitive @@ -452,6 +482,7 @@ class HelloWorld { And you will get the following: ````mdx-code-block + @@ -482,6 +513,7 @@ class HelloWorld { + ```` If you have multiple of these multi-language code tabs, and you want to sync the selection across the tab instances, refer to the [Syncing tab choices section](markdown-features-tabs.mdx#syncing-tab-choices). diff --git a/website/docs/guides/markdown-features/markdown-features-inline-toc.mdx b/website/docs/guides/markdown-features/markdown-features-inline-toc.mdx index 55e3e21e0a..c8a8eaf567 100644 --- a/website/docs/guides/markdown-features/markdown-features-inline-toc.mdx +++ b/website/docs/guides/markdown-features/markdown-features-inline-toc.mdx @@ -61,9 +61,7 @@ import TOCInline from '@theme/TOCInline'; ```mdx-code-block - - ``` diff --git a/website/docs/guides/markdown-features/markdown-features-intro.mdx b/website/docs/guides/markdown-features/markdown-features-intro.mdx index c07ab7d2e5..11de81bc13 100644 --- a/website/docs/guides/markdown-features/markdown-features-intro.mdx +++ b/website/docs/guides/markdown-features/markdown-features-intro.mdx @@ -6,9 +6,7 @@ description: Docusaurus uses GitHub Flavored Markdown (GFM). Find out more about slug: /markdown-features --- -```mdx-code-block import BrowserWindow from '@site/src/components/BrowserWindow'; -``` Documentation is one of your product's interfaces with your users. A well-written and well-organized set of docs helps your users understand your product quickly. Our aligned goal here is to help your users find and understand the information they need, as quickly as possible. @@ -58,10 +56,14 @@ Markdown quotes are beautifully styled: > — Docusaurus ``` + + > Easy to maintain open source documentation websites. > > — Docusaurus + + ## Details Markdown can embed HTML elements, and [`details`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/details) HTML elements are beautifully styled: @@ -108,8 +110,6 @@ Markdown can embed HTML elements, and [`details`](https://developer.mozilla.org/ - -
``` :::note 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 af17a3b914..c62321a12c 100644 --- a/website/docs/guides/markdown-features/markdown-features-math-equations.mdx +++ b/website/docs/guides/markdown-features/markdown-features-math-equations.mdx @@ -5,6 +5,8 @@ description: Writing LaTeX Math Equations slug: /markdown-features/math-equations --- +import BrowserWindow from '@site/src/components/BrowserWindow'; + Mathematical equations can be rendered using [KaTeX](https://katex.org). ## Usage @@ -20,9 +22,13 @@ 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 `$$`: @@ -33,10 +39,14 @@ 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. diff --git a/website/docs/guides/markdown-features/markdown-features-plugins.mdx b/website/docs/guides/markdown-features/markdown-features-plugins.mdx index 75d11797f0..3817b58869 100644 --- a/website/docs/guides/markdown-features/markdown-features-plugins.mdx +++ b/website/docs/guides/markdown-features/markdown-features-plugins.mdx @@ -134,14 +134,10 @@ const plugin = (options) => { let number = 1; visit(ast, 'heading', (node) => { if (node.depth === 2 && node.children.length > 0) { - if (node.children[0].type === 'text') { - node.children[0].value = `Section ${number}. ${node.children[0].value}`; - } else { - node.children.unshift({ - type: 'text', - value: `Section ${number}. `, - }); - } + node.children.unshift({ + type: 'text', + value: `Section ${number}. `, + }); number++; } }); diff --git a/website/docs/seo.md b/website/docs/seo.md index 5a92a748dc..111560af28 100644 --- a/website/docs/seo.md +++ b/website/docs/seo.md @@ -7,6 +7,8 @@ keywords: - positioning --- +import BrowserWindow from '@site/src/components/BrowserWindow'; + Docusaurus supports search engine optimization in a variety of ways. ## Global metadata {#global-metadata} @@ -89,8 +91,12 @@ You may also add a title for your image—this doesn't impact SEO much but is di ![Docusaurus banner](./assets/docusaurus-asset-example-banner.png 'Image title') ``` + + ![Docusaurus banner](./assets/docusaurus-asset-example-banner.png 'Image title') + + ## Rich search information {#rich-search-information} Docusaurus blogs support [rich search results](https://search.google.com/test/rich-results) out-of-the-box to get maximum search engine experience. The information is created depending on your meta information in blog/global configuration. In order to get the benefits of the rich search information, fill in the information about the post's publish date, authors, and image, etc. Read more about the meta-information [here](./blog.mdx). diff --git a/website/src/components/BrowserWindow/styles.module.css b/website/src/components/BrowserWindow/styles.module.css index e746e7d889..bf236ce06e 100644 --- a/website/src/components/BrowserWindow/styles.module.css +++ b/website/src/components/BrowserWindow/styles.module.css @@ -35,17 +35,25 @@ width: 10%; } +html[data-theme='light'] { + --ifm-background-color: #fff; +} + .browserWindowAddressBar { flex: 1 0; margin: 0 1rem 0 0.5rem; border-radius: 12.5px; - background-color: #fff; - color: #666; + background-color: var(--ifm-background-color); + color: var(--ifm-color-gray-800); padding: 5px 15px; font: 400 13px Arial; user-select: none; } +html[data-theme='dark'] .browserWindowAddressBar { + color: var(--ifm-color-gray-300); +} + .dot { margin-right: 6px; margin-top: 4px;