From eeebc31ff13327d3ce1b9b1c5ed4e3c967b0b35c Mon Sep 17 00:00:00 2001 From: Yangshun Tay Date: Thu, 2 Apr 2020 14:12:17 +0800 Subject: [PATCH] docs(v2): reorganize markdown features page (#2503) * docs(v2): reorganize markdown features page * docs(v2): reorganize markdown features page --- .../src/theme/DocItem/index.js | 2 +- website/docs/markdown-features.mdx | 746 ++++++++++-------- website/docs/migrating-from-v1-to-v2.md | 20 +- website/docs/versioning.md | 2 +- 4 files changed, 433 insertions(+), 337 deletions(-) diff --git a/packages/docusaurus-theme-classic/src/theme/DocItem/index.js b/packages/docusaurus-theme-classic/src/theme/DocItem/index.js index f25f2758b1..c96619e1cf 100644 --- a/packages/docusaurus-theme-classic/src/theme/DocItem/index.js +++ b/packages/docusaurus-theme-classic/src/theme/DocItem/index.js @@ -109,7 +109,7 @@ function DocItem(props) {
{version && (
- + Version: {version}
diff --git a/website/docs/markdown-features.mdx b/website/docs/markdown-features.mdx index e6b0a7bc5d..a4623cd860 100644 --- a/website/docs/markdown-features.mdx +++ b/website/docs/markdown-features.mdx @@ -4,12 +4,6 @@ title: Markdown Features description: Docusaurus uses GitHub Flavored Markdown (GFM). Find out more about Docusaurus-specific features when writing Markdown. --- - - 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. Docusaurus 2 uses modern tooling to help you compose your interactive documentations 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. @@ -17,7 +11,7 @@ Docusaurus 2 uses modern tooling to help you compose your interactive documentat In this section, we'd like to introduce you to the tools we've picked that we believe will help you build powerful documentation. Let us walk you through with an example. :::important -All the following content assumes you are using `@docusaurus/preset-classic`. +All the following content assumes you are using `@docusaurus/preset-classic` or `@docusaurus/plugin-content-docs`. ::: --- @@ -72,6 +66,7 @@ This will render in the browser as follows: import BrowserWindow from '@site/src/components/BrowserWindow'; +

Hello from Docusaurus

Are you ready to create the documentation site for your open source project? @@ -94,7 +89,7 @@ The headers are well-spaced so that the hierarchy is clear. -### Markdown Headers +## Markdown Headers Documents use the following markdown header fields that are enclosed by a line `---` on either side: @@ -126,7 +121,21 @@ image: https://i.imgur.com/mErPwqL.png --- ``` -### Embedding React components + +## Referencing other documents + +If you want to reference another document file, you should use the name of the document you want to reference. Docusaurus will convert the file path to be the final website path (and remove the `.md`). + +For example, if you are in `doc2.md` and you want to reference `doc1.md` and `folder/doc3.md`: + +```md +I am referencing a [document](doc1.md). Reference to another [document in a folder](folder/doc3.md) +[Relative document](../doc2.md) referencing works as well. +``` + +One benefit of this approach is that the links to external files will still work if you are viewing the file on GitHub. + +## Embedding React components with MDX Docusaurus has built-in support for [MDX](https://mdxjs.com), which allows you to write JSX within your Markdown files and render them as React components. @@ -169,6 +178,7 @@ export const Highlight = ({children, color}) => ( ); + Docusaurus green and Facebook blue are my favorite colors. I can write **Markdown** alongside my _JSX_! @@ -179,199 +189,6 @@ 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. -### Referencing other documents - -If you want to reference another document file, you should use the name of the document you want to reference. Docusaurus will convert the file path to be the final website path (and remove the `.md`). - -For example, if you are in `doc2.md` and you want to reference `doc1.md` and `folder/doc3.md`: - -```md -I am referencing a [document](doc1.md). Reference to another [document in a folder](folder/doc3.md) -[Relative document](../doc2.md) referencing works as well. -``` - -One benefit of this approach is that the links to external files will still work if you are viewing the file on GitHub. - -### 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 specifications of MDX. - - ```jsx - console.log('Every repo must come with a mascot.'); - ``` - - - -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.'); -``` - -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. - -For example, if you prefer to use the `dracula` highlighting theme: - -```js {3} title="docusaurus.config.js" -module.exports = { - themeConfig: { - prism: { - theme: require('prism-react-renderer/themes/dracula'), - }, - }, -}; -``` - -By default, Docusaurus comes with this subset of [commonly used languages](https://github.com/FormidableLabs/prism-react-renderer/blob/master/src/vendor/prism/includeLangs.js). - -To add syntax highlighting for any of the other [Prism supported languages](https://prismjs.com/#supported-languages), -define it in an array of additional languages. - -For example, if you want to add highlighting for the `powershell` language: - -```js {5} title="docusaurus.config.js" -module.exports = { - ... - themeConfig: { - prism: { - additionalLanguages: ['powershell'], - }, - ... - }, -}; -``` - -### Line highlighting - -You can bring emphasis to certain lines of code by specifying line ranges after the language meta string (leave a space after the language). - - ```jsx {3} - function HighlightSomeText(highlight) { - if (highlight) { - return 'This text is highlighted!'; - } - - return 'Nothing highlighted'; - } - ``` - -```jsx {3} -function HighlightSomeText(highlight) { - if (highlight) { - return 'This text is highlighted!'; - } - - return 'Nothing highlighted'; -} -``` - -You can also use comments with `highlight-next-line`, `highlight-start`, and `highlight-end` to select which lines are highlighted. - - ```jsx - function HighlightSomeText(highlight) { - if (highlight) { - // highlight-next-line - return 'This text is highlighted!'; - } - - return 'Nothing highlighted'; - } - - function HighlightMoreText(highlight) { - // highlight-start - if (highlight) { - return 'This range is highlighted!'; - } - // highlight-end - - return 'Nothing highlighted'; - } - ``` - -```jsx -function HighlightSomeText(highlight) { - if (highlight) { - // highlight-next-line - return 'This text is highlighted!'; - } - - return 'Nothing highlighted'; -} -function HighlightMoreText(highlight) { - // highlight-start - if (highlight) { - return 'This range is highlighted!'; - } - // highlight-end - - return 'Nothing highlighted'; -} -``` - -JS style (`/* */` and `//`), JSX style (`{ /* */ }`), Python style (`# `), and HTML style (``) are supported. - -To accomplish this, Docusaurus adds the `docusaurus-highlight-code-line` class to the highlighted lines. You will need to define your own styling for this CSS, possibly in your `src/css/custom.css` with a custom background color which is dependent on your selected syntax highlighting theme. The color given below works for the default highlighting theme (Palenight), so if you are using another theme, you will have to tweak the color accordingly. - -```css title="/src/css/custom.css" -.docusaurus-highlight-code-line { - background-color: rgb(72, 77, 91); - display: block; - margin: 0 calc(-1 * var(--ifm-pre-padding)); - padding: 0 var(--ifm-pre-padding); -} - -/* If you have a different syntax highlighting theme for dark mode. */ -html[data-theme='dark'] .docusaurus-highlight-code-line { - background-color: /* Color which works with dark mode syntax highlighting theme */ -} -``` - -To highlight multiple lines, separate the line numbers by commas or use the range syntax to select a chunk of lines. This feature uses the `parse-number-range` library and you can find [more syntax](https://www.npmjs.com/package/parse-numeric-range) on their project details. - - ```jsx {1,4-6,11} - import React from 'react'; - - function MyComponent(props) { - if (props.isBar) { - return
Bar
; - } - - return
Foo
; - } - - export default MyComponent; - ``` - -```jsx {1,4-6,11} -import React from 'react'; - -function MyComponent(props) { - if (props.isBar) { - return
Bar
; - } - - return
Foo
; -} - -export default MyComponent; -``` - -### Code title - -You can add title to code block by adding `title` key after the language (leave a space between them). - - ```jsx title="src/components/HelloCodeTitle.js" - function HelloCodeTitle(props) { - return

Hello, {props.name}

; - } - ``` - -```jsx title="src/components/HelloCodeTitle.js" -function HelloCodeTitle(props) { - return

Hello, {props.name}

; -} -``` - ### Configuring plugins You can expand the MDX functionalities, using plugins. An MDX plugin is usually a npm package, so you install them like other npm packages using npm. Docusaurus supports both [remark](https://github.com/remarkjs/remark) and [rehype](https://github.com/rehypejs/rehype) plugins that work with MDX. @@ -440,6 +257,405 @@ module.exports = { See more information in the [MDX documentation](https://mdxjs.com/advanced/plugins). +## Tabs + +To show tabbed content within Markdown files, you can fall back on MDX. Docusaurus provides `` components out-of-the-box. + +```jsx +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + + +This is an apple 🍎 +This is an orange 🍊 +This is a banana 🍌 + +``` + +will result in + + +This is an apple 🍎 +This is an orange 🍊 +This is a banana 🍌 + + +### Syncing tab choices + +You may want choices of the same kind of tabs to sync with each other. For example, you might want to provide different instructions for users on Windows vs users on macOS, and you want to changing all OS-specific instructions tabs in one click. To achieve that, you can give all related tabs the same `groupId` prop. Note that doing this will persist the choice in `localStorage` and all `` instances with the same `groupId` will update automatically when the value of one of them is changed. Not that `groupID` are globally-namespaced. + +```jsx {2,14} + +Use Ctrl + C to copy. +Use Command + C to copy. + + + +Use Ctrl + V to paste. +Use Command + V to paste. + +``` + + +Use Ctrl + C to copy. +Use Command + C to copy. + + + +Use Ctrl + V to paste. +Use Command + V to paste. + + +--- + +Tab choices with different `groupId`s will not interfere with each other: + +```jsx {2,14} + +Windows in windows. +macOS is macOS. + + + +Windows is windows. +Unix is unix. + +``` + + +Windows in windows. +macOS is macOS. + + + +Windows is windows. +Unix is unix. + + +## Callouts/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 + The content and title *can* include markdown. + ::: + + :::tip You can specify an optional title + Heads up! Here's a pro-tip. + ::: + + :::info + Useful information. + ::: + + :::caution + Warning! You better pay attention! + ::: + + :::danger + Danger danger, mayday! + ::: + +:::note +The content and title *can* include markdown. +::: + +:::tip +Heads up! Here's a pro-tip. +::: + +:::info +Useful information. +::: + +:::caution +Warning! You better pay attention! +::: + +:::danger +Danger danger, mayday! +::: + +### Specifying title + +You may also specify an optional title + + :::note Your Title + The content and title *can* include markdown. + ::: + +:::note Your Title +The content and title *can* include markdown. +::: + +## Code Blocks + +Code blocks within documentation are super-powered 💪. + +### Code title + +You can add a title to the code block by adding `title` key after the language (leave a space between them). + + ```jsx title="src/components/HelloCodeTitle.js" + function HelloCodeTitle(props) { + return

Hello, {props.name}

; + } + ``` + +```jsx title="src/components/HelloCodeTitle.js" +function HelloCodeTitle(props) { + return

Hello, {props.name}

; +} +``` + +### 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 specifications of MDX. + + ```jsx + console.log('Every repo must come with a mascot.'); + ``` + + + +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.'); +``` + +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. + +For example, if you prefer to use the `dracula` highlighting theme: + +```js {4} title="docusaurus.config.js" +module.exports = { + themeConfig: { + prism: { + theme: require('prism-react-renderer/themes/dracula'), + }, + }, +}; +``` + +By default, Docusaurus comes with this subset of [commonly used languages](https://github.com/FormidableLabs/prism-react-renderer/blob/master/src/vendor/prism/includeLangs.js). + +To add syntax highlighting for any of the other [Prism supported languages](https://prismjs.com/#supported-languages), +define it in an array of additional languages. + +For example, if you want to add highlighting for the `powershell` language: + +```js {5} title="docusaurus.config.js" +module.exports = { + ... + themeConfig: { + prism: { + additionalLanguages: ['powershell'], + }, + ... + }, +}; +``` + +### Line highlighting + +You can bring emphasis to certain lines of code by specifying line ranges after the language meta string (leave a space after the language). + + ```jsx {3} + function HighlightSomeText(highlight) { + if (highlight) { + return 'This text is highlighted!'; + } + + return 'Nothing highlighted'; + } + ``` + +```jsx {3} +function HighlightSomeText(highlight) { + if (highlight) { + return 'This text is highlighted!'; + } + + return 'Nothing highlighted'; +} +``` + +To accomplish this, Docusaurus adds the `docusaurus-highlight-code-line` class to the highlighted lines. You will need to define your own styling for this CSS, possibly in your `src/css/custom.css` with a custom background color which is dependent on your selected syntax highlighting theme. The color given below works for the default highlighting theme (Palenight), so if you are using another theme, you will have to tweak the color accordingly. + +```css title="/src/css/custom.css" +.docusaurus-highlight-code-line { + background-color: rgb(72, 77, 91); + display: block; + margin: 0 calc(-1 * var(--ifm-pre-padding)); + padding: 0 var(--ifm-pre-padding); +} + +/* If you have a different syntax highlighting theme for dark mode. */ +html[data-theme='dark'] .docusaurus-highlight-code-line { + background-color: /* Color which works with dark mode syntax highlighting theme */ +} +``` + +To highlight multiple lines, separate the line numbers by commas or use the range syntax to select a chunk of lines. This feature uses the `parse-number-range` library and you can find [more syntax](https://www.npmjs.com/package/parse-numeric-range) on their project details. + + ```jsx {1,4-6,11} + import React from 'react'; + + function MyComponent(props) { + if (props.isBar) { + return
Bar
; + } + + return
Foo
; + } + + export default MyComponent; + ``` + +```jsx {1,4-6,11} +import React from 'react'; + +function MyComponent(props) { + if (props.isBar) { + return
Bar
; + } + + return
Foo
; +} + +export default MyComponent; +``` + + +You can also use comments with `highlight-next-line`, `highlight-start`, and `highlight-end` to select which lines are highlighted. + + ```jsx + function HighlightSomeText(highlight) { + if (highlight) { + // highlight-next-line + return 'This text is highlighted!'; + } + + return 'Nothing highlighted'; + } + + function HighlightMoreText(highlight) { + // highlight-start + if (highlight) { + return 'This range is highlighted!'; + } + // highlight-end + + return 'Nothing highlighted'; + } + ``` + +```jsx +function HighlightSomeText(highlight) { + if (highlight) { + // highlight-next-line + return 'This text is highlighted!'; + } + + return 'Nothing highlighted'; +} + +function HighlightMoreText(highlight) { + // highlight-start + if (highlight) { + return 'This range is highlighted!'; + } + // highlight-end + + return 'Nothing highlighted'; +} +``` + +Supported commenting syntax: + +|Language|Syntax| +|---|---| +|JavaScript|`/* ... */` and `// ...`| +|JSX|`{/* ... */}`| +|Python|`# ...`| +|HTML|``| + +If there's a syntax that is not currently supported, we are open to adding them! Pull requests welcome. + ### Interactive code editor (Powered by [React Live](https://github.com/FormidableLabs/react-live)) @@ -603,128 +819,4 @@ class HelloWorld { You may want to implement your own `` abstraction if you find the above approach too verbose. We might just implement one in future for convenience. -If you have multiple of these multi-language code tabs, and you want to sync the selection across the tab instances, read on for the [Syncing tab choices section](#syncing-tab-choices). - -### Syncing tab choices - -You may want choices of the same kind of tabs to sync with each other. For example, you might want to provide different instructions for users on Windows vs users on macOS, and you want to changing all OS-specific instructions tabs in one click. To achieve that, you can give all related tabs the same `groupId`. Note that doing this will persist the choice in `localStorage` and all `` instances with the same `groupId` will update automatically when the value of one of them is changed. - - import Tabs from '@theme/Tabs'; - import TabItem from '@theme/TabItem'; - - Use Ctrl + C to copy. - Use Command + C to copy. - - - - Use Ctrl + V to paste. - Use Command + V to paste. - - - - -Use Ctrl + C to copy. -Use Command + C to copy. - - - -Use Ctrl + V to paste. -Use Command + V to paste. - - -Tab choices with different `groupId`s will not interfere with each other: - - import Tabs from '@theme/Tabs'; - import TabItem from '@theme/TabItem'; - - Windows is windows. - Unix is unix. - - - - Windows is not unix. - Unix is not windows. - - - -Windows is windows. -Unix is unix. - - - -Windows is not unix. -Unix is not windows. - - -### Callouts/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: - - ```markdown - :::tip Title - The content and title *can* include markdown. - ::: - ``` - -:::tip Title -The content and title *can* include markdown. -::: +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](#syncing-tab-choices). diff --git a/website/docs/migrating-from-v1-to-v2.md b/website/docs/migrating-from-v1-to-v2.md index c46fb13647..2ae47ea109 100644 --- a/website/docs/migrating-from-v1-to-v2.md +++ b/website/docs/migrating-from-v1-to-v2.md @@ -5,9 +5,13 @@ title: Migrating from v1 to v2 import ColorGenerator from '@site/src/components/ColorGenerator'; -This doc guides you through migrating an existing Docusaurus 1 site to Docusaurus 2. +:::caution -**Note: This migration guide is targeted at Docusaurus users without translation and/or versioning features and assumes the following structure:** +This migration guide is targeted at Docusaurus users without translation and/or versioning features. + +::: + +This doc guides you through migrating an existing Docusaurus 1 site to Docusaurus 2. Your Docusaurus 1 site should have the following structure: ```sh ├── docs @@ -326,7 +330,7 @@ Deprecated. Create a `CNAME` file in your `static` folder instead with your cust Deprecated. Pass it as an option to `@docusaurus/preset-classic` docs instead: -```jsx {8-21} title="docusaurus.config.js" +```jsx {8-20} title="docusaurus.config.js" module.exports = { // ... presets: [ @@ -471,9 +475,9 @@ In Docusaurus 2, the markdown syntax has been changed to [MDX](https://mdxjs.com Refer to the [multi-language support code blocks](markdown-features.mdx#multi-language-support-code-blocks) section. -### Frontmatter +### Front matter -The Docusaurus frontmatter fields for the blog have been changed from camelCase to snake_case to be consistent with the docs. +The Docusaurus front matter fields for the blog have been changed from camelCase to snake_case to be consistent with the docs. The fields `authorFBID` and `authorTwitter` have been deprecated. They are only used for generating the profile image of the author which can be done via the `author_image_url` field. @@ -523,9 +527,9 @@ The versioning feature is a work in progress! Although we've implemented docs ve ## Changes from v1 -Read up https://v2.docusaurus.io/blog/2018/09/11/Towards-Docusaurus-2#versioning first for reasoning on v1's problem +Read up https://v2.docusaurus.io/blog/2018/09/11/Towards-Docusaurus-2#versioning first for problems in v1's approach. -### Migrate your `versioned_docs` frontmatter +### 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. @@ -629,7 +633,7 @@ Example `versioned_sidebars/version-1.0.0-sidebars.json`: ### Populate your `versioned_sidebars` and `versioned_docs` -In v2, we use snapshot approach on documentation versioning. **Every versioned docs does not depends on other version**. It is possible to have `foo.md` in `version-1.0.0` but it doesn't exist in `version-1.2.0`. This is not possible in previous version due to Docusaurus v1 fallback functionality (https://docusaurus.io/docs/en/versioning#fallback-functionality). +In v2, we use snapshot approach for documentation versioning. **Every versioned docs does not depends on other version**. It is possible to have `foo.md` in `version-1.0.0` but it doesn't exist in `version-1.2.0`. This is not possible in previous version due to Docusaurus v1 fallback functionality (https://docusaurus.io/docs/en/versioning#fallback-functionality). For example, if your `versions.json` looks like this in v1 diff --git a/website/docs/versioning.md b/website/docs/versioning.md index 09f1817a5b..ff6d361567 100644 --- a/website/docs/versioning.md +++ b/website/docs/versioning.md @@ -7,7 +7,7 @@ You can use the version script to cut a new documentation version based on the l :::caution -Consider hard before starting to version your documentation. +Consider well before starting to version your documentation. :::