diff --git a/website/docs/api/docusaurus.config.js.md b/website/docs/api/docusaurus.config.js.md index 2dbd9e3585d8..fcdc89450b8f 100644 --- a/website/docs/api/docusaurus.config.js.md +++ b/website/docs/api/docusaurus.config.js.md @@ -108,7 +108,7 @@ module.exports = { ``` - `label`: the label to use for this locale -- `direction`: `ltr` (default) or `rtl` (for [right-to-left languages](https://developer.mozilla.org/en-US/docs/Glossary/rtl) like Araric, Hebrew...) +- `direction`: `ltr` (default) or `rtl` (for [right-to-left languages](https://developer.mozilla.org/en-US/docs/Glossary/rtl) like Araric, Hebrew, etc.) ### `noIndex` @@ -208,7 +208,7 @@ module.exports = { - Type: `Object` -The [theme configuration](./themes/theme-configuration.md) object, to customize your site UI: navbar, footer... +The [theme configuration](./themes/theme-configuration.md) object, to customize your site UI like navbar, footer. Example: diff --git a/website/docs/api/plugins/plugin-content-docs.md b/website/docs/api/plugins/plugin-content-docs.md index 22ebec46a02c..e3f4f2b9ff2d 100644 --- a/website/docs/api/plugins/plugin-content-docs.md +++ b/website/docs/api/plugins/plugin-content-docs.md @@ -150,17 +150,17 @@ 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. +Markdown documents can use the following markdown frontmatter 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 - `slug`: Allows to customize the document url Example: diff --git a/website/docs/api/plugins/plugin-pwa.md b/website/docs/api/plugins/plugin-pwa.md index 9e97df5b0c0b..9b81e4b2ead8 100644 --- a/website/docs/api/plugins/plugin-pwa.md +++ b/website/docs/api/plugins/plugin-pwa.md @@ -166,7 +166,7 @@ interface PwaReloadPopupProps { } ``` -The default theme includes an implementation for the reload popup and uses [Infima Alerts](https://facebookincubator.github.io/infima/docs/components/alert). +The default theme includes an implementation for the reload popup and uses [Infima Alerts](https://infima.dev/docs/components/alert). ![pwa_reload.gif](/img/pwa_reload.gif) diff --git a/website/docs/api/themes/theme-configuration.md b/website/docs/api/themes/theme-configuration.md index f64dc799fb62..c6f88dfca243 100644 --- a/website/docs/api/themes/theme-configuration.md +++ b/website/docs/api/themes/theme-configuration.md @@ -436,7 +436,7 @@ module.exports = { You can set the static Navbar style without disabling the theme switching ability. The selected style will always apply no matter which theme user have selected. -Currently, there are two possible style options: `dark` and `primary` (based on the `--ifm-color-primary` color). You can see the styles preview in the [Infima documentation](https://facebookincubator.github.io/infima/docs/components/navbar/). +Currently, there are two possible style options: `dark` and `primary` (based on the `--ifm-color-primary` color). You can see the styles preview in the [Infima documentation](https://infima.dev/docs/components/navbar/). ```js {5} title="docusaurus.config.js" module.exports = { diff --git a/website/docs/guides/markdown-features/markdown-features-headings.mdx b/website/docs/guides/markdown-features/markdown-features-headings.mdx index abc6fca0f9d5..c1b2e7dd541e 100644 --- a/website/docs/guides/markdown-features/markdown-features-headings.mdx +++ b/website/docs/guides/markdown-features/markdown-features-headings.mdx @@ -21,7 +21,7 @@ Markdown headings appear as a table-of-contents entry. ## Heading ids -Each heading has an id that can be generated, or explicitly specified. +Each heading has an id that can be automatically generated, or explicitly specified. Heading ids allow you to link to a specific document heading in Markdown or JSX: diff --git a/website/docs/i18n/i18n-crowdin.mdx b/website/docs/i18n/i18n-crowdin.mdx index 226e56158d8b..56c596d64781 100644 --- a/website/docs/i18n/i18n-crowdin.mdx +++ b/website/docs/i18n/i18n-crowdin.mdx @@ -9,11 +9,11 @@ The i18n system of Docusaurus is **decoupled from any translation software**. You can integrate Docusaurus with the **tools and SaaS of your choice**, as long as you put the **translation files at the correct location**. -We document the usage of [Crowdin](http://crowdin.com/), as **one** possible **integration example**. +We document the usage of [Crowdin](https://crowdin.com/), as **one** possible **integration example**. :::caution -This is **not an endorsement of Crowdin** as the unique choice to translate a Docusaurus site, but it is used successfully used by Facebook to translate documentation projects such as [Jest](https://jestjs.io/), [Docusaurus](https://docusaurus.io/) and [ReasonML](https://reasonml.github.io/). +This is **not an endorsement of Crowdin** as the unique choice to translate a Docusaurus site, but it is successfully used by Facebook to translate documentation projects such as [Jest](https://jestjs.io/), [Docusaurus](https://docusaurus.io/) and [ReasonML](https://reasonml.github.io/). Refer to the **[Crowdin documentation](https://support.crowdin.com/)** and **[Crowdin support](mailto:support@crowdin.com)** for help. @@ -114,7 +114,7 @@ Your project is created, but it is empty for now. We will upload the files to tr This configuration ([doc](https://support.crowdin.com/configuration-file/)) provides a mapping for the Crowdin CLI to understand: - Where to find the source files to upload (JSON and Markdown) -- Where to download the files after translation (in `i18n/`). +- Where to download the files after translation (in `i18n/`) Create `crowdin.yml` in `website`: @@ -182,8 +182,8 @@ You should **not commit** it, and it may be a good idea to create a dedicated ** #### Other configuration fields -- `project_id`: can be hardcoded, and is found on `https://crowdin.com/project//settings#api`. -- `preserve_hierarchy`: preserve the folder's hierarchy of your docs on Crowdin UI instead of flattening everything. +- `project_id`: can be hardcoded, and is found on `https://crowdin.com/project//settings#api` +- `preserve_hierarchy`: preserve the folder's hierarchy of your docs on Crowdin UI instead of flattening everything ### Install the Crowdin CLI @@ -294,7 +294,7 @@ Start your site on the French locale: npm run start -- --locale fr ``` -Make sure that your website is now translated in French at `http://localhost:3000/fr/` +Make sure that your website is now translated in French at `http://localhost:3000/fr/`. ### Automate with CI @@ -304,7 +304,7 @@ Add `website/i18n` to `.gitignore`. Set the `CROWDIN_PERSONAL_TOKEN` env variable on your CI. -Create a NPM script to `sync` Crowdin (extract sources, upload sources, download translations): +Create a npm script to `sync` Crowdin (extract sources, upload sources, download translations): ```json title="package.json" { @@ -431,9 +431,9 @@ When your sources are refactored, you should use the Crowdin UI to **update your ![Crowdin UI: renaming a file](/img/crowdin/crowdin-files-rename.png) -### Git / VCS integrations +### VCS (Git) integrations -Crowdin has multiple VCS integrations for [GitHub](https://support.crowdin.com/github-integration/), GitLab, BitBucket... +Crowdin has multiple VCS integrations for [GitHub](https://support.crowdin.com/github-integration/), GitLab, Bitbucket. :::warning @@ -445,7 +445,7 @@ It could have been helpful to be able to edit the translations in both Git and C In practice, **it didn't work very reliably** for a few reasons: -- The Crowdin -> Git sync works fine (with a pull-request) +- The Crowdin -> Git sync works fine (with a pull request) - The Git -> Crowdin sync is manual (you have to press a button) - The heuristics used by Crowdin to match existing Markdown translations to existing Markdown sources are not 100% reliable, and you have to verify the result on Crowdin UI after any sync from Git - 2 users concurrently editing on Git and Crowdin can lead to a translation loss diff --git a/website/docs/i18n/i18n-git.md b/website/docs/i18n/i18n-git.md index e28809c921ef..cf731342ca9b 100644 --- a/website/docs/i18n/i18n-git.md +++ b/website/docs/i18n/i18n-git.md @@ -12,7 +12,7 @@ A **possible translation strategy** is to **version control the translation file This strategy has advantages: - **Easy to get started**: just add the `i18n` folder to Git -- **Easy for developers**: Git, GitHub and pull-requests are mainstream developer tools +- **Easy for developers**: Git, GitHub and pull requests are mainstream developer tools - **Free** (or without any additional cost, assuming you already use Git) - **Low friction**: does not require signing-up to an external tool - **Rewarding**: contributors are happy to have a nice contribution history @@ -25,7 +25,7 @@ Using Git also present some shortcomings: :::note -Some **large-scale technical projects** (ReactJS, VueJS, Gatsby, TypeScript, Nuxt...) use Git for translations. +Some **large-scale technical projects** (React, Vue.js, MDN, TypeScript, Nuxt.js, etc.) use Git for translations. Refer to the [Docusaurus i18n RFC](https://github.com/facebook/docusaurus/issues/3317) for our notes and links studying these systems. diff --git a/website/docs/i18n/i18n-introduction.md b/website/docs/i18n/i18n-introduction.md index 229c0172c57d..51e55991bf91 100644 --- a/website/docs/i18n/i18n-introduction.md +++ b/website/docs/i18n/i18n-introduction.md @@ -23,26 +23,26 @@ For more context, you can read the initial [RFC](https://github.com/facebook/doc The goals of the Docusaurus i18n system are: -- **Simple**: just put the translated files in the correct file-system location. -- **Flexible translation workflows**: based on Git (monorepo, forks or submodules), SaaS software, FTP... -- **Flexible deployment options**: single or multiple domains. -- **Modular**: allow plugin author to provide i18n support. -- **Low-overhead runtime**: documentation is mostly static and does not require a heavy JS library or polyfills. -- **Acceptable build-times**: allow building and deploying localized sites independently. -- **Localize assets**: an image of your site might contain text that should be translated. -- **No coupling**: not forced to use any SaaS, yet the integration is possible. -- **Easy to use with [Crowdin](http://crowdin.com/)**: multiple Docusaurus v1 sites use Crowdin, and should be able to migrate to v2. -- **Good SEO defaults**: setting useful SEO headers like [`hreflang`](https://developers.google.com/search/docs/advanced/crawling/localized-versions) for you. -- **RTL support**: locales reading right-to-left (Arabic, Hebrew...) should be easy to use. -- **Default translations**: theme labels are translated for you in [many languages](https://github.com/facebook/docusaurus/tree/master/packages/docusaurus-theme-classic/codeTranslations). +- **Simple**: just put the translated files in the correct file-system location +- **Flexible translation workflows**: based on Git (monorepo, forks or submodules), SaaS software, FTP +- **Flexible deployment options**: single or multiple domains +- **Modular**: allow plugin author to provide i18n support +- **Low-overhead runtime**: documentation is mostly static and does not require a heavy JS library or polyfills +- **Acceptable build-times**: allow building and deploying localized sites independently +- **Localize assets**: an image of your site might contain text that should be translated +- **No coupling**: not forced to use any SaaS, yet the integration is possible +- **Easy to use with [Crowdin](https://crowdin.com/)**: multiple Docusaurus v1 sites use Crowdin, and should be able to migrate to v2 +- **Good SEO defaults**: setting useful SEO headers like [`hreflang`](https://developers.google.com/search/docs/advanced/crawling/localized-versions) for you +- **RTL support**: locales reading right-to-left (Arabic, Hebrew, etc.) should be easy to use +- **Default translations**: classic theme labels are translated for you in [many languages](https://github.com/facebook/docusaurus/tree/master/packages/docusaurus-theme-classic/codeTranslations). ### i18n non-goals We don't provide support for: -- **Automatic locale detection**: opinionated, and best done on the [server](../deployment.mdx). -- **Translation SaaS software**: you are responsible to understand the external tools of your choice. -- **Translation of slugs**: technically complicated, little SEO value. +- **Automatic locale detection**: opinionated, and best done on the [server](../deployment.mdx) +- **Translation SaaS software**: you are responsible to understand the external tools of your choice +- **Translation of slugs**: technically complicated, little SEO value ## Translation workflow @@ -50,9 +50,9 @@ We don't provide support for: Overview of the workflow to create a translated Docusaurus website: -- **Configure**: declare the default locale and alternative locales in `docusaurus.config.js`. -- **Translate**: put the translation files at the correct file-system location. -- **Deploy**: build and deploy your site using a single or multi-domain strategy. +- **Configure**: declare the default locale and alternative locales in `docusaurus.config.js` +- **Translate**: put the translation files at the correct file-system location +- **Deploy**: build and deploy your site using a single or multi-domain strategy ### Translation files @@ -69,8 +69,8 @@ Markdown and MDX documents are translated as a whole, to fully preserve the tran JSON is used to translate: - your React code: using the `` component -- your theme: the navbar, footer... -- your plugins: the docs sidebar category labels... +- your theme: the navbar, footer +- your plugins: the docs sidebar category labels The JSON format used is called **Chrome i18n**: @@ -89,8 +89,8 @@ The JSON format used is called **Chrome i18n**: The choice was made for 2 reasons: -- **Description attribute**: to help translators with additional context. -- **Widely supported**: [Chrome extensions](https://developer.chrome.com/docs/extensions/mv2/i18n-messages/), [Crowdin](https://support.crowdin.com/file-formats/chrome-json/), [Transifex](https://docs.transifex.com/formats/chrome-json), [Phrase](https://help.phrase.com/help/chrome-json-messages), [Applanga](https://www.applanga.com/docs/formats/chrome_i18n_json)... +- **Description attribute**: to help translators with additional context +- **Widely supported**: [Chrome extensions](https://developer.chrome.com/docs/extensions/mv2/i18n-messages/), [Crowdin](https://support.crowdin.com/file-formats/chrome-json/), [Transifex](https://docs.transifex.com/formats/chrome-json), [Phrase](https://help.phrase.com/help/chrome-json-messages), [Applanga](https://www.applanga.com/docs/formats/chrome_i18n_json) ### Translation files location @@ -131,7 +131,7 @@ website/i18n The JSON files are initialized with the [`docusaurus write-translations`](../cli.md#docusaurus-write-translations) CLI command. -The `code.json` file is extracted from React components using the `` api. +The `code.json` file is extracted from React components using the `` API. :::info diff --git a/website/docs/i18n/i18n-tutorial.md b/website/docs/i18n/i18n-tutorial.md index 3d7bf2fdf292..1846682227ff 100644 --- a/website/docs/i18n/i18n-tutorial.md +++ b/website/docs/i18n/i18n-tutorial.md @@ -65,7 +65,7 @@ Start your localized site in dev mode, using the locale of your choice: npm run start -- --locale fr ``` -Your site is accessible at **`http://localhost:3000/fr/`** +Your site is accessible at **`http://localhost:3000/fr/`**. We haven't provided any translation, and the site is **mostly untranslated**. @@ -149,7 +149,7 @@ export default function Home() { Docusaurus provides a **very small and lightweight translation runtime** on purpose, and only supports basic [placeholders interpolation](../docusaurus-core.md#interpolate), using a subset of the [ICU Message Format](https://formatjs.io/docs/core-concepts/icu-syntax/). -Most documentation websites are generally **static** and don't need advanced i18n features (**plurals**, **genders**...). Use a library like [react-intl](https://www.npmjs.com/package/react-intl) for more advanced use-cases. +Most documentation websites are generally **static** and don't need advanced i18n features (**plurals**, **genders**, etc.). Use a library like [react-intl](https://www.npmjs.com/package/react-intl) for more advanced use-cases. ::: @@ -321,7 +321,7 @@ You can also build your site for a single locale: npm run build -- --locale fr ``` -Docusaurus will not add the `/fr/` url prefix. +Docusaurus will not add the `/fr/` URL prefix. On your [static hosting provider](../deployment.mdx): diff --git a/website/docs/installation.md b/website/docs/installation.md index 0c8a6f2e7aec..4d1526a0893f 100644 --- a/website/docs/installation.md +++ b/website/docs/installation.md @@ -82,14 +82,14 @@ my-website ### Project structure rundown -- `/blog/` - Contains the blog Markdown files. You can delete the directory if you do not want/need a blog. More details can be found in the [blog guide](blog.md). -- `/docs/` - Contains the Markdown files for the docs. Customize the order of the docs sidebar in `sidebars.js`. More details can be found in the [docs guide](./guides/docs/docs-markdown-features.mdx). +- `/blog/` - Contains the blog Markdown files. You can delete the directory if you do not want/need a blog. More details can be found in the [blog guide](blog.md) +- `/docs/` - Contains the Markdown files for the docs. Customize the order of the docs sidebar in `sidebars.js`. More details can be found in the [docs guide](./guides/docs/docs-markdown-features.mdx) - `/src/` - Non-documentation files like pages or custom React components. You don't have to strictly put your non-documentation files in here but putting them under a centralized directory makes it easier to specify in case you need to do some sort of linting/processing - - `/src/pages` - Any files within this directory will be converted into a website page. More details can be found in the [pages guide](guides/creating-pages.md). -- `/static/` - Static directory. Any contents inside here will be copied into the root of the final `build` directory. -- `/docusaurus.config.js` - A config file containing the site configuration. This is the equivalent of `siteConfig.js` in Docusaurus 1. -- `/package.json` - A Docusaurus website is a React app. You can install and use any npm packages you like in them. -- `/sidebar.js` - Used by the documentation to specify the order of documents in the sidebar. + - `/src/pages` - Any files within this directory will be converted into a website page. More details can be found in the [pages guide](guides/creating-pages.md) +- `/static/` - Static directory. Any contents inside here will be copied into the root of the final `build` directory +- `/docusaurus.config.js` - A config file containing the site configuration. This is the equivalent of `siteConfig.js` in Docusaurus v1 +- `/package.json` - A Docusaurus website is a React app. You can install and use any npm packages you like in them +- `/sidebar.js` - Used by the documentation to specify the order of documents in the sidebar ## Running the development server diff --git a/website/docs/introduction.md b/website/docs/introduction.md index 02c983b68166..6b25f1153caf 100644 --- a/website/docs/introduction.md +++ b/website/docs/introduction.md @@ -69,7 +69,7 @@ Our shared goal — to help your users find what they need fast, and understand - Share your code in live editors to get your users love your products on the spot - 🔍 **Search** - Your full site is searchable - 💾 **Document Versioning** - Helps you keep documentation in sync with project releases. -- 🌍 **i18n** (_coming soon_) +- 🌍 **i18n** Docusaurus 2 is born to be compassionately accessible to all your users, and lightning fast. diff --git a/website/docs/migration/migration-manual.md b/website/docs/migration/migration-manual.md index 33b12934fb6b..c0aa55efd6d8 100644 --- a/website/docs/migration/migration-manual.md +++ b/website/docs/migration/migration-manual.md @@ -168,7 +168,7 @@ No actions needed, these configuration fields were not modified. #### `colors` -Deprecated. We wrote a custom CSS framework for Docusaurus 2 called [Infima](https://facebookincubator.github.io/infima/) which uses CSS variables for theming. The docs are not quite ready yet and we will update here when it is. To overwrite Infima's CSS variables, create your own CSS file (e.g. `./src/css/custom.css`) and import it globally by passing it as an option to `@docusaurus/preset-classic`: +Deprecated. We wrote a custom CSS framework for Docusaurus 2 called [Infima](https://infima.dev/) which uses CSS variables for theming. The docs are not quite ready yet and we will update here when it is. To overwrite Infima's CSS variables, create your own CSS file (e.g. `./src/css/custom.css`) and import it globally by passing it as an option to `@docusaurus/preset-classic`: ```js {7-9} title="docusaurus.config.js" module.exports = { @@ -505,7 +505,7 @@ In Docusaurus v2, get the `siteConfig` object from `useDocusaurusContext` instea In v2, you have to apply the theme layout around each page. The Layout component takes metadata props. -`CompLibrary` is deprecated in v2, so you have to write your own React component or use Infima styles (Docs will be available soon, sorry about that! In the meanwhile, inspect the V2 website or view https://facebookincubator.github.io/infima/ to see what styles are available). +`CompLibrary` is deprecated in v2, so you have to write your own React component or use Infima styles (Docs will be available soon, sorry about that! In the meanwhile, inspect the V2 website or view https://infima.dev/ to see what styles are available). You can migrate CommonJS to ES6 imports/exports. diff --git a/website/docs/styling-layout.md b/website/docs/styling-layout.md index ced45921c8f8..da907be16218 100644 --- a/website/docs/styling-layout.md +++ b/website/docs/styling-layout.md @@ -32,7 +32,7 @@ Any CSS you write within that file will be available globally and can be referen ## Styling your site with Infima -`@docusaurus/preset-classic` uses [Infima](https://facebookincubator.github.io/infima/) as the underlying styling framework. Infima provides flexible layout and common UI components styling suitable for content-centric websites (blogs, documentation, landing pages). For more details, check out the [Infima website](https://facebookincubator.github.io/infima/). +`@docusaurus/preset-classic` uses [Infima](https://infima.dev/) as the underlying styling framework. Infima provides flexible layout and common UI components styling suitable for content-centric websites (blogs, documentation, landing pages). For more details, check out the [Infima website](https://infima.dev/). When you `init` your Docusaurus 2 project, the website will be generated with basic Infima stylesheets and default styling. You may customize the styling by editing the `/src/css/custom.css` file.