mirror of
https://github.com/facebook/docusaurus.git
synced 2025-08-03 16:59:06 +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).
|
||||
|
||||
|
|
|
|||
|
|
@ -82,7 +82,7 @@ If you haven't done so already, you can [setup CircleCI](https://circleci.com/si
|
|||
1. Go to https://github.com/settings/tokens for the `GIT_USER` and generate a new [personal access token](https://help.github.com/articles/creating-a-personal-access-token-for-the-command-line/), granting it full control of private repositories through the `repo` access scope. Store this token in a safe place, making sure to not share it with anyone. This token can be used to authenticate GitHub actions on your behalf in place of your GitHub password.
|
||||
1. Open your Circle CI dashboard, and navigate to the Settings page for your repository, then select "Environment variables". The URL looks like https://circleci.com/gh/ORG/REPO/edit#env-vars, where "ORG/REPO" should be replaced with your own GitHub org/repo.
|
||||
1. Create a new environment variable named `GITHUB_TOKEN`, using your newly generated access token as the value.
|
||||
1. Create a `.circleci` folder and create a `config.yml` under that folder.
|
||||
1. Create a `.circleci` folder and create a `config.yml` under that folder.
|
||||
1. Copy the text below into `.circleci/config.yml`.
|
||||
|
||||
```yml
|
||||
|
|
@ -104,7 +104,7 @@ jobs:
|
|||
|
||||
steps:
|
||||
- checkout
|
||||
- run:
|
||||
- run:
|
||||
name: Deploying to GitHub Pages
|
||||
command: |
|
||||
git config --global user.email "<GITHUB_USERNAME>@users.noreply.github.com"
|
||||
|
|
@ -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
|
||||
|
||||
|
|
|
|||
|
|
@ -29,9 +29,9 @@ const siteConfig = {
|
|||
...
|
||||
algolia: {
|
||||
...
|
||||
algoliaOptions: {
|
||||
facetFilters: [ "tags:VERSION" ],
|
||||
hitsPerPage: 5
|
||||
algoliaOptions: {
|
||||
facetFilters: [ "tags:VERSION" ],
|
||||
hitsPerPage: 5
|
||||
}
|
||||
},
|
||||
}
|
||||
|
|
|
|||
|
|
@ -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`).
|
||||
|
||||
|
|
|
|||
|
|
@ -53,7 +53,7 @@ You can create version numbers in whatever format you wish, and a new version ca
|
|||
|
||||
Versioned documents are placed into `website/versioned_docs/version-${version}`, where `${version}` is the version number you supplied the `version` script.
|
||||
|
||||
The markdown header for each versioned doc is altered by renaming the id frontmatter field to `original_id`, then using `"version-${version}-${original_id}"` as the value for the actual `id` field.
|
||||
The markdown header for each versioned doc is altered by renaming the id front matter field to `original_id`, then using `"version-${version}-${original_id}"` as the value for the actual `id` field.
|
||||
|
||||
Versioned sidebars are copied into `website/versioned_sidebars` and are named as `version-${version}-sidebars.json`.
|
||||
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue