mirror of
https://github.com/facebook/docusaurus.git
synced 2025-05-12 00:27:21 +02:00
docs: fix typo for docs folder (#1484)
* docs: fix typo for `docs` folder * docs: request change for #1484 * Update api-doc-markdown.md
This commit is contained in:
Hongarc
Yangshun Tay
parent
96445eee32
commit
f18e07343c
15 changed files with 64 additions and 64 deletions
|
|
@ -170,4 +170,4 @@ See the [Versioning guide](guides-versioning.md) to learn more.
|
|||
|
||||
Alias: `write-translations`
|
||||
|
||||
Writes the English for any strings that need to be translated into an `website/i18n/en.json` file. The script will go through every file in `website/pages/en` and through the `siteConfig.js` file and other config files to fetch English strings that will then be translated on Crowdin. See the [Translation guide](guides-translation.md) to learn more.
|
||||
Writes the English for any strings that need to be translated into a `website/i18n/en.json` file. The script will go through every file in `website/pages/en` and through the `siteConfig.js` file and other config files to fetch English strings that will then be translated on Crowdin. See the [Translation guide](guides-translation.md) to learn more.
|
||||
|
|
|
|||
|
|
@ -109,7 +109,7 @@ Example:
|
|||
|
||||
You can make an auto-generated list of links, which can be useful as a table of contents for API docs.
|
||||
|
||||
In your markdown file, insert a line with the text `<AUTOGENERATED_TABLE_OF_CONTENTS>`. Write your documentation using `h3` headers for each function inside a code block. These will be found by Docusaurus and a list of links to these sections will inserted at the text `<AUTOGENERATED_TABLE_OF_CONTENTS>`.
|
||||
In your markdown file, insert a line with the text `<AUTOGENERATED_TABLE_OF_CONTENTS>`. Write your documentation using `h3` headers for each function inside a code block. These will be found by Docusaurus and a list of links to these sections will be inserted at the text `<AUTOGENERATED_TABLE_OF_CONTENTS>`.
|
||||
|
||||
Example:
|
||||
|
||||
|
|
@ -250,4 +250,4 @@ class Example extends React.Component {
|
|||
|
||||
### Adding Copy Code Buttons
|
||||
|
||||
Docusaurus allows for adding buttons to copy code within fenced code blocks. Please follow the instructions [here](https://gist.github.com/yangshun/55db997ed0f8f4e6527571fc3bee4675) to add "Copy" buttons to your code blocks.
|
||||
Docusaurus allows for adding buttons to copy the code within fenced code blocks. Please follow the instructions [here](https://gist.github.com/yangshun/55db997ed0f8f4e6527571fc3bee4675) to add "Copy" buttons to your code blocks.
|
||||
|
|
|
|||
|
|
@ -26,7 +26,7 @@ module.exports = MyPage;
|
|||
|
||||
## URLs for Pages
|
||||
|
||||
Any `.js` files in `website/pages` will be rendered to static HTML using the path of the file after `pages`. Files in `website/pages/en` will also get copied out into `pages` and will OVERRIDE any files of the same name in `pages`. For example, the page for the `website/pages/en/help.js` file will be found at the URL `${baseUrl}en/help.js` as well as the URL `${baseUrl}help.js`, where `${baseUrl}` is the `baseUrl` field set in your [siteConfig.js file](api-site-config.md).
|
||||
Any `.js` files in `website/pages` will be rendered to static HTML using the path of the file after `pages`. Files in `website/pages/en` will also get copied out into `pages` and will OVERRIDE any files of the same name in `pages`. For example, the page for the `website/pages/en/help.js` file will be found at the URL `${baseUrl}en/help.js` as well as the URL `${baseUrl}help.js`, where `${baseUrl}` is the `baseUrl` fieldset in your [siteConfig.js file](api-site-config.md).
|
||||
|
||||
## Titles for Pages
|
||||
|
||||
|
|
|
|||
|
|
@ -3,13 +3,13 @@ id: site-config
|
|||
title: siteConfig.js
|
||||
---
|
||||
|
||||
A large part of site configuration is done by editing the `siteConfig.js` file.
|
||||
A large part of the site configuration is done by editing the `siteConfig.js` file.
|
||||
|
||||
## User Showcase
|
||||
|
||||
The `users` array is used to store objects for each project/user that you want to show on your site. Currently this field is used by example the `pages/en/index.js` and `pages/en/users.js` files provided. Each user object should have `caption`, `image`, `infoLink`, and `pinned` fields. The `caption` is the text showed when someone hovers over the `image` of that user, and the `infoLink` is where clicking the image will bring someone. The `pinned` field determines whether or not it shows up on the `index` page.
|
||||
The `users` array is used to store objects for each project/user that you want to show on your site. Currently, this field is used by example the `pages/en/index.js` and `pages/en/users.js` files provided. Each user object should have `caption`, `image`, `infoLink`, and `pinned` fields. The `caption` is the text showed when someone hovers over the `image` of that user, and the `infoLink` is where clicking the image will bring someone. The `pinned` field determines whether or not it shows up on the `index` page.
|
||||
|
||||
Currently this `users` array is used only by the `index.js` and `users.js` example files. If you do not wish to have a users page or show users on the `index` page, you may remove this section.
|
||||
Currently, this `users` array is used only by the `index.js` and `users.js` example files. If you do not wish to have a users page or show users on the `index` page, you may remove this section.
|
||||
|
||||
## siteConfig Fields
|
||||
|
||||
|
|
@ -19,7 +19,7 @@ The `siteConfig` object contains the bulk of the configuration settings for your
|
|||
|
||||
#### `baseUrl` [string]
|
||||
|
||||
baseUrl for your site. This can also be considered the path after the host. For example, `/metro/` is the baseUrl of https://facebook.github.io/metro/. For urls that have no path, the baseUrl should be set to `/`. This field is related to the [`url` field](#url-string).
|
||||
baseUrl for your site. This can also be considered the path after the host. For example, `/metro/` is the baseUrl of https://facebook.github.io/metro/. For URLs that have no path, the baseUrl should be set to `/`. This field is related to the [`url` field](#url-string).
|
||||
|
||||
#### `colors` [object]
|
||||
|
||||
|
|
@ -31,7 +31,7 @@ Color configurations for the site.
|
|||
|
||||
#### `copyright` [string]
|
||||
|
||||
The copyright string at footer of site and within feed
|
||||
The copyright string at the footer of the site and within the feed
|
||||
|
||||
#### `favicon` [string]
|
||||
|
||||
|
|
@ -39,7 +39,7 @@ URL for site favicon.
|
|||
|
||||
#### `headerIcon` [string]
|
||||
|
||||
URL for icon used in header navigation bar.
|
||||
URL for icon used in the header navigation bar.
|
||||
|
||||
#### `headerLinks` [array]
|
||||
|
||||
|
|
@ -74,7 +74,7 @@ Project name. This must match your GitHub repository project name (case-sensitiv
|
|||
|
||||
#### `tagline` [string]
|
||||
|
||||
Tagline for your website.
|
||||
The tagline for your website.
|
||||
|
||||
#### `title` [string]
|
||||
|
||||
|
|
@ -82,7 +82,7 @@ Title for your website.
|
|||
|
||||
#### `url` [string]
|
||||
|
||||
URL for your website. This can also be considered the top-level hostname. For example, `https://facebook.github.io` is the url of https://facebook.github.io/metro/, and `https://docusaurus.io` is the url for https://docusaurus.io. This field is related to the [`baseUrl` field](#baseurl-string).
|
||||
URL for your website. This can also be considered the top-level hostname. For example, `https://facebook.github.io` is the URL of https://facebook.github.io/metro/, and `https://docusaurus.io` is the URL for https://docusaurus.io. This field is related to the [`baseUrl` field](#baseurl-string).
|
||||
|
||||
### Optional Fields
|
||||
|
||||
|
|
@ -90,7 +90,7 @@ URL for your website. This can also be considered the top-level hostname. For ex
|
|||
|
||||
Information for Algolia search integration. If this field is excluded, the search bar will not appear in the header. You must specify two values for this field, and one (`appId`) is optional.
|
||||
|
||||
- `apiKey` - the Algolia provided API key for your search.
|
||||
- `apiKey` - the Algolia provided an API key for your search.
|
||||
- `indexName` - the Algolia provided index name for your search (usually this is the project name)
|
||||
- `appId` - Algolia provides a default scraper for your docs. If you provide your own, you will probably get this id from them.
|
||||
|
||||
|
|
@ -104,7 +104,7 @@ Control the title of the blog sidebar. See the [adding a blog docs](guides-blog.
|
|||
|
||||
#### `cleanUrl` [string]
|
||||
|
||||
If `true`, allow URLs with no `html` extension. For example, a request to URL https://docusaurus.io/docs/installation will returns the same result as https://docusaurus.io/docs/installation.html.
|
||||
If `true`, allow URLs with no `HTML` extension. For example, a request to URL https://docusaurus.io/docs/installation will return the same result as https://docusaurus.io/docs/installation.html.
|
||||
|
||||
#### `cname` [string]
|
||||
|
||||
|
|
@ -128,7 +128,7 @@ The default version for the site to be shown. If this is not set, the latest ver
|
|||
|
||||
#### `docsUrl` [string]
|
||||
|
||||
The base url for all docs file. Set this field to `''` to remove the `docs` prefix of the documentation URL.
|
||||
The base URL for all docs file. Set this field to `''` to remove the `docs` prefix of the documentation URL.
|
||||
If unset, it is defaulted to `docs`.
|
||||
|
||||
#### `disableHeaderTitle` [boolean]
|
||||
|
|
@ -208,7 +208,7 @@ Set this to `true` if you want to use [global site tags (gtag.js)](https://devel
|
|||
|
||||
#### `githubHost` [string]
|
||||
|
||||
Hostname of your server. Useful if you are using GitHub Enterprise.
|
||||
The hostname of your server. Useful if you are using GitHub Enterprise.
|
||||
|
||||
#### `highlight`
|
||||
|
||||
|
|
@ -271,11 +271,11 @@ If you want a visible navigation option for representing topics on the current p
|
|||
|
||||
#### `scripts` [array]
|
||||
|
||||
Array of JavaScript sources to load. The values can be either strings or plain objects of attribute-value maps. Refer to the example below. The script tag will be inserted in the HTML head.
|
||||
An array of JavaScript sources to load. The values can be either strings or plain objects of attribute-value maps. Refer to the example below. The script tag will be inserted in the HTML head.
|
||||
|
||||
#### `separateCSS` [array]
|
||||
|
||||
Directories inside which any `css` files will not be processed and concatenated to Docusaurus' styles. This is to support static `html` pages that may be separate from Docusaurus with completely separate styles.
|
||||
Directories inside which any `CSS` files will not be processed and concatenated to Docusaurus' styles. This is to support static `HTML` pages that may be separate from Docusaurus with completely separate styles.
|
||||
|
||||
#### `scrollToTop` [boolean]
|
||||
|
||||
|
|
@ -287,7 +287,7 @@ Optional options configuration for the scroll to top button. You do not need to
|
|||
|
||||
#### `stylesheets` [array]
|
||||
|
||||
Array of CSS sources to load. The values can be either strings or plain objects of attribute-value maps. The link tag will be inserted in the HTML head.
|
||||
An array of CSS sources to load. The values can be either strings or plain objects of attribute-value maps. The link tag will be inserted in the HTML head.
|
||||
|
||||
#### `translationRecruitingLink` [string]
|
||||
|
||||
|
|
@ -315,11 +315,11 @@ The `users` array mentioned earlier.
|
|||
|
||||
#### `usePrism` [array]
|
||||
|
||||
Array of languages to use Prism syntax highlighter. Refer to [Using Prism as additional syntax highlighter](api-doc-markdown.md#using-prism-as-additional-syntax-highlighter). Set it to `true` to use Prism on all languages.
|
||||
An array of languages to use Prism syntax highlighter. Refer to [Using Prism as additional syntax highlighter](api-doc-markdown.md#using-prism-as-additional-syntax-highlighter). Set it to `true` to use Prism on all languages.
|
||||
|
||||
#### `wrapPagesHTML` [boolean]
|
||||
|
||||
Boolean flag to indicate whether `html` files in `/pages` should be wrapped with Docusaurus site styles, header and footer. This feature is experimental and relies on the files being `html` fragments instead of complete pages. It inserts the contents of your `html` file with no extra processing. Defaults to `false`.
|
||||
Boolean flag to indicate whether `HTML` files in `/pages` should be wrapped with Docusaurus site styles, header and footer. This feature is experimental and relies on the files being `HTML` fragments instead of complete pages. It inserts the contents of your `HTML` file with no extra processing. Defaults to `false`.
|
||||
|
||||
Users can also add their own custom fields if they wish to provide some data across different files.
|
||||
|
||||
|
|
|
|||
|
|
@ -47,11 +47,11 @@ root-directory
|
|||
as the footer for the site generated by Docusaurus and should be customized by the user.
|
||||
* **Configuration file**: The `website/siteConfig.js` file is the main
|
||||
configuration file used by Docusaurus.
|
||||
* **Sidebars**: The `sidebars.json` file contains the structure and ordering
|
||||
* **Sidebars**: The `sidebars.json` file contains the structure and order
|
||||
of the documentation files.
|
||||
|
||||
## Preparation Notes
|
||||
|
||||
You will need to keep the `website/siteConfig.js` and `website/core/Footer.js` files, but may edit them as you wish. The value of the `customDocsPath` key in `website/siteConfig.js` can be modified if you wish to use a different directory name or path. The `website` directory can also be renamed to anything you want it to be.
|
||||
You will need to keep the `website/siteConfig.js` and `website/core/Footer.js` files but may edit them as you wish. The value of the `customDocsPath` key in `website/siteConfig.js` can be modified if you wish to use a different directory name or path. The `website` directory can also be renamed to anything you want it to be.
|
||||
|
||||
However, you should keep the `website/pages` and `website/static` directories. You may change the content inside them as you wish. At the bare minimum you should have an `en/index.js` or `en/index.html` file inside `website/pages` and an image to use as your header icon inside `website/static`.
|
||||
However, you should keep the `website/pages` and `website/static` directories. You may change the content inside them as you wish. At the bare minimum, you should have an `en/index.js` or `en/index.html` file inside `website/pages` and an image to use as your header icon inside `website/static`.
|
||||
|
|
|
|||
|
|
@ -19,9 +19,9 @@ This will generate a `build` directory inside the `website` directory containing
|
|||
|
||||
At this point, you can grab all of the files inside the `website/build` directory and copy them over to your favorite web server's `html` directory.
|
||||
|
||||
> For example, both Apache and nginx serve content from `/var/www/html` by default. That said, choosing a web server or provider is outside the scope of Docusaurus.
|
||||
> For example, both Apache and Nginx serve content from `/var/www/html` by default. That said, choosing a web server or provider is outside the scope of Docusaurus.
|
||||
|
||||
> When serving the site from your own web server, ensure the web server is serving the asset files with the proper HTTP headers. CSS files should be served with the `content-type` header of `text/css`. In the case of nginx, this would mean setting `include /etc/nginx/mime.types;` in your `nginx.conf` file. See [this issue](https://github.com/facebook/Docusaurus/issues/602) for more info.
|
||||
> When serving the site from your own web server, ensure the web server is serving the asset files with the proper HTTP headers. CSS files should be served with the `content-type` header of `text/css`. In the case of Nginx, this would mean setting `include /etc/nginx/mime.types;` in your `nginx.conf` file. See [this issue](https://github.com/facebook/Docusaurus/issues/602) for more info.
|
||||
|
||||
### Hosting on a Service:
|
||||
|
||||
|
|
@ -101,7 +101,7 @@ However, you can automate the publishing process with continuous integration (CI
|
|||
|
||||
## Automating Deployments Using Continuous Integration
|
||||
|
||||
Continuous integration (CI) services are typically used to perform routine tasks whenever new commits are checked in to source control. These tasks can be any combination of running unit tests and integration tests, automating builds, publishing packages to NPM, and yes, deploying changes to your website. All you need to do to automate deployment of your website is to invoke the `publish-gh-pages` script whenever your docs get updated. In the following section we'll be covering how to do just that using [CircleCI](https://circleci.com/), a popular continuous integration service provider.
|
||||
Continuous integration (CI) services are typically used to perform routine tasks whenever new commits are checked in to source control. These tasks can be any combination of running unit tests and integration tests, automating builds, publishing packages to NPM, and yes, deploying changes to your website. All you need to do to automate deployment of your website is to invoke the `publish-gh-pages` script whenever your docs get updated. In the following section, we'll be covering how to do just that using [CircleCI](https://circleci.com/), a popular continuous integration service provider.
|
||||
|
||||
### Using CircleCI 2.0
|
||||
|
||||
|
|
@ -156,7 +156,7 @@ Make sure to replace all `<....>` in the `command:` sequence with appropriate va
|
|||
|
||||
> If you want to use SSH for your GitHub repository connection, you can set `USE_SSH=true`. So the above command would look something like: `cd website && npm install && GIT_USER=<GIT_USER> USE_SSH=true npm run publish-gh-pages`.
|
||||
|
||||
> Unlike when you run the `publish-gh-pages` script manually, when the script runs within the Circle environment, the value of `CURRENT_BRANCH` is already defined as an [environment variable within CircleCI](https://circleci.com/docs/1.0/environment-variables/) and will be picked up by the script automatically.
|
||||
> Unlike when you run the `publish-gh-pages` script manually when the script runs within the Circle environment, the value of `CURRENT_BRANCH` is already defined as an [environment variable within CircleCI](https://circleci.com/docs/1.0/environment-variables/) and will be picked up by the script automatically.
|
||||
|
||||
Now, whenever a new commit lands in `master`, CircleCI will run your suite of tests and, if everything passes, your website will be deployed via the `publish-gh-pages` script.
|
||||
|
||||
|
|
@ -174,7 +174,7 @@ CUSTOM_COMMIT_MESSAGE="[skip ci]" \
|
|||
yarn run publish-gh-pages # or `npm run publish-gh-pages`
|
||||
```
|
||||
|
||||
- Alternatively you can work around this by creating a basic CircleCI config with the following contents:
|
||||
- Alternatively, you can work around this by creating a basic CircleCI config with the following contents:
|
||||
```yaml
|
||||
# CircleCI 2.0 Config File
|
||||
# This config file will prevent tests from being run on the gh-pages branch.
|
||||
|
|
|
|||
|
|
@ -46,7 +46,7 @@ To create a fully functional site, you only need to do a few steps:
|
|||
My new content here..
|
||||
```
|
||||
|
||||
1. Add zero or more docs to the [`sidebars.json`](guides-navigation.md#adding-docs-to-a-sidebar) file so that your documentation is rendered in a sidebar, if you choose them to be.
|
||||
1. Add zero or more docs to the [`sidebars.json`](guides-navigation.md#adding-docs-to-a-sidebar) file so that your documentation is rendered in a sidebar if you choose them to be.
|
||||
|
||||
> If you do not add your documentation to the `sidebars.json` file, the docs will be rendered, but they can only be linked to from other documentation and visited with the known URL.
|
||||
|
||||
|
|
|
|||
|
|
@ -40,7 +40,7 @@ Of course, you are also free to write your own pages. It is strongly suggested t
|
|||
|
||||
Static `.html` files can also be used, but they will not include Docusaurus' header, footer, or styles by default. These can be added to the `static` directory in the same way as other [static assets](api-pages.md#using-static-assets). Alternatively, they can be placed in the `pages` directory and would be served as-is instead of being rendered from React.
|
||||
|
||||
If you wish to use Docusaurus' stylesheet, you can access it at `${baseUrl}css/main.css`. If you wish to use separate css for these static pages, you can exclude them from being concatenated to Docusaurus' styles by adding them into the `siteConfig.separateCss` field in `siteConfig.js`.
|
||||
If you wish to use Docusaurus' stylesheet, you can access it at `${baseUrl}css/main.css`. If you wish to use separate CSS for these static pages, you can exclude them from being concatenated to Docusaurus' styles by adding them into the `siteConfig.separateCss` field in `siteConfig.js`.
|
||||
|
||||
> You can set the [`$wrapPagesHTML` site config option](api-site-config.md#optional-fields) in order to wrap raw HTML fragments with the Docusaurus site styling, header and footer.
|
||||
|
||||
|
|
|
|||
|
|
@ -234,7 +234,7 @@ If search is enabled on your site, your search bar will appear to the right of y
|
|||
|
||||
### Languages Dropdown
|
||||
|
||||
If translations is enabled on your site, the language dropdown will appear to the right of your links (and to the left of the search bar, if search is enabled). If you want to put the language selection drop down between links in the header, add a languages entry in the `headerLinks` config array:
|
||||
If translations are enabled on your site, the language dropdown will appear to the right of your links (and to the left of the search bar, if search is enabled). If you want to put the language selection drop down between links in the header, add a languages entry in the `headerLinks` config array:
|
||||
|
||||
```js
|
||||
{
|
||||
|
|
@ -256,7 +256,7 @@ The links in the top navigation bar get `siteNavItemActive` and `siteNavGroupAct
|
|||
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
|
||||
- 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.
|
||||
|
||||
|
|
|
|||
|
|
@ -5,7 +5,7 @@ title: Enabling Search
|
|||
|
||||
Docusaurus supports search using [Algolia DocSearch](https://community.algolia.com/docsearch/). Once your website is online, you can [submit it to DocSearch](https://community.algolia.com/docsearch/). Algolia will then send you credentials you can add to your `siteConfig.js`.
|
||||
|
||||
DocSearch works by crawling the content of your website every 24 hours and putting all the content in an Algolia index. This content is then queried directly from your front-end using the Algolia API. Note that your website need to be publicly available for this to work (ie. not behind a firewall). This service is free.
|
||||
DocSearch works by crawling the content of your website every 24 hours and putting all the content in an Algolia index. This content is then queried directly from your front-end using the Algolia API. Note that your website needs to be publicly available for this to work (ie. not behind a firewall). This service is free.
|
||||
|
||||
## Enabling the Search Bar
|
||||
|
||||
|
|
@ -25,18 +25,18 @@ const siteConfig = {
|
|||
|
||||
## Extra Search Options
|
||||
|
||||
You can also specify extra [search options used by Algolia](https://community.algolia.com/docsearch/documentation/) by using an `algoliaOptions` field in `algolia`. This may be useful if you want to provide different search results for the different versions or languages of your docs. Any occurrences of "VERSION" or "LANGUAGE" will be replaced by the version or language of the current page, respectively. More details about search options can be [found here](https://www.algolia.com/doc/api-reference/api-parameters/#overview).
|
||||
You can also specify extra [search options used by Algolia](https://community.algolia.com/docsearch/documentation/) by using an `algoliaOptions` field in `algolia`. This may be useful if you want to provide different search results for the different versions or languages of your docs. Any occurrences of "VERSION" or "LANGUAGE" will be replaced by the version or language of the current page, respectively. More details about search options can be [found here](https://www.algolia.com/doc/api-reference/api-parameters/#overview).
|
||||
|
||||
```js
|
||||
const siteConfig = {
|
||||
...
|
||||
algolia: {
|
||||
...
|
||||
algoliaOptions: {
|
||||
facetFilters: [ "language:LANGUAGE", "version:VERSION" ]
|
||||
}
|
||||
},
|
||||
};
|
||||
```js
|
||||
const siteConfig = {
|
||||
...
|
||||
algolia: {
|
||||
...
|
||||
algoliaOptions: {
|
||||
facetFilters: [ "language:LANGUAGE", "version:VERSION" ]
|
||||
}
|
||||
},
|
||||
};
|
||||
```
|
||||
|
||||
Algolia might provide you with [extra search options](https://community.algolia.com/docsearch/documentation/). If so, you should add them to the `algoliaOptions` object.
|
||||
|
|
@ -66,13 +66,13 @@ const siteConfig = {
|
|||
If you want to change the placeholder (which defaults to *Search*), add the `placeholder` field in your config. For example, you may want the search bar to display *Ask me something*:
|
||||
|
||||
```js
|
||||
const siteConfig = {
|
||||
...
|
||||
algolia: {
|
||||
...
|
||||
const siteConfig = {
|
||||
...
|
||||
algolia: {
|
||||
...
|
||||
placeholder: 'Ask me something'
|
||||
},
|
||||
};
|
||||
},
|
||||
};
|
||||
```
|
||||
|
||||
## Disabling the Search Bar
|
||||
|
|
|
|||
|
|
@ -27,13 +27,13 @@ languages.js
|
|||
../crowdin.yaml
|
||||
```
|
||||
|
||||
* The `pages/en/help-with-translations.js` file includes the same starter help page generated by the `examples` script, but now includes translation tags.
|
||||
* The `pages/en/help-with-translations.js` file includes the same starter help page generated by the `examples` script but now includes translation tags.
|
||||
|
||||
> Generally, you will use `help-with-translations.js` as a guide to enable translations in your other pages, but not actually commit the file to your repo (i.e., you can delete it). However, if you want a Help page, and you currently do not have one, you can rename this file to `help.js` and use it as a starting point.
|
||||
|
||||
* The `languages.js` file tells Docusaurus what languages you want to enable for your site. By default, we expect English to be enabled.
|
||||
|
||||
* The `crowdin.yaml` file is used to configure Crowdin integration, and is copied up one level into your Docusaurus project repo. If your Docusaurus project resides in `/project/website`, then `crowdin.yaml` will be copied to `/project/crowdin.yaml`.
|
||||
* The `crowdin.yaml` file is used to configure Crowdin integration and is copied up one level into your Docusaurus project repo. If your Docusaurus project resides in `/project/website`, then `crowdin.yaml` will be copied to `/project/crowdin.yaml`.
|
||||
|
||||
## Translating Your Existing Docs
|
||||
|
||||
|
|
@ -41,7 +41,7 @@ Your documentation files (e.g., the `.md` files that live in your `docs` directo
|
|||
|
||||
## Enabling Translations on Pages
|
||||
|
||||
Pages allow you to customize layout and specific content of pages like a custom index page or help page.
|
||||
Pages allow you to customize the layout and specific content of pages like a custom index page or help page.
|
||||
|
||||
Pages with text that you want translated should be placed in `website/pages/en` directory.
|
||||
|
||||
|
|
@ -95,7 +95,7 @@ The script will include text from the following places:
|
|||
|
||||
### Custom Translation Strings
|
||||
|
||||
If you want to add additional custom translation strings, or override any of the strings that get produced by the script that creates the `website/i18n/en.json` file, you can add a `website/data/custom-translation-strings.json` file. The file should have form of:
|
||||
If you want to add additional custom translation strings or override any of the strings that get produced by the script that creates the `website/i18n/en.json` file, you can add a `website/data/custom-translation-strings.json` file. The file should have a form of:
|
||||
|
||||
```json
|
||||
{
|
||||
|
|
@ -146,9 +146,9 @@ This section provides context about how translations in Docusaurus works.
|
|||
|
||||
### Strings
|
||||
|
||||
A Docusaurus site has many strings used throughout it that require localization. However, maintaining a list of strings used through out a site can be laborious. Docusaurus simplifies this by centralizing strings.
|
||||
A Docusaurus site has many strings used throughout it that require localization. However, maintaining a list of strings used throughout a site can be laborious. Docusaurus simplifies this by centralizing strings.
|
||||
|
||||
The header navigation, for example can have links to 'Home' or your 'Blog'. This and other strings found in the headers and sidebars of pages are extracted and placed into `i18n/en.json`. When your files are translated, say into Spanish, a `i18n/es-ES.json` file will be downloaded from Crowdin. Then, when the Spanish pages are generated, Docusaurus will replace the English version of corresponding strings with translated strings from the corresponding localized strings file (e.g. In a Spanish enabled site 'Help' will become 'Ayuda').
|
||||
The header navigation, for example, can have links to 'Home' or your 'Blog'. This and other strings found in the headers and sidebars of pages are extracted and placed into `i18n/en.json`. When your files are translated, say into Spanish, an `i18n/es-ES.json` file will be downloaded from Crowdin. Then, when the Spanish pages are generated, Docusaurus will replace the English version of corresponding strings with translated strings from the corresponding localized strings file (e.g. In a Spanish enabled site 'Help' will become 'Ayuda').
|
||||
|
||||
### Markdown Files
|
||||
|
||||
|
|
|
|||
|
|
@ -3,7 +3,7 @@ id: tutorial-create-new-site
|
|||
title: Create a New Site
|
||||
---
|
||||
|
||||
In this section we'll get our Docusaurus site up and running for local development. The process takes less than a few minutes.
|
||||
In this section, we'll get our Docusaurus site up and running for local development. The process takes less than a few minutes.
|
||||
|
||||
<img alt="Docusaurus browser" src="/img/undraw_docusaurus_browser.svg" class="docImage"/>
|
||||
|
||||
|
|
|
|||
|
|
@ -3,7 +3,7 @@ id: tutorial-create-pages
|
|||
title: Create Pages
|
||||
---
|
||||
|
||||
In this section we will learn about creating two new types of pages in Docusaurus, a regular page and a documentation page.
|
||||
In this section, we will learn about creating two new types of pages in Docusaurus, a regular page and a documentation page.
|
||||
|
||||
<img alt="Docusaurus MacBook" src="/img/undraw_docusaurus_tree.svg" class="docImage"/>
|
||||
|
||||
|
|
@ -41,7 +41,7 @@ module.exports = HelloWorld;
|
|||
+ <p>I can write JSX here!</p>
|
||||
```
|
||||
|
||||
React is being used as a templating engine for rendering static markup. You can leverage on the expressability of React to build rich web content. Learn more about creating pages [here](custom-pages).
|
||||
React is being used as a templating engine for rendering static markup. You can leverage on the expressibility of React to build rich web content. Learn more about creating pages [here](custom-pages).
|
||||
|
||||
<img alt="Docusaurus React" src="/img/undraw_docusaurus_react.svg" class="docImage"/>
|
||||
|
||||
|
|
|
|||
|
|
@ -5,7 +5,7 @@ title: Publish the Site
|
|||
|
||||
<img alt="Docusaurus Facebook" src="/img/undraw_docusaurus_fb.svg" class="docImage"/>
|
||||
|
||||
Next we'll learn how to publish the site to the WWW for everyone to browse! For the purpose of the tutorial, we'll use GitHub pages to host our website. But you can use any static file hosting service that you want, e.g. Netlify, Amazon S3, etc.
|
||||
Next, we'll learn how to publish the site to the WWW for everyone to browse! For the purpose of the tutorial, we'll use GitHub pages to host our website. But you can use any static file hosting service that you want, e.g. Netlify, Amazon S3, etc.
|
||||
|
||||
## Put the Site Online
|
||||
|
||||
|
|
|
|||
|
|
@ -3,7 +3,7 @@ id: tutorial-version
|
|||
title: Add Versions
|
||||
---
|
||||
|
||||
With an example site deployed, we can now try out one of the killer features of Docusaurus - versioned documentation. Versioned documentation helps to show relevant documention to the users for the current version of the tool they are using and also hide unreleased documentation from users, reducing confusion. Documentation for older versions are also preserved and accessible to users of older versions of the tool even as the latest documentation changes.
|
||||
With an example site deployed, we can now try out one of the killer features of Docusaurus - versioned documentation. Versioned documentation helps to show relevant documentation to the users for the current version of the tool they are using and also hide unreleased documentation from users, reducing confusion. Documentations for older versions are also preserved and accessible to users of older versions of the tool even as the latest documentation changes.
|
||||
|
||||
<img alt="Docusaurus process" src="/img/undraw_docusaurus_process.svg" class="docImage"/>
|
||||
|
||||
|
|
@ -48,10 +48,10 @@ If we go to the `localhost:3000/<baseUrl>/docs/doc1` URL in our browser, realize
|
|||
|
||||
The latest versions of the docs have to be accessed by adding `next` to the URL: `localhost:3000/<baseUrl>/docs/next/doc1`. Note that the version beside the title also changes to `next` when we are on that URL.
|
||||
|
||||
A versions page has been created for us at `localhost:3000/<baseUrl>/versions` which shows a list of the current versions of the documentation. See that both `1.0.0` and `master` are being listed here and they correctly link to the respective versions of documentation.
|
||||
A versions page has been created for us at `localhost:3000/<baseUrl>/versions` which shows a list of the current versions of the documentation. See that both `1.0.0` and `master` are being listed here and they correctly link to the respective versions of the documentation.
|
||||
|
||||
Go ahead and publish your versioned site!
|
||||
|
||||
## Wrap Up
|
||||
|
||||
That's all folks! In this short tutorial you have experienced how easy it was to create a documentation website from scratch and making versions for them. There are many more things you can do with Docusaurus, such as adding a blog, search and translations. Check out the Guides section for more.
|
||||
That's all folks! In this short tutorial, you have experienced how easy it was to create a documentation website from scratch and making versions for them. There are many more things you can do with Docusaurus, such as adding a blog, search and translations. Check out the Guides section for more.
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue