3pp-mirror/docusaurus
1
0
Fork 0
mirror of https://github.com/facebook/docusaurus.git synced 2025-05-10 15:47:23 +02:00
Code Issues Projects Releases Packages Wiki Activity

Update documentation

Browse source
This commit is contained in:
Frank Li 2017-08-15 10:57:49 -07:00
parent 9c0a69c3e0
commit bd3d55a80b
3 changed files with 68 additions and 32 deletions
Download patch file Download diff file Expand all files Collapse all files

57
docs/site-config.md
View file

@ -27,22 +27,40 @@ The `siteConfig` object contains the bulk of the configuration settings for your
`projectName` - Project name.
`headerLinksInternal` - Header links for targets on this site. `'LANGUAGE'` will be replaced by whatever language the page is for, for example, `'en'`.
`headerLinksExternal` - Header links for targets outside this site.
`headerLinks` - Links that will be used in the header navigation bar. The `label` field of each object will be the link text and will also be translated for each language.
Example Usage:
```js
headerLinks: [
// Links to document with id doc1 for current language/version
{ doc: "doc1", label: "Getting Started" },
// Link to page found at pages/en/help.js or if that does not exist, pages/help.js, for current language
{ page: "help", label: "Help" },
// Links to href destination
{ href: "https://github.com/", label: "GitHub" },
// Links to blog generated by Docusaurus (${baseUrl}blog)
{ blog: true, label: "Blog" },
// Determines search bar position among links
{ search: true },
// Determines language drop down position among links
{ languages: true }
],
```
`headerIcon` - url for icon used in header navigation bar.
`favicon` - url for site favicon.
`colors` - Simple color configurations for the site. `primaryColor` is the color used the header navigation bar and sidebars. `secondaryColor` is the color seen in the second row of the header navigation bar when the site window is narrow (including on mobile). `prismColor` is the color used in the background of syntax highlighting for code in documentation. It is recommended to be the same color as `primaryColor` in `rgba` form with an alpha value of `0.03`.
`colors` - Color configurations for the site.
- `primaryColor` is the color used the header navigation bar and sidebars.
- `secondaryColor` is the color seen in the second row of the header navigation bar when the site window is narrow (including on mobile).
- `prismColor` is the color used in the background of syntax highlighting for code in documentation. It is recommended to be the same color as `primaryColor` in `rgba` form with an alpha value of `0.03`. Other fields can be added
- Custom color configurations can also be added. For example, if user styles are added with colors specified as `$myColor`, then adding a `myColor` field to `colors` will allow you to easily configure this color.
### Optional Fields
`editUrl` - url for editing docs, usage example: `editUrl + 'en/doc1.md'`. If this field is omitted, there will be no "Edit this Doc" button for each document.
`externalLinkTarget` - Target attribute for header external links. If this field is omitted, the default target of `"_self"` will be used.
`users` - The `users` array mentioned earlier.
`disableHeaderTitle` - An option to disable showing the title in the header next to the header icon. Exclude this field to keep the header as normal, otherwise set to `true`.
@ -59,6 +77,8 @@ The `siteConfig` object contains the bulk of the configuration settings for your
`gaTrackingId` - Google Analytics tracking ID to track page views.
Users can also add their own custom fields if they wish to provide some data across different files.
## Example siteConfig.js with all fields
```
@ -79,25 +99,13 @@ const siteConfig = {
baseUrl: "/test-site/",
// baseUrl: "/",
projectName: "docusaurus",
headerLinksInternal: [
{
section: "docs",
href: "/test-site/docs/LANGUAGE/doc1.html",
text: "Docs"
},
{ section: "api", href: "/test-site/docs/LANGUAGE/doc4.html", text: "API" },
{ section: "help", href: "/test-site/LANGUAGE/help.html", text: "Help" },
{ section: "blog", href: "/test-site/blog", text: "Blog" }
headerLinks: [
{ doc: "doc1", label: "Docs" },
{ page: "help", label: "Help" },
{ search: true },
{ blog: true }
],
// headerLinksInternal: [],
headerLinksExternal: [
{
section: "github",
href: "https://github.com/deltice/test-site",
text: "GitHub"
}
],
// headerLinksExternal: [],
// headerLinks: [],
headerIcon: "img/docusaurus.svg",
favicon: "img/favicon.png",
colors: {
@ -109,7 +117,6 @@ const siteConfig = {
editUrl: "https://github.com/deltice/test-site/edit/master/docs/",
externalLinkTarget: "_blank",
users,
disableHeaderTitle: true,
disableTitleTagline: true,

15
docs/translation.md
View file

@ -61,11 +61,12 @@ Add the following script to your package.json file:
Running the script will generate a `website/i18n/en.json` file containing all the strings that will be translated from English into other languages.
The script will include text from the following places:
- `title` and `sidebar_label` strings in document markdown headers
- category names in `sidebars.json`
- tagline in `siteConfig.js`
- header link `label` strings in `siteConfig.js`
- strings wrapped in the `<translate>` tag in any `.js` files inside `pages`
- `title` and `sidebar_label` strings in document markdown headers
- category names in `sidebars.json`
- tagline in `siteConfig.js`
- header link `label` strings in `siteConfig.js`
- strings wrapped in the `<translate>` tag in any `.js` files inside `pages`
## How Strings Get Translated
@ -123,7 +124,9 @@ The `crowdin` command uses the `crowdin.yaml` file generated with the `examples`
Note that in the `crowdin.yaml` file, `CROWDIN_PROJECT_ID` and `CROWDIN_API_KEY` are environment variables set-up in Circle for your Crowdin project. They can be found in your Crowdin project settings.
Now, Circle will help you automatically get translations prior to building your website. If you wish to use crowdin on your machine locally, you can install the [Crowdin CLI tool](https://support.crowdin.com/cli-tool/) and run the same commands found in the `circle.yaml` file, making sure you actually set the `project_identifier` and `api_key` in the `crowdin.yaml` file. The provided `crowdin.yaml` file will copy translated documents into `website/translated_docs/`, and translated versions of the `i18n/en.json` strings file will into `i18n/${language}.json`.
Now, Circle will help you automatically get translations prior to building your website. The provided `crowdin.yaml` file will copy translated documents into `website/translated_docs/`, and translated versions of the `i18n/en.json` strings file will into `i18n/${language}.json`.
If you wish to use Crowdin on your machine locally, you can install the [Crowdin CLI tool](https://support.crowdin.com/cli-tool/) and run the same commands found in the `circle.yaml` file. The only difference is that you must set `project_identifier` and `api_key` values in the `crowdin.yaml` file since you will not have Circle environment variables set up.
## Translations and Versioning

28
docs/versioning.md
View file

@ -38,7 +38,15 @@ Users can create version numbers in whatever format they wish, and a new version
## Storing Files for Each Version
Versioned documents are placed into `website/versioned_docs/version-${version}`, where `${version}` is the version number you supplied the `version` script. The front matter for each versioned doc is altered by appending `"version-${version}-"` to the id and by adding an `original_id` field. Versioned sidebars are copied into `website/versioned_sidebars` and are named as `version-${version}-sidebar.json`. A `website/versions.json` file is created the first time you cut a version and is used by Docusaurus to detect what versions exist. Each time a new version is added, it gets added to the `versions.json` file. If you wish to change the documentation for a past version, you can access the files for that respective version.
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 appending `"version-${version}-"` to the id and by adding an `original_id` field.
Versioned sidebars are copied into `website/versioned_sidebars` and are named as `version-${version}-sidebar.json`.
A `website/versions.json` file is created the first time you cut a version and is used by Docusaurus to detect what versions exist. Each time a new version is added, it gets added to the `versions.json` file.
If you wish to change the documentation for a past version, you can access the files for that respective version.
## Fallback Functionality
@ -46,6 +54,24 @@ Only files in the `docs` folder and sidebar files that differ from those of the
For example, a document with the original id `doc1` exists for the latest version, `1.0.0`, and has the same content as the document with the id `doc1` in the `docs` folder. When a new version `2.0.0` is created, the file for `doc1` will not be copied into `versioned_docs/version-2.0.0/`. There will still be a page for `docs/2.0.0/doc1.html`, but it will use the file from version `1.0.0`.
## Renaming Existing Versions
To rename an existing version number to something else, first make sure the following script is in your `package.json` file:
```json
...
"scripts": {
"rename-version": "docusaurus-rename-version"
},
...
```
Run the script with command line arguments of first, the current version name, then second, the new version name. e.g.,
```bash
npm run rename-version 1.0.0 1.0.1
```
## Versioning and Translations
If you wish to use versioning and translations features, the `crowdin.yaml` file should be set up to upload and download versioned documents to and from Crowdin for translation. Translated, versioned files will go into the folder `translated_docs/${language}/version-${version}/`. For more information, check out the [translations guide](translation.md).