mirror of
https://github.com/facebook/docusaurus.git
synced 2025-08-06 10:20:09 +02:00
More doc improvements (#532)
* Generic doc improvements * Convert to Markdown * Remove whitespace * More typo fixes
This commit is contained in:
Yangshun Tay
Joel Marcey
parent
e19b9ac56e
commit
6500f9bacf
8 changed files with 25 additions and 25 deletions
|
|
@ -74,7 +74,7 @@ Alias: `publish-gh-pages`
|
|||
|
||||
[Builds](api-commands.md#docusaurus-build), then deploys the static website to GitHub Pages. This command is meant to be run during the deployment step in Circle CI, and therefore expects a few environment variables to be defined:
|
||||
|
||||
The following is generally set manually by the user in the CircleCI `config.yml` file.
|
||||
The following environment variables are generally set manually by the user in the CircleCI `config.yml` file.
|
||||
|
||||
- `GIT_USER`: The git user to be associated with the deploy commit.
|
||||
- `USE_SSH`: Whether to use SSH instead of HTTPS for your connection to the GitHub repo.
|
||||
|
|
@ -85,15 +85,15 @@ The following is generally set manually by the user in the CircleCI `config.yml`
|
|||
GIT_USER=docusaurus-bot USE_SSH=true yarn run publish-gh-pages
|
||||
```
|
||||
|
||||
The following are set by the [CircleCI environment](https://circleci.com/docs/1.0/environment-variables/) during the build process.
|
||||
The following environment variables are [set by CircleCI](https://circleci.com/docs/1.0/environment-variables/) during the build process.
|
||||
|
||||
- `CIRCLE_BRANCH`: The git branch associated with the commit that triggered the CI run.
|
||||
- `CI_PULL_REQUEST`: Expected to be truthy if the current CI run was triggered by a commit in a pull request.
|
||||
|
||||
The following should be set by you in `siteConfig.js` as `organizationName` and `projectName`, respectively. If they are not set in your site configuration, they fall back to the [CircleCI environment](https://circleci.com/docs/1.0/environment-variables/).
|
||||
|
||||
- `CIRCLE_PROJECT_USERNAME`: The GitHub username or organization name that hosts the git repo, e.g. "facebook".
|
||||
- `CIRCLE_PROJECT_REPONAME`: The name of the git repo, e.g. "Docusaurus".
|
||||
- `CIRCLE_PROJECT_USERNAME`: The GitHub username or organization name that hosts the Git repo, e.g. "facebook".
|
||||
- `CIRCLE_PROJECT_REPONAME`: The name of the Git repo, e.g. "Docusaurus".
|
||||
|
||||
You can learn more about configuring automatic deployments with CircleCI in the [Publishing guide](getting-started-publishing.md).
|
||||
|
||||
|
|
|
|||
|
|
@ -132,7 +132,7 @@ Now, whenever a new commit lands in `master`, CircleCI will run your suite of te
|
|||
|
||||
> If you would rather use a deploy key instead of a personal access token, you can by starting with the Circle CI [instructions](https://circleci.com/docs/1.0/adding-read-write-deployment-key/) for adding a read/write deploy key.
|
||||
|
||||
#### Tips & Tricks
|
||||
### Tips & Tricks
|
||||
|
||||
When initially deploying to a `gh-pages` branch using Circle CI, you may notice that some jobs triggered by commits to the `gh-pages` branch fail to run successfully due to a lack of tests. You can easily work around this by creating a basic Circle CI config with the following contents:
|
||||
|
||||
|
|
|
|||
|
|
@ -163,14 +163,14 @@ headerLinks: [
|
|||
|
||||
The links in the top navigation bar get `siteNavItemActive` and `siteNavGroupActive` class names to allow you to style the currently active link different from the others. `siteNavItemActive` is applied when there's an exact match between the navigation link and the currently displayed web page.
|
||||
|
||||
> This does not include links of type `href` which are meant for external links only. If you manually set an `href` in your headerLinks to an internal page, document, or blog post, it will not get the `siteNavItemActive` class even if that page is being displayed.
|
||||
> This does not include links of type `href` which are meant for external links only. If you manually set an `href` in your `headerLinks` to an internal page, document, or blog post, it will not get the `siteNavItemActive` class even if that page is being displayed.
|
||||
|
||||
`siteNavGroupActive` will be added to these links:
|
||||
The `siteNavGroupActive` class will be added to these links:
|
||||
|
||||
* `doc` links that belong to the same sidebar as the currently displayed document
|
||||
* The blog link when a blog post, or the blog listing page is being displayed
|
||||
|
||||
These are two separate class names so you can have the active styles applied to either exact matches only or a bit more broadly for docs that belong together. If you don't want to make this distinction you can add both classes to the same css rule.
|
||||
These are two separate class names so you can have the active styles applied to either exact matches only or a bit more broadly for docs that belong together. If you don't want to make this distinction you can add both classes to the same CSS rule.
|
||||
|
||||
## Secondary On-Page Navigation
|
||||
|
||||
|
|
|
|||
|
|
@ -116,9 +116,9 @@ For other pages, Docusaurus will automatically transform all `<translate>` tags
|
|||
|
||||
## Crowdin
|
||||
|
||||
Crowdin is a company that provides translation services. For Open Source projects, Crowdin provides free string translations
|
||||
Crowdin is a company that provides translation services. For Open Source projects, Crowdin provides free string translations.
|
||||
|
||||
Create your translation project on [Crowdin](https://crowdin.com/). You can use [Crowdin's guides](https://support.crowdin.com/translation-process-overview/) to learn more about the translations work flow. _We suggest that you deselect and do not include "English" as a translateable language to prevent the creation of `en-US` localization files as this can lead to confusion._
|
||||
Create your translation project on [Crowdin](https://crowdin.com/). You can use [Crowdin's guides](https://support.crowdin.com/translation-process-overview/) to learn more about the translations work flow. _We suggest that you deselect and do not include "English" as a translatable language to prevent the creation of `en-US` localization files as this can lead to confusion._
|
||||
|
||||
> Ensure in your Crowdin settings, in the Translations section, that "Duplicate Strings" are set to ["Hide - all duplicates will share the same translation"](https://support.crowdin.com/api/create-project/). This setting will ensure that identical strings between versions share a single translation.
|
||||
|
||||
|
|
@ -128,7 +128,7 @@ Your project will need a `crowdin.yaml` file generated. If you ran `yarn example
|
|||
|
||||
The example below can be automatically generated by the Docusaurus cli with the `examples` script. It should be placed in the top level of your project directory to configure how and what files are uploaded/downloaded.
|
||||
|
||||
Below is an example Crowdin configuration for the respective languages: German, Spanish, French, Japanese, Korean, Behasa Indonesia, Portuguese Brazilian, Chinese Simplified, and Chinese Traditional.
|
||||
Below is an example Crowdin configuration for the respective languages: German, Spanish, French, Japanese, Korean, Bahasa Indonesia, Portuguese Brazilian, Chinese Simplified, and Chinese Traditional.
|
||||
|
||||
```yaml
|
||||
project_identifier_env: CROWDIN_DOCUSAURUS_PROJECT_ID
|
||||
|
|
@ -157,9 +157,9 @@ You can go [here](https://support.crowdin.com/configuration-file/) to learn more
|
|||
|
||||
### Setup the Crowdin Scripts
|
||||
|
||||
You will want to manually sync your files to and from crowdin. The sync process will upload any markdown files in `/docs` as well as translatable strings in `website/i18n/en.json`. (These strings can be generated by running `yarn write-translations`.)
|
||||
You will want to manually sync your files to and from Crowdin. The sync process will upload any markdown files in `/docs` as well as translatable strings in `website/i18n/en.json`. (These strings can be generated by running `yarn write-translations`.)
|
||||
|
||||
You can add the following to your `package.json` to manually trigger crowdin.
|
||||
You can add the following to your `package.json` to manually trigger Crowdin.
|
||||
|
||||
```json
|
||||
"scripts": {
|
||||
|
|
@ -179,7 +179,7 @@ CROWDIN_DOCUSAURUS_PROJECT_ID=YOUR_CROWDIN_PROJECT_ID CROWDIN_DOCUSAURUS_API_KEY
|
|||
|
||||
> `YOUR_CROWDIN_PROJECT_ID` is the name of your Crowdin project. e.g., for https://crowdin.com/project/docusaurus/, that variable would be set to `docusaurus`. `YOUR_CROWDIN_API_KEY` is a unique key that is like a password. You can find it in the `API` tab of your Crowdin project's `Settings`.
|
||||
|
||||
> These commands require having an environment variable set with your crowdin project id and api key (`CROWDIN_PROJECT_ID`, `CROWDIN_API_KEY`). You can preface them inline as done above or add them permanently to your `.bashrc` or `.bash_profile`.
|
||||
> These commands require having an environment variable set with your Crowdin project id and api key (`CROWDIN_PROJECT_ID`, `CROWDIN_API_KEY`). You can preface them inline as done above or add them permanently to your `.bashrc` or `.bash_profile`.
|
||||
|
||||
> If you run more than one localized Docusaurus project on your computer, you should change the name of the environment variables to something unique (`CROWDIN_PROJECTNAME_PROJECT_ID`, `CROWDIN_PROJECTNAME_API_KEY`).
|
||||
|
||||
|
|
|
|||
|
|
@ -5,7 +5,7 @@
|
|||
* LICENSE file in the root directory of this source tree.
|
||||
*/
|
||||
|
||||
// translation object contains all translations for each string in 18n/en.json
|
||||
// translation object contains all translations for each string in i18n/en.json
|
||||
|
||||
const CWD = process.cwd();
|
||||
const fs = require('fs');
|
||||
|
|
|
|||
|
|
@ -230,7 +230,7 @@ class Index extends React.Component {
|
|||
contents={[
|
||||
{
|
||||
content:
|
||||
"<i>I’ve helped open source many projects at Facebook and every one needed a website. They all had very similar constraints: the documentation should be written in markdown and be deployed via GitHub pages. None of the existing solutions were great, so I hacked my own and then forked it whenever we needed a new website. I’m so glad that Docusaurus now exists so that I don’t have to spend a week each time spinning up a new one.</i>",
|
||||
"*I've helped open source many projects at Facebook and every one needed a website. They all had very similar constraints: the documentation should be written in markdown and be deployed via GitHub pages. None of the existing solutions were great, so I hacked my own and then forked it whenever we needed a new website. I’m so glad that Docusaurus now exists so that I don’t have to spend a week each time spinning up a new one.*",
|
||||
image: `${siteConfig.baseUrl}img/christopher-chedeau.jpg`,
|
||||
imageAlign: "top",
|
||||
imageAlt: 'Christopher "vjeux" Chedeau',
|
||||
|
|
@ -238,7 +238,7 @@ class Index extends React.Component {
|
|||
},
|
||||
{
|
||||
content:
|
||||
"<i>Open source contributions to the React Native docs have skyrocketed after our move to Docusaurus. The docs are now hosted on a small repo in plain markdown, with none of the clutter that a typical static site generator would require. Thanks Slash!</i>",
|
||||
"*Open source contributions to the React Native docs have skyrocketed after our move to Docusaurus. The docs are now hosted on a small repo in plain markdown, with none of the clutter that a typical static site generator would require. Thanks Slash!*",
|
||||
image: `${siteConfig.baseUrl}img/hector-ramos.png`,
|
||||
imageAlign: "top",
|
||||
imageAlt: "Hector Ramos",
|
||||
|
|
@ -246,7 +246,7 @@ class Index extends React.Component {
|
|||
},
|
||||
{
|
||||
content:
|
||||
"<i>Docusaurus has been a great choice for the ReasonML family of projects. It makes our documentation consistent, i18n-friendly, easy to maintain, and friendly for new contributors.</i>",
|
||||
"*Docusaurus has been a great choice for the ReasonML family of projects. It makes our documentation consistent, i18n-friendly, easy to maintain, and friendly for new contributors.*",
|
||||
image: `${siteConfig.baseUrl}img/ricky-vetter.jpg`,
|
||||
imageAlign: "top",
|
||||
imageAlt: "Ricky Vetter",
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue