From 9134b1396b1690cbd9c8143c93b544ba2bfc19be Mon Sep 17 00:00:00 2001 From: Alexey Pyltsyn Date: Wed, 7 Oct 2020 13:39:47 +0300 Subject: [PATCH] docs: various fixes and improvements (#3546) --- README.md | 7 +- admin/publish.md | 4 +- .../src/theme/hooks/useAnnouncementBar.ts | 2 +- .../docusaurus-theme-classic/src/types.d.ts | 2 +- website/docs/cli.md | 4 +- website/docs/deployment.md | 6 +- website/docs/docusaurus-core.md | 2 +- website/docs/guides/creating-pages.md | 2 +- .../docs/guides/migrating-from-v1-to-v2.md | 18 ++-- website/docs/introduction.md | 2 +- website/docs/lifecycle-apis.md | 12 +-- website/docs/markdown-features.mdx | 92 ++++++++++--------- website/docs/using-themes.md | 4 +- .../src/pages/examples/markdownPageExample.md | 2 +- .../version-2.0.0-alpha.60/deployment.md | 2 +- .../guides/migrating-from-v1-to-v2.md | 8 +- .../version-2.0.0-alpha.60/introduction.md | 2 +- .../version-2.0.0-alpha.60/lifecycle-apis.md | 12 +-- .../markdown-features.mdx | 16 ++-- .../version-2.0.0-alpha.60/using-themes.md | 4 +- .../version-2.0.0-alpha.61/deployment.md | 2 +- .../guides/creating-pages.md | 2 +- .../guides/migrating-from-v1-to-v2.md | 8 +- .../version-2.0.0-alpha.61/introduction.md | 2 +- .../version-2.0.0-alpha.61/lifecycle-apis.md | 12 +-- .../markdown-features.mdx | 16 ++-- .../version-2.0.0-alpha.61/using-themes.md | 4 +- .../version-2.0.0-alpha.62/cli.md | 2 +- .../version-2.0.0-alpha.62/deployment.md | 2 +- .../guides/creating-pages.md | 2 +- .../guides/migrating-from-v1-to-v2.md | 8 +- .../version-2.0.0-alpha.62/introduction.md | 2 +- .../version-2.0.0-alpha.62/lifecycle-apis.md | 12 +-- .../markdown-features.mdx | 20 ++-- .../version-2.0.0-alpha.62/using-themes.md | 4 +- .../version-2.0.0-alpha.63/cli.md | 2 +- .../version-2.0.0-alpha.63/deployment.md | 2 +- .../guides/creating-pages.md | 2 +- .../guides/migrating-from-v1-to-v2.md | 8 +- .../version-2.0.0-alpha.63/introduction.md | 2 +- .../version-2.0.0-alpha.63/lifecycle-apis.md | 12 +-- .../markdown-features.mdx | 20 ++-- .../version-2.0.0-alpha.63/using-themes.md | 4 +- .../version-2.0.0-alpha.64/cli.md | 2 +- .../version-2.0.0-alpha.64/deployment.md | 2 +- .../guides/creating-pages.md | 2 +- .../guides/migrating-from-v1-to-v2.md | 8 +- .../version-2.0.0-alpha.64/introduction.md | 2 +- .../version-2.0.0-alpha.64/lifecycle-apis.md | 12 +-- .../markdown-features.mdx | 20 ++-- .../version-2.0.0-alpha.64/using-themes.md | 4 +- .../version-2.0.0-alpha.65/cli.md | 4 +- .../version-2.0.0-alpha.65/deployment.md | 2 +- .../guides/creating-pages.md | 2 +- .../guides/migrating-from-v1-to-v2.md | 8 +- .../version-2.0.0-alpha.65/introduction.md | 2 +- .../version-2.0.0-alpha.65/lifecycle-apis.md | 12 +-- .../markdown-features.mdx | 20 ++-- .../version-2.0.0-alpha.65/using-themes.md | 4 +- 59 files changed, 232 insertions(+), 227 deletions(-) diff --git a/README.md b/README.md index 0fe27f2e332a..cd848c549202 100644 --- a/README.md +++ b/README.md @@ -31,9 +31,12 @@ Docusaurus is a project for building, deploying, and maintaining open source pro > Docusaurus is built in a way so that it can [get running](https://docusaurus.io/docs/en/installation/) in as little time as possible. We've built Docusaurus to handle the website build process so you can focus on your project. - **Localizable** - > Docusaurus ships with [localization support](https://docusaurus.io/docs/en/translation/) via CrowdIn. Empower and grow your international community by translating your documentation. + +> Docusaurus ships with [localization support](https://docusaurus.io/docs/en/translation/) via CrowdIn. Empower and grow your international community by translating your documentation. + - **Customizable** - > While Docusaurus ships with the key pages and sections you need to get started, including a home page, a docs section, a [blog](https://docusaurus.io/docs/en/adding-blog/), and additional support pages, it is also [customizable](https://docusaurus.io/docs/en/custom-pages/) as well to ensure you have a site that is [uniquely yours](https://docusaurus.io/docs/en/api-pages/). + +> While Docusaurus ships with the key pages and sections you need to get started, including a home page, a docs section, a [blog](https://docusaurus.io/docs/en/adding-blog/), and additional support pages, it is also [customizable](https://docusaurus.io/docs/en/custom-pages/) as well to ensure you have a site that is [uniquely yours](https://docusaurus.io/docs/en/api-pages/). ## Installation diff --git a/admin/publish.md b/admin/publish.md index 939f41dc4daa..ecbdb0cffa69 100644 --- a/admin/publish.md +++ b/admin/publish.md @@ -157,7 +157,7 @@ npm access ls-packages -It can happen that some accesses not granted, as an admin might add you to the @docusaurus NPM organisation, but you don't have access to the packages that are not in that organisation. +It can happen that some accesses not granted, as an admin might add you to the @docusaurus NPM organization, but you don't have access to the packages that are not in that organization. Please **double-check your permissions on these 3 packages**, otherwise you'll publish a half-release and will have to release a new version. @@ -196,7 +196,7 @@ Now that the release is done, **merge the pull request**. ### 8. Notify people about new release (optional but desirable) -After new release, it is cool to notify our users about this in the Dicsord chat (`docusaurus-users` channel) and write summaries on Twitter using the following templates. +After new release, it is cool to notify our users about this in the Discord chat (`docusaurus-users` channel) and write summaries on Twitter using the following templates. For Discord: diff --git a/packages/docusaurus-theme-classic/src/theme/hooks/useAnnouncementBar.ts b/packages/docusaurus-theme-classic/src/theme/hooks/useAnnouncementBar.ts index 9eba0653d155..2ad3762963fe 100644 --- a/packages/docusaurus-theme-classic/src/theme/hooks/useAnnouncementBar.ts +++ b/packages/docusaurus-theme-classic/src/theme/hooks/useAnnouncementBar.ts @@ -7,7 +7,7 @@ import {useState, useEffect, useCallback} from 'react'; import useThemeConfig from '../../utils/useThemeConfig'; -import type {useAnnouncementBarReturns} from '@theme/hooks/useAnnoucementBar'; +import type {useAnnouncementBarReturns} from '@theme/hooks/useAnnouncementBar'; const STORAGE_DISMISS_KEY = 'docusaurus.announcement.dismiss'; const STORAGE_ID_KEY = 'docusaurus.announcement.id'; diff --git a/packages/docusaurus-theme-classic/src/types.d.ts b/packages/docusaurus-theme-classic/src/types.d.ts index 7d1228562596..3c93176d881a 100644 --- a/packages/docusaurus-theme-classic/src/types.d.ts +++ b/packages/docusaurus-theme-classic/src/types.d.ts @@ -105,7 +105,7 @@ declare module '@theme/Heading' { export default Heading; } -declare module '@theme/hooks/useAnnoucementBar' { +declare module '@theme/hooks/useAnnouncementBar' { export type useAnnouncementBarReturns = { readonly isAnnouncementBarClosed: boolean; readonly closeAnnouncementBar: () => void; diff --git a/website/docs/cli.md b/website/docs/cli.md index 857722146172..3357e8739de2 100644 --- a/website/docs/cli.md +++ b/website/docs/cli.md @@ -97,7 +97,7 @@ Running the command will copy the relevant theme files to your site folder. You | `themeName` | The name of the theme you are using. | | `swizzleComponent` | The name of the component to swizzle. | | `--danger` | Allow swizzling of unstable components | -| `--typescript` | Swizzle typescript components | +| `--typescript` | Swizzle TypeScript components | To unswizzle a component, simply delete the files of the swizzled component. @@ -130,6 +130,6 @@ Serve your built website locally. ### `docusaurus clear` -Clear a Docusaurus site's generated assets, caches, build artifacts... +Clear a Docusaurus site's generated assets, caches, build artifacts. We recommend running this command before reporting bugs, after upgrading versions, or anytime you have issues with your Docusaurus site. diff --git a/website/docs/deployment.md b/website/docs/deployment.md index b6f2a209392f..04902e4f8881 100644 --- a/website/docs/deployment.md +++ b/website/docs/deployment.md @@ -366,13 +366,13 @@ Deploy your app in a matter of seconds using surge with the following steps: npm install --g surge ``` -1. To build the static files of your site for production in the root directory of your project, run: +2. To build the static files of your site for production in the root directory of your project, run: ```bash npm run build ``` -1. Then, run this command inside the root directory of your project: +3. Then, run this command inside the root directory of your project: ```bash surge build/ @@ -380,7 +380,7 @@ surge build/ First-time users of Surge would be prompted to create an account from the command line(happens only once). -Confirm that the site you want to publish is in the `build` directory, a randomly generated subdomain `*.surge.sh subdomain` is always given(which can be edited). +Confirm that the site you want to publish is in the `build` directory, a randomly generated subdomain `*.surge.sh subdomain` is always given (which can be edited). ### Using your domain diff --git a/website/docs/docusaurus-core.md b/website/docs/docusaurus-core.md index d5c78ea5809b..dea573e06bba 100644 --- a/website/docs/docusaurus-core.md +++ b/website/docs/docusaurus-core.md @@ -283,7 +283,7 @@ const MyComponent = () => { ### `useAllPluginInstancesData(pluginName: string)` -Access global data created by a specific plugin. Given a plugin name, it returns the data of all the plugins instances of that name, by pluginId. +Access global data created by a specific plugin. Given a plugin name, it returns the data of all the plugins instances of that name, by plugin id. Usage example: diff --git a/website/docs/guides/creating-pages.md b/website/docs/guides/creating-pages.md index 4c25f493278d..d90215dfc5c0 100644 --- a/website/docs/guides/creating-pages.md +++ b/website/docs/guides/creating-pages.md @@ -70,7 +70,7 @@ In the same way, a page will be created at `http://localhost:3000/helloMarkdown` Markdown pages are less flexible than React pages, because it always uses the theme layout. -Here's an [example markdown page](/examples/markdownPageExample). +Here's an [example Markdown page](/examples/markdownPageExample). :::tip diff --git a/website/docs/guides/migrating-from-v1-to-v2.md b/website/docs/guides/migrating-from-v1-to-v2.md index df42cc67dda1..4ea946264c16 100644 --- a/website/docs/guides/migrating-from-v1-to-v2.md +++ b/website/docs/guides/migrating-from-v1-to-v2.md @@ -361,7 +361,7 @@ Deprecated. Create a `CNAME` file in your `static` folder instead with your cust #### `customDocsPath`, `docsUrl`, `editUrl`, `enableUpdateBy`, `enableUpdateTime` -**BREAKING**: `editUrl` should point to (website) docusaurus project instead of `docs` directory. +**BREAKING**: `editUrl` should point to (website) Docusaurus project instead of `docs` directory. Deprecated. Pass it as an option to `@docusaurus/preset-classic` docs instead: @@ -671,11 +671,11 @@ To use the migration command, follow these steps: 2. To migrate your v1 website, run the migration command with the appropriate filesystem paths: -``` -// migration command format +```bash +# migration command format npx @docusaurus/migrate migrate -// example +# example npx @docusaurus/migrate migrate ./v1-website ./v2-website ``` @@ -689,15 +689,15 @@ yarn start #### Options -You can add option flags to the migration command to automatically migrate markdown content and pages to v2. It is likely that you will still need to make some manual changes to achieve your desired result. +You can add option flags to the migration command to automatically migrate Markdown content and pages to v2. It is likely that you will still need to make some manual changes to achieve your desired result. | Name | Description | | -------- | ------------------------------------------------------ | -| `--mdx` | Add this flag to convert markdown to mdx automatically | +| `--mdx` | Add this flag to convert Markdown to MDX automatically | | `--page` | Add this flag to migrate pages automatically | -``` -// example using options +```bash +# example using options npx docusaurus-migrate migrate --mdx --page ./v1-website ./v2-website ``` @@ -705,7 +705,7 @@ npx docusaurus-migrate migrate --mdx --page ./v1-website ./v2-website The migration of pages and MDX is still a work in progress. -We recommend you to try to run the pages without these options, commit, and then try to run the migration again with the --page and --mdx options. +We recommend you to try to run the pages without these options, commit, and then try to run the migration again with the `--page` and `--mdx` options. This way, you'd be able to easily inspect and fix the diff. diff --git a/website/docs/introduction.md b/website/docs/introduction.md index e374625700b4..2133e2ea2851 100644 --- a/website/docs/introduction.md +++ b/website/docs/introduction.md @@ -7,7 +7,7 @@ slug: / ## Disclaimer -It has been a year since we made the first **alpha release** of Docusaurus 2 and things have been pretty stable since then. Many of Facebook's new open source websites are using Docusaurus 2 now. At this point, we highly encourage you to use Docusaurus 2 over Docusaurus 1 for your new websites. For feedback and questions, chat with us on [**Discord**](https://discordapp.com/invite/docusaurus) :wink: +It has been a year since we made the first **alpha release** of Docusaurus 2 and things have been pretty stable since then. Many of Facebook's new open source websites are using Docusaurus 2 now. At this point, we highly encourage you to use Docusaurus 2 over Docusaurus 1 for your new websites. For feedback and questions, chat with us on [**Discord**](https://discordapp.com/invite/docusaurus) :wink:. **You should use this if:** diff --git a/website/docs/lifecycle-apis.md b/website/docs/lifecycle-apis.md index 3d39ad44f4cc..e73395c32c25 100644 --- a/website/docs/lifecycle-apis.md +++ b/website/docs/lifecycle-apis.md @@ -11,9 +11,9 @@ This section is a work in progress. Lifecycle APIs are shared by Themes and Plugins. -## `validateOptions({options,validate})` +## `validateOptions({options, validate})` -Return validated and normalized options for the plugin. This method is called before the plugin is initialized.You must return options since the returned options will be passed to plugin during intialization. +Return validated and normalized options for the plugin. This method is called before the plugin is initialized.You must return options since the returned options will be passed to plugin during initialization. ### `options` @@ -61,7 +61,7 @@ export function validateOptions({options, validate}) { } ``` -## `validateThemeConfig({themeConfig,validate})` +## `validateThemeConfig({themeConfig, validate})` Return validated and normalized configuration for the theme. @@ -217,7 +217,7 @@ export default function friendsPlugin(context, options) { path: '/friends', component: '@site/src/components/Friends.js', modules: { - // propName -> json file path + // propName -> JSON file path friends: friendsJsonPath, }, exact: true, @@ -231,9 +231,9 @@ export default function friendsPlugin(context, options) { This function permits to create some global plugin data, that can be read from any page, including the pages created by other plugins, and your theme layout. -This data become accessible to your client-side/theme code, through the [`useGlobalData`](./docusaurus-core.md#useglobaldata) and [`usePluginData`](./docusaurus-core.md#useplugindatapluginname-string-pluginid-string) +This data become accessible to your client-side/theme code, through the [`useGlobalData`](./docusaurus-core.md#useglobaldata) and [`usePluginData`](./docusaurus-core.md#useplugindatapluginname-string-pluginid-string). -One this data is created, you can access it with the global data hooks APIs +One this data is created, you can access it with the global data hooks APIs. :::caution diff --git a/website/docs/markdown-features.mdx b/website/docs/markdown-features.mdx index d6ab3324dc7d..8af21c93dd06 100644 --- a/website/docs/markdown-features.mdx +++ b/website/docs/markdown-features.mdx @@ -282,7 +282,7 @@ import TabItem from '@theme/TabItem'; ; ``` -will result in +And you will get the following: - - - ```js - function helloWorld() { - console.log('Hello, world!'); - } - ``` +````jsx +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; - - + + - ```py - def hello_world(): - print 'Hello, world!' - ``` +```js +function helloWorld() { + console.log('Hello, world!'); +} +``` + + + - - +```py +def hello_world(): + print 'Hello, world!' +``` - ```java - class HelloWorld { - public static void main(String args[]) { - System.out.println("Hello, World"); - } - } - ``` + + - - +```java +class HelloWorld { + public static void main(String args[]) { + System.out.println("Hello, World"); + } +} +``` + + + +```` And you will get the following: @@ -935,7 +937,7 @@ If you have multiple of these multi-language code tabs, and you want to sync the ## 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. +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. @@ -955,7 +957,7 @@ Let's imagine the following file structure: You can use images in Markdown, or by requiring them and using a JSX image tag: ```mdx -# My markdown page +# My Markdown page @@ -967,7 +969,7 @@ or The ES imports syntax also works: ```mdx -# My markdown page +# My Markdown page import myImageUrl from './assets/docusaurus-asset-example-banner.png'; @@ -986,29 +988,29 @@ If you are using [@docusaurus/plugin-ideal-image](./using-plugins.md#docusaurusp ### Files -In the same way, you can link to existing assets by requiring them and using the returned url in videos, links etc... +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 +# My Markdown page - Download this PDF !!! + Download this PDF or -[Download this PDF using Markdown !!!](./assets/docusaurus-asset-example-pdf.pdf) +[Download this PDF using Markdown](./assets/docusaurus-asset-example-pdf.pdf) ``` - Download this PDF !!! + Download this PDF -[Download this PDF using Markdown !!!](./assets/docusaurus-asset-example-pdf.pdf) +[Download this PDF using Markdown](./assets/docusaurus-asset-example-pdf.pdf) ### Inline SVGs diff --git a/website/docs/using-themes.md b/website/docs/using-themes.md index 2a17fa08ab95..af2aa521a3a0 100644 --- a/website/docs/using-themes.md +++ b/website/docs/using-themes.md @@ -246,8 +246,8 @@ There are two lifecycle methods that are essential to theme implementation: These lifecycle method are not essential but recommended: -- [`validateThemeConfig({themeConfig,validate})`](lifecycle-apis.md#validatethemeconfigthemeconfigvalidate) -- [`validateOptions({options,validate})`](lifecycle-apis.md#validateoptionsoptionsvalidate) +- [`validateThemeConfig({themeConfig, validate})`](lifecycle-apis.md#validatethemeconfigthemeconfig-validate) +- [`validateOptions({options, validate})`](lifecycle-apis.md#validateoptionsoptions-validate)