mirror of
https://github.com/facebook/docusaurus.git
synced 2025-05-10 07:37:19 +02:00
misc: add command to run prettier on docs (#2102)
* misc: add command to run prettier on docs * Fix GH issue template * Fix tests * Add prettier-docs command to precommit
This commit is contained in:
Yangshun Tay
GitHub
parent
cfc313d7c7
commit
55e676cb25
141 changed files with 1181 additions and 968 deletions
|
|
@ -5,8 +5,8 @@ title: CLI Commands
|
|||
|
||||
Docusaurus provides a set of scripts to help you generate, serve, and deploy your website. These scripts can be invoked with the `run` command when using Yarn or npm. Some common commands are:
|
||||
|
||||
* [`yarn run start`](api-commands.md#docusaurus-start-port-number): build and serve the website from a local server
|
||||
* [`yarn run examples`](api-commands.md#docusaurus-examples): create example configuration files
|
||||
- [`yarn run start`](api-commands.md#docusaurus-start-port-number): build and serve the website from a local server
|
||||
- [`yarn run examples`](api-commands.md#docusaurus-examples): create example configuration files
|
||||
|
||||
## Running from the command line
|
||||
|
||||
|
|
@ -56,10 +56,10 @@ Docusaurus provides some default mappings to allow you to run commands following
|
|||
|
||||
Alias: `build`.
|
||||
|
||||
| Options | Default | Description |
|
||||
| -------------------------- | ------- | --------------------------------------------------------------------------------------------------------------------- |
|
||||
| Options | Default | Description |
|
||||
| --- | --- | --- |
|
||||
| `--skip-image-compression` | `false` | Skip compression of image assets. You usually won't want to skip this unless your images have already been optimized. |
|
||||
| `--skip-next-release` | `false` | Skip the next release documents when versioning is enabled. This will not build HTML files for documents in `/docs` directory.|
|
||||
| `--skip-next-release` | `false` | Skip the next release documents when versioning is enabled. This will not build HTML files for documents in `/docs` directory. |
|
||||
|
||||
Generates the static website, applying translations if necessary. Useful for building the website prior to deployment.
|
||||
|
||||
|
|
@ -71,9 +71,9 @@ See also [`docusaurus-start`](api-commands.md#docusaurus-start).
|
|||
|
||||
Alias: `examples`
|
||||
|
||||
| Arguments | Default | Description |
|
||||
| ----------- | ------- | ---------------------------------------------------------------------------------------------------- |
|
||||
| `<feature>` | - | Specify a feature `translations` or `versions` to generate the extra example files for that feature. |
|
||||
| Arguments | Default | Description |
|
||||
| --- | --- | --- |
|
||||
| `<feature>` | - | Specify a feature `translations` or `versions` to generate the extra example files for that feature. |
|
||||
|
||||
**Example**
|
||||
|
||||
|
|
@ -93,8 +93,8 @@ Alias: `publish-gh-pages`
|
|||
|
||||
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.
|
||||
- `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.
|
||||
|
||||
**Example**
|
||||
|
||||
|
|
@ -104,13 +104,13 @@ GIT_USER=docusaurus-bot USE_SSH=true yarn run publish-gh-pages
|
|||
|
||||
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.
|
||||
- `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).
|
||||
|
||||
|
|
@ -143,11 +143,11 @@ Alias: `start`.
|
|||
|
||||
This command will build the static website, apply translations if necessary, and then start a local server.
|
||||
|
||||
| Options | Default | Description |
|
||||
| ----------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------ |
|
||||
| `--port <number>` | `3000` | The website will be served from port 3000 by default, but if the port is taken up, Docusaurus will attempt to find an available one. |
|
||||
|`--host <host>`|`localhost`|Specify a host to use. E.g., if you want your server to be accessible externally, you can use --host 0.0.0.0.|
|
||||
| `--watch` | - | Whether to watch the files and live reload the page when files are changed. Defaults to true. Disable this by using `--no-watch`. |
|
||||
| Options | Default | Description |
|
||||
| --- | --- | --- |
|
||||
| `--port <number>` | `3000` | The website will be served from port 3000 by default, but if the port is taken up, Docusaurus will attempt to find an available one. |
|
||||
| `--host <host>` | `localhost` | Specify a host to use. E.g., if you want your server to be accessible externally, you can use --host 0.0.0.0. |
|
||||
| `--watch` | - | Whether to watch the files and live reload the page when files are changed. Defaults to true. Disable this by using `--no-watch`. |
|
||||
|
||||
You can specify the browser application to be opened by setting the `BROWSER` environment variable before the command, e.g.:
|
||||
|
||||
|
|
|
|||
|
|
@ -25,6 +25,7 @@ id: doc1
|
|||
title: My Document
|
||||
sidebar_label: Document
|
||||
---
|
||||
|
||||
```
|
||||
|
||||
Versioned documents have their ids altered to include the version number when they get copied. The new `id` is `version-${version}-${id}` where `${version}` is the version number of that document and `${id}` is the original `id`. Additionally, versioned documents get an added `original_id` field with the original document id.
|
||||
|
|
@ -38,6 +39,7 @@ title: My Document
|
|||
sidebar_label: Document
|
||||
original_id: doc1
|
||||
---
|
||||
|
||||
```
|
||||
|
||||
`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 optional fields of `siteConfig.js`. See [siteConfig.js](api-site-config.md) docs for more information.
|
||||
|
|
@ -50,6 +52,7 @@ id: doc-markdown
|
|||
title: Markdown Features
|
||||
custom_edit_url: https://github.com/facebook/docusaurus/edit/master/docs/api-doc-markdown.md
|
||||
---
|
||||
|
||||
```
|
||||
|
||||
### Blog Posts
|
||||
|
|
@ -73,6 +76,7 @@ author: Frank Li
|
|||
authorURL: http://twitter.com/franchementli
|
||||
authorFBID: 100002976521003
|
||||
---
|
||||
|
||||
```
|
||||
|
||||
## Extra Features
|
||||
|
|
@ -130,7 +134,6 @@ will lead to a table of contents of the functions:
|
|||
|
||||
and each function will link to their corresponding sections in the page.
|
||||
|
||||
|
||||
### Language-specific Code Tabs
|
||||
|
||||
Display code in multiple programming languages using code tabs. First, mark the start and end of a code tabs group, by using `<!-- DOCUSAURUS_CODE_TABS -->` and `<!-- END_DOCUSAURUS_CODE_TABS -->` respectively in your markdown. Then start each tab with `<!--[TAB_TITLE]-->`.
|
||||
|
|
@ -144,26 +147,30 @@ produces this:
|
|||
<!--DOCUSAURUS_CODE_TABS-->
|
||||
|
||||
<!--JavaScript-->
|
||||
|
||||
```js
|
||||
console.log('Hello, world!');
|
||||
```
|
||||
|
||||
<!--Python-->
|
||||
|
||||
```py
|
||||
print('Hello, world!')
|
||||
```
|
||||
|
||||
<!--C-->
|
||||
|
||||
```C
|
||||
#include <stdio.h>
|
||||
|
||||
int main() {
|
||||
printf("Hello World!");
|
||||
return 0;
|
||||
printf("Hello World!");
|
||||
return 0;
|
||||
}
|
||||
```
|
||||
|
||||
<!--Pascal-->
|
||||
|
||||
```Pascal
|
||||
program HelloWorld;
|
||||
begin
|
||||
|
|
|
|||
|
|
@ -71,8 +71,8 @@ module.exports = MyPage;
|
|||
This will be translated to a description metadata tag on the generated HTML.
|
||||
|
||||
```html
|
||||
<meta property="og:description" content="My Custom Description"/>
|
||||
<meta name="description" content="My Custom Description"/>
|
||||
<meta property="og:description" content="My Custom Description" />
|
||||
<meta name="description" content="My Custom Description" />
|
||||
```
|
||||
|
||||
## Page Require Paths
|
||||
|
|
@ -107,11 +107,11 @@ A React container component using Docusaurus styles. Has optional padding and ba
|
|||
|
||||
**Props**
|
||||
|
||||
| Prop | Type | Default | Description |
|
||||
| ------------ | ---------------------------------------------------------- | ------- | ----------------------------------- |
|
||||
| `padding` | Array of `'all'`, `'bottom'`, `'left'`, `'right'`, `'top'` | `[]` | Positions of the padding. |
|
||||
| `background` | One of `'dark'`, `'highlight'`, `'light'` | `null` | Background styling of the element. |
|
||||
| `className` | String | - | Custom class to add to the element. |
|
||||
| Prop | Type | Default | Description |
|
||||
| --- | --- | --- | --- |
|
||||
| `padding` | Array of `'all'`, `'bottom'`, `'left'`, `'right'`, `'top'` | `[]` | Positions of the padding. |
|
||||
| `background` | One of `'dark'`, `'highlight'`, `'light'` | `null` | Background styling of the element. |
|
||||
| `className` | String | - | Custom class to add to the element. |
|
||||
|
||||
**Example**
|
||||
|
||||
|
|
@ -130,23 +130,23 @@ A React component to organize text and images.
|
|||
|
||||
**Props**
|
||||
|
||||
| Prop | Type | Default | Description |
|
||||
| ----------- | ----------------------------------------------------- | ------------- | ---------------------------------------------------------------------------------------------------------------- |
|
||||
| `align` | One of `'left'`, `'center'`, `'right'` | `'left'` | Text alignment of content. |
|
||||
| `layout` | One of `'twoColumn'`, `'threeColumn'`, `'fourColumn'` | `'twoColumn'` | Number of column sections in the `GridBlock`. |
|
||||
| `className` | String | - | Custom class to add to the element. |
|
||||
| `contents` | Array of content objects | `[]` | Contents of each section of the GridBlock. Refer to the next table for the fields available on a content object. |
|
||||
| Prop | Type | Default | Description |
|
||||
| --- | --- | --- | --- |
|
||||
| `align` | One of `'left'`, `'center'`, `'right'` | `'left'` | Text alignment of content. |
|
||||
| `layout` | One of `'twoColumn'`, `'threeColumn'`, `'fourColumn'` | `'twoColumn'` | Number of column sections in the `GridBlock`. |
|
||||
| `className` | String | - | Custom class to add to the element. |
|
||||
| `contents` | Array of content objects | `[]` | Contents of each section of the GridBlock. Refer to the next table for the fields available on a content object. |
|
||||
|
||||
**Content Object**
|
||||
|
||||
| Key | Type | Default | Description |
|
||||
| ------------ | ----------------------------------------------- | -------- | ----------------------------------------------------------------- |
|
||||
| `title` | String | - | The display title of this section, which is parsed using Markdown |
|
||||
| `content` | String | - | The text of this section, which is parsed using Markdown |
|
||||
| `image` | String | - | The path of the display image |
|
||||
| `imageAlt` | String | - | The text that will be shown in case the image is not available |
|
||||
| `imageAlign` | One of `'top'`, `'left'`, `'bottom'`, `'right'` | `'left'` | Image alignment relative to the text |
|
||||
| `imageLink` | String | - | Link destination from clicking the image |
|
||||
| Key | Type | Default | Description |
|
||||
| --- | --- | --- | --- |
|
||||
| `title` | String | - | The display title of this section, which is parsed using Markdown |
|
||||
| `content` | String | - | The text of this section, which is parsed using Markdown |
|
||||
| `image` | String | - | The path of the display image |
|
||||
| `imageAlt` | String | - | The text that will be shown in case the image is not available |
|
||||
| `imageAlign` | One of `'top'`, `'left'`, `'bottom'`, `'right'` | `'left'` | Image alignment relative to the text |
|
||||
| `imageLink` | String | - | Link destination from clicking the image |
|
||||
|
||||
**Example**
|
||||
|
||||
|
|
|
|||
|
|
@ -130,8 +130,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.
|
||||
If unset, it is defaulted to `docs`.
|
||||
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]
|
||||
|
||||
|
|
|
|||
|
|
@ -13,13 +13,13 @@ To run the local web server:
|
|||
|
||||
1. **Build the docker image** -- Enter the folder where you have Docusaurus installed. Run `docker build -t docusaurus-doc .`
|
||||
|
||||
Once the build phase finishes, you can verify the image exists by running `docker images`.
|
||||
Once the build phase finishes, you can verify the image exists by running `docker images`.
|
||||
|
||||
> We now include a `Dockerfile` when you install Docusaurus.
|
||||
> We now include a `Dockerfile` when you install Docusaurus.
|
||||
|
||||
2. **Run the Docusaurus container** -- To start docker run `docker run --rm -p 3000:3000 docusaurus-doc`
|
||||
|
||||
This will start a docker container with the image `docusaurus-doc`. To see more detailed container info run `docker ps` .
|
||||
This will start a docker container with the image `docusaurus-doc`. To see more detailed container info run `docker ps` .
|
||||
|
||||
## Use docker-compose
|
||||
|
||||
|
|
@ -36,8 +36,9 @@ Using Compose is a three-step process:
|
|||
3. Run `docker-compose up` and Compose starts and runs your entire app.
|
||||
|
||||
We include a basic `docker-compose.yml` in your project:
|
||||
``` yml
|
||||
version: "3"
|
||||
|
||||
```yml
|
||||
version: '3'
|
||||
|
||||
services:
|
||||
docusaurus:
|
||||
|
|
@ -55,7 +56,6 @@ services:
|
|||
- ./website/sidebars.json:/app/website/sidebars.json
|
||||
- ./website/siteConfig.js:/app/website/siteConfig.js
|
||||
working_dir: /app/website
|
||||
|
||||
```
|
||||
|
||||
To run a local web server with `docker-compose` run `docker-compose up`.
|
||||
|
|
|
|||
|
|
@ -16,9 +16,7 @@ We have created a helpful script that will get all of the infrastructure set up
|
|||
|
||||
1. Create a project, if none exists, and change your directory to this project's root.
|
||||
|
||||
You will be creating the docs in this directory. The root directory may
|
||||
contain other files. The Docusaurus installation script will create two new
|
||||
directories: `docs` and `website`.
|
||||
You will be creating the docs in this directory. The root directory may contain other files. The Docusaurus installation script will create two new directories: `docs` and `website`.
|
||||
|
||||
> Commonly, either an existing or newly created GitHub project will be the location for your Docusaurus site, but that is not mandatory to use Docusaurus.
|
||||
|
||||
|
|
@ -61,15 +59,11 @@ root-directory
|
|||
|
||||
## Running the example website
|
||||
|
||||
After running the Docusaurus initialization script, `docusaurus-init` as
|
||||
described in the [Installation](#installing-docusaurus) section, you will have a
|
||||
runnable, example website to use as your site's base. To run:
|
||||
After running the Docusaurus initialization script, `docusaurus-init` as described in the [Installation](#installing-docusaurus) section, you will have a runnable, example website to use as your site's base. To run:
|
||||
|
||||
1. `cd website`
|
||||
1. From within the `website` directory, run the local web server using
|
||||
`yarn start` or `npm start`.
|
||||
1. Load the example site at http://localhost:3000 if it did not already open
|
||||
automatically. If port 3000 has already been taken, another port will be used. Look at the console messages to see which.
|
||||
1. From within the `website` directory, run the local web server using `yarn start` or `npm start`.
|
||||
1. Load the example site at http://localhost:3000 if it did not already open automatically. If port 3000 has already been taken, another port will be used. Look at the console messages to see which.
|
||||
|
||||
You should see the example site loaded in your web browser. There's also a LiveReload server running and any changes made to the docs and files in the `website` directory will cause the page to refresh. A randomly generated primary and secondary theme color will be picked for you.
|
||||
|
||||
|
|
|
|||
|
|
@ -25,10 +25,10 @@ At this point, you can grab all of the files inside the `website/build` director
|
|||
|
||||
### Hosting on a Service:
|
||||
|
||||
* [ZEIT Now](#using-zeit-now)
|
||||
* [GitHub Pages](#using-github-pages)
|
||||
* [Netlify](#hosting-on-netlify)
|
||||
* [Render](#hosting-on-render)
|
||||
- [ZEIT Now](#using-zeit-now)
|
||||
- [GitHub Pages](#using-github-pages)
|
||||
- [Netlify](#hosting-on-netlify)
|
||||
- [Render](#hosting-on-render)
|
||||
|
||||
### Using ZEIT Now
|
||||
|
||||
|
|
@ -60,17 +60,16 @@ Docusaurus was designed to work really well with one of the most popular hosting
|
|||
|
||||
> Even if your repository is private, anything published to a `gh-pages` branch will be [public](https://help.github.com/articles/user-organization-and-project-pages/).
|
||||
|
||||
__Note:__ When you deploy as user/organization page, the publish script will deploy these sites to the root of the __`master`__ branch of the _username_.github.io repo. In this case, note that you will want to have the Docusaurus infra, your docs, etc. either in __another branch of the _username_.github.io repo__ (e.g., maybe call it `source`), or in another, separate repo (e.g. in the same as the documented source code).
|
||||
**Note:** When you deploy as user/organization page, the publish script will deploy these sites to the root of the **`master`** branch of the _username_.github.io repo. In this case, note that you will want to have the Docusaurus infra, your docs, etc. either in **another branch of the _username_.github.io repo** (e.g., maybe call it `source`), or in another, separate repo (e.g. in the same as the documented source code).
|
||||
|
||||
2. You will need to modify the file `website/siteConfig.js` and add the required parameters.
|
||||
|
||||
| Name | Description |
|
||||
| ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `organizationName` | The GitHub user or organization that owns the repository. If you are the owner, then it is your GitHub username. In the case of Docusaurus, that would be the "_facebook_" GitHub organization. |
|
||||
| `projectName` | The name of the GitHub repository for your project. For example, the source code for Docusaurus is hosted at https://github.com/facebook/docusaurus, so our project name in this case would be "docusaurus". |
|
||||
| `url` | Your website's URL. For projects hosted on GitHub pages, this will be "https://_username_.github.io" |
|
||||
| `baseUrl` | Base URL for your project. For projects hosted on GitHub pages, it follows the format "/_projectName_/". For https://github.com/facebook/docusaurus, `baseUrl` is `/docusaurus/`. |
|
||||
|
||||
| Name | Description |
|
||||
| --- | --- |
|
||||
| `organizationName` | The GitHub user or organization that owns the repository. If you are the owner, then it is your GitHub username. In the case of Docusaurus, that would be the "_facebook_" GitHub organization. |
|
||||
| `projectName` | The name of the GitHub repository for your project. For example, the source code for Docusaurus is hosted at https://github.com/facebook/docusaurus, so our project name in this case would be "docusaurus". |
|
||||
| `url` | Your website's URL. For projects hosted on GitHub pages, this will be "https://_username_.github.io" |
|
||||
| `baseUrl` | Base URL for your project. For projects hosted on GitHub pages, it follows the format "/_projectName_/". For https://github.com/facebook/docusaurus, `baseUrl` is `/docusaurus/`. |
|
||||
|
||||
```js
|
||||
const siteConfig = {
|
||||
|
|
@ -85,19 +84,20 @@ const siteConfig = {
|
|||
|
||||
In case you want to deploy as a user or organization site, specify the project name as `<username>.github.io` or `<orgname>.github.io`. E.g. If your GitHub username is "user42" then _user42.github.io_, or in the case of an organization name of "org123", it will be _org123.github.io_.
|
||||
|
||||
__Note:__ Not setting the `url` and `baseUrl` of your project might result in incorrect file paths generated which can cause broken links to assets paths like stylesheets and images.
|
||||
**Note:** Not setting the `url` and `baseUrl` of your project might result in incorrect file paths generated which can cause broken links to assets paths like stylesheets and images.
|
||||
|
||||
> While we recommend setting the `projectName` and `organizationName` in `siteConfig.js`, you can also use environment variables `ORGANIZATION_NAME` and `PROJECT_NAME`.
|
||||
|
||||
3. Now you have to specify the git user as an environment variable, and run the script [`publish-gh-pages`](./api-commands.md#docusaurus-publish)
|
||||
|
||||
| Name | Description |
|
||||
| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
|
||||
| Name | Description |
|
||||
| --- | --- |
|
||||
| `GIT_USER` | The username for a GitHub account that has commit access to this repo. For your own repositories, this will usually be your own GitHub username. The specified `GIT_USER` must have push access to the repository specified in the combination of `organizationName` and `projectName`. |
|
||||
|
||||
To run the script directly from the command-line, you can use the following, filling in the parameter values as appropriate.
|
||||
|
||||
**Bash**
|
||||
|
||||
```bash
|
||||
GIT_USER=<GIT_USER> \
|
||||
CURRENT_BRANCH=master \
|
||||
|
|
@ -106,15 +106,16 @@ GIT_USER=<GIT_USER> \
|
|||
```
|
||||
|
||||
**Windows**
|
||||
|
||||
```batch
|
||||
cmd /C "set GIT_USER=<GIT_USER> && set CURRENT_BRANCH=master && set USE_SSH=true && yarn run publish-gh-pages"
|
||||
```
|
||||
|
||||
There are also two optional parameters that are set as environment variables:
|
||||
|
||||
| Name | Description |
|
||||
| ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `USE_SSH` | If this is set to `true`, then SSH is used instead of HTTPS for the connection to the GitHub repo. HTTPS is the default if this variable is not set. |
|
||||
| Name | Description |
|
||||
| --- | --- |
|
||||
| `USE_SSH` | If this is set to `true`, then SSH is used instead of HTTPS for the connection to the GitHub repo. HTTPS is the default if this variable is not set. |
|
||||
| `CURRENT_BRANCH` | The branch that contains the latest docs changes that will be deployed. Usually, the branch will be `master`, but it could be any branch (default or otherwise) except for `gh-pages`. If nothing is set for this variable, then the current branch will be used. |
|
||||
|
||||
If you run into issues related to SSH keys, visit [GitHub's authentication documentation](https://help.github.com/articles/connecting-to-github-with-ssh/).
|
||||
|
|
@ -195,14 +196,16 @@ Now, whenever a new commit lands in `master`, CircleCI will run your suite of te
|
|||
When initially deploying to a `gh-pages` branch using CircleCI, you may notice that some jobs triggered by commits to the `gh-pages` branch fail to run successfully due to a lack of tests (This can also result in chat/slack build failure notifications).
|
||||
|
||||
You can work around this by:
|
||||
- Setting the environment variable `CUSTOM_COMMIT_MESSAGE` flag to the `publish-gh-pages` command with the contents of `[skip ci]`.
|
||||
e.g.
|
||||
|
||||
- Setting the environment variable `CUSTOM_COMMIT_MESSAGE` flag to the `publish-gh-pages` command with the contents of `[skip ci]`. e.g.
|
||||
|
||||
```bash
|
||||
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:
|
||||
|
||||
```yaml
|
||||
# CircleCI 2.0 Config File
|
||||
# This config file will prevent tests from being run on the gh-pages branch.
|
||||
|
|
@ -258,8 +261,8 @@ Steps to configure your Docusaurus-powered site on Netlify.
|
|||
1. Select the branch to deploy. Default is `master`
|
||||
1. Configure your build steps:
|
||||
|
||||
* For your build command enter: `cd website; npm install; npm run build;`
|
||||
* For publish directory: `website/build/<projectName>` (use the `projectName` from your `siteConfig`)
|
||||
- For your build command enter: `cd website; npm install; npm run build;`
|
||||
- For publish directory: `website/build/<projectName>` (use the `projectName` from your `siteConfig`)
|
||||
|
||||
1. Click **Deploy site**
|
||||
|
||||
|
|
@ -273,22 +276,22 @@ Render offers free [static site](https://render.com/docs/static-sites) hosting w
|
|||
|
||||
2. Select the branch to deploy. The default is `master`.
|
||||
|
||||
2. Enter the following values during creation.
|
||||
3. Enter the following values during creation.
|
||||
|
||||
| Field | Value |
|
||||
| ------- | ----- |
|
||||
| **Environment** | `Static Site` |
|
||||
| **Build Command** | `cd website; yarn install; yarn build` |
|
||||
| **Publish Directory** | `website/build/<projectName>` |
|
||||
| Field | Value |
|
||||
| --------------------- | -------------------------------------- |
|
||||
| **Environment** | `Static Site` |
|
||||
| **Build Command** | `cd website; yarn install; yarn build` |
|
||||
| **Publish Directory** | `website/build/<projectName>` |
|
||||
|
||||
`projectName` is the value you defined in your `siteConfig.js`.
|
||||
`projectName` is the value you defined in your `siteConfig.js`.
|
||||
|
||||
```javascript{7}
|
||||
const siteConfig = {
|
||||
// ...
|
||||
projectName: 'your-project-name',
|
||||
// ...
|
||||
```
|
||||
```javascript{7}
|
||||
const siteConfig = {
|
||||
// ...
|
||||
projectName: 'your-project-name',
|
||||
// ...
|
||||
```
|
||||
|
||||
That's it! Your app will be live on your Render URL as soon as the build finishes.
|
||||
|
||||
|
|
|
|||
|
|
@ -42,7 +42,6 @@ To create a fully functional site, you only need to do a few steps:
|
|||
id: intro
|
||||
title: Getting Started
|
||||
---
|
||||
|
||||
My new content here..
|
||||
```
|
||||
|
||||
|
|
@ -71,18 +70,22 @@ If you prefer to have your landing page be straight to your documentation, you c
|
|||
1. Add a [custom static `index.html` page](guides-custom-pages.md#adding-static-pages) in the `website/static` directory with the following contents:
|
||||
|
||||
```html
|
||||
<!DOCTYPE HTML>
|
||||
<!DOCTYPE html>
|
||||
<html lang="en-US">
|
||||
<head>
|
||||
<meta charset="UTF-8">
|
||||
<meta http-equiv="refresh" content="0; url=docs/id-of-doc-to-land-on.html">
|
||||
<meta charset="UTF-8" />
|
||||
<meta
|
||||
http-equiv="refresh"
|
||||
content="0; url=docs/id-of-doc-to-land-on.html"
|
||||
/>
|
||||
<script type="text/javascript">
|
||||
window.location.href = 'docs/id-of-doc-to-land-on.html';
|
||||
</script>
|
||||
<title>Your Site Title Here</title>
|
||||
</head>
|
||||
<body>
|
||||
If you are not redirected automatically, follow this <a href="docs/id-of-doc-to-land-on.html">link</a>.
|
||||
If you are not redirected automatically, follow this
|
||||
<a href="docs/id-of-doc-to-land-on.html">link</a>.
|
||||
</body>
|
||||
</html>
|
||||
```
|
||||
|
|
|
|||
|
|
@ -63,7 +63,7 @@ const siteConfig = {
|
|||
|
||||
## Customizing the placeholder
|
||||
|
||||
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*:
|
||||
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 = {
|
||||
|
|
|
|||
|
|
@ -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 `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
|
||||
|
||||
|
|
@ -87,11 +87,11 @@ Running the script will generate a `website/i18n/en.json` file containing all th
|
|||
|
||||
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`
|
||||
|
||||
### Custom Translation Strings
|
||||
|
||||
|
|
@ -111,7 +111,7 @@ If you want to add additional custom translation strings or override any of the
|
|||
}
|
||||
}
|
||||
},
|
||||
"pages-strings" : {
|
||||
"pages-strings": {
|
||||
"id3": "string3",
|
||||
"id4": "string4"
|
||||
}
|
||||
|
|
@ -128,8 +128,8 @@ Here is an example:
|
|||
"localized-strings": {
|
||||
"translation": "Translations and Localization"
|
||||
},
|
||||
"pages-strings" : {
|
||||
"Help Translate|recruit community translators for your project": "Help Us Translate"
|
||||
"pages-strings": {
|
||||
"Help Translate|recruit community translators for your project": "Help Us Translate"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
|
@ -177,12 +177,11 @@ Below is an example Crowdin configuration for the respective languages: German,
|
|||
```yaml
|
||||
project_identifier_env: CROWDIN_DOCUSAURUS_PROJECT_ID
|
||||
api_key_env: CROWDIN_DOCUSAURUS_API_KEY
|
||||
base_path: "./"
|
||||
base_path: './'
|
||||
preserve_hierarchy: true
|
||||
|
||||
files:
|
||||
-
|
||||
source: '/docs/**/*.md'
|
||||
- source: '/docs/**/*.md'
|
||||
translation: '/website/translated_docs/%locale%/**/%original_file_name%'
|
||||
languages_mapping: &anchor
|
||||
locale:
|
||||
|
|
|
|||
|
|
@ -64,7 +64,6 @@ The following contents will be created in your current directory. Some example d
|
|||
└── yarn.lock
|
||||
```
|
||||
|
||||
|
||||
3. Run `cd website` to go into the `website` directory.
|
||||
4. Run `npm start` or `yarn start`.
|
||||
|
||||
|
|
|
|||
|
|
@ -32,7 +32,7 @@ GIT_USER=USERNAME CURRENT_BRANCH=master USE_SSH=true npm run publish-gh-pages #
|
|||
GIT_USER=USERNAME CURRENT_BRANCH=master npm run publish-gh-pages # HTTPS
|
||||
```
|
||||
|
||||
The HTML files (and other file types) are pushed to the `gh-pages` branch of your repository: https://github.com/USERNAME/docusaurus-tutorial.
|
||||
The HTML files (and other file types) are pushed to the `gh-pages` branch of your repository: https://github.com/USERNAME/docusaurus-tutorial.
|
||||
|
||||
5. Go to https://USERNAME.github.io/docusaurus-tutorial/ and view your site in action!
|
||||
|
||||
|
|
|
|||
|
|
@ -56,7 +56,7 @@ We highly recommend that you install Yarn, an alternative package manager that h
|
|||
|
||||
<img alt="GitHub create repo" src="/img/tutorial-git-clone.png" class="docImage"/>
|
||||
|
||||
5. In Terminal or Git Bash, `cd` to a directory where the local clone will be a subdirectory.
|
||||
5. In Terminal or Git Bash, `cd` to a directory where the local clone will be a subdirectory.
|
||||
|
||||
```sh
|
||||
cd /Users/NAME/doc_projects # macOS example
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue