diff --git a/website/docs/api/plugins/plugin-content-docs.md b/website/docs/api/plugins/plugin-content-docs.md index c78817d44f..5ebc766620 100644 --- a/website/docs/api/plugins/plugin-content-docs.md +++ b/website/docs/api/plugins/plugin-content-docs.md @@ -4,7 +4,7 @@ title: '📦 plugin-content-docs' slug: '/api/plugins/@docusaurus/plugin-content-docs' --- -Provides the [Docs](markdown-features.mdx) functionality and is the default docs plugin for Docusaurus. +Provides the [Docs](../../guides/docs/docs-introduction.md) functionality and is the default docs plugin for Docusaurus. ## Installation @@ -133,3 +133,36 @@ module.exports = { ], }; ``` + +## Markdown Frontmatter + +Markdown documents can use the following markdown frontmmatter metadata fields, enclosed by a line `---` on either side: + +- `id`: A unique document id. If this field is not present, the document's `id` will default to its file name (without the extension). +- `title`: The title of your document. If this field is not present, the document's `title` will default to its `id`. +- `hide_title`: Whether to hide the title at the top of the doc. By default it is `false`. +- `hide_table_of_contents`: Whether to hide the table of contents to the right. By default it is `false`. +- `sidebar_label`: The text shown in the document sidebar and in the next/previous button for this document. If this field is not present, the document's `sidebar_label` will default to its `title`. +- `custom_edit_url`: The URL for editing this document. If this field is not present, the document's edit URL will fall back to `editUrl` from options fields passed to `docusaurus-plugin-content-docs`. +- `keywords`: Keywords meta tag for the document page, for search engines. +- `description`: The description of your document, which will become the `` and `` in ``, used by search engines. If this field is not present, it will default to the first line of the contents. +- `image`: Cover or thumbnail image that will be used when displaying the link to your post. + +Example: + +```yml +--- +id: doc-markdown +title: Markdown Features +hide_title: false +hide_table_of_contents: false +sidebar_label: Markdown :) +custom_edit_url: https://github.com/facebook/docusaurus/edit/master/docs/api-doc-markdown.md +description: How do I find you when I cannot solve this problem +keywords: + - docs + - docusaurus +image: https://i.imgur.com/mErPwqL.png +--- +My Document Markdown content +``` diff --git a/website/docs/api/themes/theme-configuration.md b/website/docs/api/themes/theme-configuration.md index 369a974d5d..70f6d89996 100644 --- a/website/docs/api/themes/theme-configuration.md +++ b/website/docs/api/themes/theme-configuration.md @@ -399,7 +399,7 @@ module.exports = { :::note -If you use the line highlighting Markdown syntax, you might need to specify a different highlight background color for the dark mode syntax highlighting theme. Refer to the [docs for guidance](markdown-features.mdx#line-highlighting). +If you use the line highlighting Markdown syntax, you might need to specify a different highlight background color for the dark mode syntax highlighting theme. Refer to the [docs for guidance](../../guides/markdown-features/markdown-features-code-blocks.mdx#line-highlighting). ::: diff --git a/website/docs/api/themes/theme-live-codeblock.md b/website/docs/api/themes/theme-live-codeblock.md index 2f24c0ea38..9ee615cec0 100644 --- a/website/docs/api/themes/theme-live-codeblock.md +++ b/website/docs/api/themes/theme-live-codeblock.md @@ -4,7 +4,7 @@ title: '📦 theme-live-codeblock' slug: '/api/themes/@docusaurus/theme-live-codeblock' --- -This theme provides a `@theme/CodeBlock` component that is powered by react-live. You can read more on [interactive code editor](markdown-features.mdx#interactive-code-editor) documentation. +This theme provides a `@theme/CodeBlock` component that is powered by react-live. You can read more on [interactive code editor](../../guides/markdown-features/markdown-features-code-blocks.mdx#interactive-code-editor) documentation. ```bash npm2yarn npm install --save @docusaurus/theme-live-codeblock diff --git a/website/docs/guides/docs/docs-create-doc.mdx b/website/docs/guides/docs/docs-create-doc.mdx new file mode 100644 index 0000000000..b1856efcd4 --- /dev/null +++ b/website/docs/guides/docs/docs-create-doc.mdx @@ -0,0 +1,75 @@ +--- +id: create-doc +title: Create a doc +description: Create a Markdown Document +slug: /create-doc +--- + +Create a markdown file, `greeting.md`, and place it under the `docs` directory. + +```bash +website # root directory of your site +├── docs +│   └── greeting.md +├── src +│   └── pages +├── docusaurus.config.js +├── ... +``` + +At the top of the file, specify `id` and `title` in the front matter, so that Docusaurus will pick them up correctly when generating your site. + +```yml +--- +id: greeting +title: Hello +--- + +## Hello from Docusaurus + +Are you ready to create the documentation site for your open source project? + +### Headers + +will show up on the table of contents on the upper right + +So that your users will know what this page is all about without scrolling down or even without reading too much. + +### Only h2 and h3 will be in the toc + +The headers are well-spaced so that the hierarchy is clear. + +- lists will help you +- present the key points +- that you want your users to remember + - and you may nest them + - multiple times +``` + +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? + +

