Skip to content

Commit

Permalink
docs(v2): various improvements (facebook#4369)
Browse files Browse the repository at this point in the history 
* docs(v2): various improvements

* Update blog.md
  • Loading branch information
@lex111
lex111 authored Mar 9, 2021
1 parent f888404 commit 1c7d423
Show file tree
Hide file tree
Showing 13 changed files with 65 additions and 65 deletions.
4 changes: 2 additions & 2 deletions website/docs/api/docusaurus.config.js.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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`

Expand Down Expand Up @@ -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:

Expand Down
22 changes: 11 additions & 11 deletions website/docs/api/plugins/plugin-content-docs.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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 `<meta name="description" content="..."/>` and `<meta property="og:description" content="..."/>` in `<head>`, 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 `<meta name="description" content="..."/>` and `<meta property="og:description" content="..."/>` in `<head>`, 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:
Expand Down
2 changes: 1 addition & 1 deletion website/docs/api/plugins/plugin-pwa.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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)

Expand Down
2 changes: 1 addition & 1 deletion website/docs/api/themes/theme-configuration.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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 = {
Expand Down
2 changes: 1 addition & 1 deletion website/docs/guides/markdown-features/markdown-features-headings.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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:

Expand Down
20 changes: 10 additions & 10 deletions website/docs/i18n/i18n-crowdin.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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:[email protected])** for help.

Expand Down Expand Up @@ -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/<locale>`).
- Where to download the files after translation (in `i18n/<locale>`)

Create `crowdin.yml` in `website`:

Expand Down Expand Up @@ -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/<MY_PROJECT_NAME>/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/<MY_PROJECT_NAME>/settings#api`
- `preserve_hierarchy`: preserve the folder's hierarchy of your docs on Crowdin UI instead of flattening everything

### Install the Crowdin CLI

Expand Down Expand Up @@ -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

Expand All @@ -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"
{
Expand Down Expand Up @@ -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

Expand All @@ -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
Expand Down
4 changes: 2 additions & 2 deletions website/docs/i18n/i18n-git.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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.

Expand Down
46 changes: 23 additions & 23 deletions website/docs/i18n/i18n-introduction.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -23,36 +23,36 @@ 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

### Overview

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

Expand All @@ -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 `<Translate>` 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**:

Expand All @@ -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

Expand Down Expand Up @@ -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 `<Translate>` api.
The `code.json` file is extracted from React components using the `<Translate>` API.

:::info

Expand Down
6 changes: 3 additions & 3 deletions website/docs/i18n/i18n-tutorial.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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**.

Expand Down Expand Up @@ -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.

:::

Expand Down Expand Up @@ -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):

Expand Down
14 changes: 7 additions & 7 deletions website/docs/installation.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
2 changes: 1 addition & 1 deletion website/docs/introduction.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand Down
Loading

0 comments on commit 1c7d423

Please sign in to comment.