Headers

+ +will show up on the table of contents on the upper right + +So that your users will know what this page is all about without scrolling down or even without reading too much. + +

Only h2 and h3 will be in the toc

+ +The headers are well-spaced so that the hierarchy is clear. + +- lists will help you +- present the key points +- that you want your users to remember + - and you may nest them + - multiple times + + diff --git a/website/docs/docs.md b/website/docs/guides/docs/docs-introduction.md similarity index 93% rename from website/docs/docs.md rename to website/docs/guides/docs/docs-introduction.md index 6fa8226c55..b56c7a561c 100644 --- a/website/docs/docs.md +++ b/website/docs/guides/docs/docs-introduction.md @@ -1,7 +1,8 @@ --- -id: docs-introduction +id: introduction title: Docs Introduction sidebar_label: Introduction +slug: /docs-introduction --- The docs feature provides users with a way to organize Markdown files in a hierarchical format. @@ -74,6 +75,6 @@ You should delete the existing homepage at `./src/pages/index.js`, or else there :::tip -There's also a "blog-only mode" for those who only want to use the blog feature of Docusaurus 2. You can use the same method detailed above. Follow the setup instructions on [Blog-only mode](blog.md#blog-only-mode). +There's also a "blog-only mode" for those who only want to use the blog feature of Docusaurus 2. You can use the same method detailed above. Follow the setup instructions on [Blog-only mode](../../blog.md#blog-only-mode). ::: diff --git a/website/docs/guides/docs/docs-markdown-features.mdx b/website/docs/guides/docs/docs-markdown-features.mdx new file mode 100644 index 0000000000..0035a655f2 --- /dev/null +++ b/website/docs/guides/docs/docs-markdown-features.mdx @@ -0,0 +1,28 @@ +--- +id: markdown-features +title: Docs Markdown Features +description: Docusaurus Markdown features that are specific to the docs plugin +slug: /docs-markdown-features +--- + +Docs can use any [Markdown feature](../markdown-features/markdown-features-intro.mdx), and have a few additional Docs-specific markdown features. + +## Markdown frontmatter + +Markdown docs have their own [Markdown frontmatter](../../api/plugins/plugin-content-docs.md#markdown-frontmatter) + +## Referencing other documents + +If you want to reference another document file, you could 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. + +Another benefit, for versioned docs, is that one versioned doc will link to another doc of the exact same version. diff --git a/website/docs/sidebar.md b/website/docs/guides/docs/sidebar.md similarity index 98% rename from website/docs/sidebar.md rename to website/docs/guides/docs/sidebar.md index 87f8157926..44e8ae0370 100644 --- a/website/docs/sidebar.md +++ b/website/docs/guides/docs/sidebar.md @@ -1,5 +1,5 @@ --- -id: docs-sidebar +id: sidebar title: Sidebar slug: /sidebar --- @@ -105,7 +105,7 @@ By default, the doc page the user is reading will display the sidebar that it is For example, with the above example, when displaying the `doc2` page, the sidebar will contain the items of `secondSidebar` only. Another example of multiple sidebars is the `API` and `Docs` sections on the Docusaurus website. -For more information about sidebars and how they relate to doc pages, see [Navbar doc link](./api/themes/theme-configuration.md#navbar-doc-link). +For more information about sidebars and how they relate to doc pages, see [Navbar doc link](../../api/themes/theme-configuration.md#navbar-doc-link). ## Understanding sidebar items diff --git a/website/docs/versioning.md b/website/docs/guides/docs/versioning.md similarity index 96% rename from website/docs/versioning.md rename to website/docs/guides/docs/versioning.md index 4c67a3298d..d61e383c57 100644 --- a/website/docs/versioning.md +++ b/website/docs/guides/docs/versioning.md @@ -1,6 +1,7 @@ --- id: versioning title: Versioning +slug: /versioning --- You can use the version script to create a new documentation version based on the latest content in the `docs` directory. That specific set of documentation will then be preserved and accessible even as the documentation in the `docs` directory changes moving forward. @@ -61,7 +62,7 @@ npm run docusaurus docs:version 1.1.0 When tagging a new version, the document versioning mechanism will: - Copy the full `docs/` folder contents into a new `versioned_docs/version-/` folder. -- Create a versioned sidebars file based from your current [sidebar](docs.md#sidebar) configuration (if it exists) - saved as `versioned_sidebars/version--sidebars.json`. +- Create a versioned sidebars file based from your current [sidebar](docs-introduction.md#sidebar) configuration (if it exists) - saved as `versioned_sidebars/version--sidebars.json`. - Append the new version number to `versions.json`. ## Docs @@ -165,7 +166,7 @@ Docusaurus defaults work great for the first usecase. The docs in `./docs` will be served at `/docs/1.0.0` instead of `/docs/next`, and `1.0.0` will become the default version we link to in the navbar dropdown, and you will only need to maintain a single `./docs` folder. -See [docs plugin configuration](./api/plugins/plugin-content-docs.md) for more details. +See [docs plugin configuration](../../api/plugins/plugin-content-docs.md) for more details. ### Version your documentation only when needed diff --git a/website/docs/guides/markdown-features/markdown-features-admonitions.mdx b/website/docs/guides/markdown-features/markdown-features-admonitions.mdx new file mode 100644 index 0000000000..c692e1dda2 --- /dev/null +++ b/website/docs/guides/markdown-features/markdown-features-admonitions.mdx @@ -0,0 +1,86 @@ +--- +id: admonitions +title: Admonitions +description: Handling admonitions/callouts in Docusaurus Markdown +slug: /markdown-features/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 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! + +::: + +## 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. + +::: diff --git a/website/docs/guides/markdown-features/markdown-features-assets.mdx b/website/docs/guides/markdown-features/markdown-features-assets.mdx new file mode 100644 index 0000000000..142f4fe3a0 --- /dev/null +++ b/website/docs/guides/markdown-features/markdown-features-assets.mdx @@ -0,0 +1,145 @@ +--- +id: assets +title: Assets +description: Handling assets in Docusaurus Markdown +slug: /markdown-features/assets +--- + +Sometimes you want to link to static assets directly from Markdown files, and it is convenient to co-locate the asset next to the markdown file using it. + +We have setup Webpack loaders to handle most common file types, so that when you import a file, you get its url, and the asset is automatically copied to the output folder. + +Let's imagine the following file structure: + +``` +# Your doc +/website/docs/myFeature.mdx + +# Some assets you want to use +/website/docs/assets/docusaurus-asset-example-banner.png +/website/docs/assets/docusaurus-asset-example-pdf.pdf +``` + +## Images + +You can use images in Markdown, or by requiring them and using a JSX image tag: + +```mdx +# My Markdown page + +Example banner + +or + +![Example banner](./assets/docusaurus-asset-example-banner.png) +``` + +The ES imports syntax also works: + +```mdx +# My Markdown page + +import myImageUrl from './assets/docusaurus-asset-example-banner.png'; + +My image alternative text +``` + +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](../../using-plugins.md#docusaurusplugin-ideal-image), you need to use the dedicated image component, as documented. + +::: + +## Files + +In the same way, you can link to existing assets by requiring them and using the returned url in videos, links etc. + +```mdx +# My Markdown page + + + Download this PDF + + +or + +[Download this PDF using Markdown](./assets/docusaurus-asset-example-pdf.pdf) +``` + + + Download this PDF + + +[Download this PDF using Markdown](../../assets/docusaurus-asset-example-pdf.pdf) + +## Inline SVGs + +Docusaurus supports inlining SVGs out of the box. + +```jsx +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 +import DocusaurusSvg from './docusaurus.svg'; + +; +``` + +```css +html[data-theme='light'] .themedDocusaurus [fill='#FFFF50'] { + fill: greenyellow; +} + +html[data-theme='dark'] .themedDocusaurus [fill='#FFFF50'] { + fill: seagreen; +} +``` + + + +## Themed Images + +Docusaurus supports themed images: the `ThemedImage` component (included in the classic/bootstrap themes) allows you to switch the image source based on the current theme. + +```jsx {5-8} +import ThemedImage from '@theme/ThemedImage'; + +; +``` + +import useBaseUrl from '@docusaurus/useBaseUrl'; +import ThemedImage from '@theme/ThemedImage'; + + diff --git a/website/docs/guides/markdown-features/markdown-features-code-blocks.mdx b/website/docs/guides/markdown-features/markdown-features-code-blocks.mdx new file mode 100644 index 0000000000..3510a73c45 --- /dev/null +++ b/website/docs/guides/markdown-features/markdown-features-code-blocks.mdx @@ -0,0 +1,439 @@ +--- +id: code-blocks +title: Code blocks +description: Handling code blocks in Docusaurus Markdown +slug: /markdown-features/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'], + }, + // ... + }, +}; +``` + +If you want to add highlighting for languages not yet supported by Prism, you can swizzle `prism-include-languages`: + +```bash npm2yarn +npm run swizzle @docusaurus/theme-classic prism-include-languages +``` + +It will produce `prism-include-languages.js` in your `src/theme` folder. You can add highlighting support for custom languages by editing `prism-include-languages.js`: + +```js {8} title="src/theme/prism-include-languages.js" +const prismIncludeLanguages = (Prism) => { + // ... + + additionalLanguages.forEach((lang) => { + require(`prismjs/components/prism-${lang}`); // eslint-disable-line + }); + + require('/path/to/your/prism-language-definition'); + + // ... +}; +``` + +You can refer to [Prism's official language definitions](https://github.com/PrismJS/prism/tree/master/components) when you are writing your own language definitions. + +## 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)) + +You can create an interactive coding editor with the `@docusaurus/theme-live-codeblock` plugin. + +First, add the plugin to your package. + +```bash npm2yarn +npm install --save @docusaurus/theme-live-codeblock +``` + +You will also need to add the plugin to your `docusaurus.config.js`. + +```js {3} +module.exports = { + // ... + themes: ['@docusaurus/theme-live-codeblock'], + // ... +}; +``` + +To use the plugin, create a code block with `live` attached to the language meta string. + + ```jsx live + function Clock(props) { + const [date, setDate] = useState(new Date()); + useEffect(() => { + var timerID = setInterval(() => tick(), 1000); + + return function cleanup() { + clearInterval(timerID); + }; + }); + + function tick() { + setDate(new Date()); + } + + return ( +
+

It is {date.toLocaleTimeString()}.

+
+ ); + } + ``` + +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()); + useEffect(() => { + var timerID = setInterval(() => tick(), 1000); + + return function cleanup() { + clearInterval(timerID); + }; + }); + + function tick() { + setDate(new Date()); + } + + return ( +
+

It is {date.toLocaleTimeString()}.

+
+ ); +} +``` + +:::caution 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. + +::: + +By default, all React imports are available. If you need more imports available, swizzle the react-live scope: + +```bash npm2yarn +npm run swizzle @docusaurus/theme-live-codeblock ReactLiveScope +``` + +```jsx {3-15,21} title="src/theme/ReactLiveScope/index.js" +import React from 'react'; + +const ButtonExample = (props) => ( +