Skip to content

Commit 18c0132

Browse files
yangshunJoelMarcey
yangshun
authored and
JoelMarcey
committed
Reformat, proofread and tidy up docs (facebook#749)
1 parent 33a0f30 commit 18c0132

14 files changed

+200
-212
lines changed

‎admin/testing-changes-on-Docusaurus-itself.md

+2-5
Original file line numberDiff line numberDiff line change
@@ -31,10 +31,7 @@ Use the following code in VSCode to enable breakpoints. Please ensure you have a
3131
"request": "launch",
3232
"cwd": "${workspaceFolder}/website",
3333
"runtimeExecutable": "npm",
34-
"runtimeArgs": [
35-
"run",
36-
"start-debug"
37-
],
34+
"runtimeArgs": ["run", "start-debug"],
3835
"port": 9229
3936
}
4037
]
@@ -47,4 +44,4 @@ Feel free to contribute debug instructions for other IDEs
4744

4845
### Observing changes
4946

50-
Now that the server is running, you can make changes to the core Docusaurus code and docs to see the effects on the Docusaurus site. LiveReload will reflect changes to the local site in your browser, usually running at http://localhost:3000
47+
Now that the server is running, you can make changes to the core Docusaurus code and docs to see the effects on the Docusaurus site. LiveReload will reflect changes to the local site in your browser, usually running at http://localhost:3000.

‎docs/api-commands.md

+25-26
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,6 @@ Docusaurus provides a set of scripts to help you generate, serve, and deploy you
88
* [`yarn run start`](api-commands.md#docusaurus-start-port-number): build and serve the website from a local server
99
* [`yarn run examples`](api-commands.md#docusaurus-examples): create example configuration files
1010

11-
1211
## Running from the command line
1312

1413
The scripts can be run using either Yarn or npm. If you've already gone through our Getting Started guide, you may already be familiar with the `start` command. It's the command that tells Docusaurus to run the `docusaurus-start` script which generates the site and starts up a server, and it's usually invoked like so:
@@ -49,17 +48,17 @@ Docusaurus provides some default mappings to allow you to run commands following
4948

5049
<AUTOGENERATED_TABLE_OF_CONTENTS>
5150

52-
-----
51+
---
5352

5453
## Reference
5554

5655
### `docusaurus-build`
5756

5857
Alias: `build`.
5958

60-
|Options|Default|Description|
61-
|---|---|---|
62-
|`--skip-image-compression`|`false`|Skip compression of image assets. You usually won't want to skip this unless your images have already been optimized.|
59+
| Options | Default | Description |
60+
| -------------------------- | ------- | --------------------------------------------------------------------------------------------------------------------- |
61+
| `--skip-image-compression` | `false` | Skip compression of image assets. You usually won't want to skip this unless your images have already been optimized. |
6362

6463
Generates the static website, applying translations if necessary. Useful for building the website prior to deployment.
6564

@@ -71,9 +70,9 @@ See also [`docusaurus-start`](api-commands.md#docusaurus-start).
7170

7271
Alias: `examples`
7372

74-
|Arguments|Default|Description|
75-
|---|---|---|
76-
|`<feature>`|-|Specify a feature `translations` or `versions` to generate the extra example files for that feature.|
73+
| Arguments | Default | Description |
74+
| ----------- | ------- | ---------------------------------------------------------------------------------------------------- |
75+
| `<feature>` | - | Specify a feature `translations` or `versions` to generate the extra example files for that feature. |
7776

7877
**Example**
7978

@@ -93,24 +92,24 @@ Alias: `publish-gh-pages`
9392

9493
The following environment variables are generally set manually by the user in the CircleCI `config.yml` file.
9594

96-
- `GIT_USER`: The git user to be associated with the deploy commit.
97-
- `USE_SSH`: Whether to use SSH instead of HTTPS for your connection to the GitHub repo.
95+
* `GIT_USER`: The git user to be associated with the deploy commit.
96+
* `USE_SSH`: Whether to use SSH instead of HTTPS for your connection to the GitHub repo.
9897

99-
**Example**
98+
**Example**
10099

101-
```bash
102-
GIT_USER=docusaurus-bot USE_SSH=true yarn run publish-gh-pages
103-
```
100+
```bash
101+
GIT_USER=docusaurus-bot USE_SSH=true yarn run publish-gh-pages
102+
```
104103

105104
The following environment variables are [set by CircleCI](https://circleci.com/docs/1.0/environment-variables/) during the build process.
106105

107-
- `CIRCLE_BRANCH`: The git branch associated with the commit that triggered the CI run.
108-
- `CI_PULL_REQUEST`: Expected to be truthy if the current CI run was triggered by a commit in a pull request.
106+
* `CIRCLE_BRANCH`: The git branch associated with the commit that triggered the CI run.
107+
* `CI_PULL_REQUEST`: Expected to be truthy if the current CI run was triggered by a commit in a pull request.
109108

110109
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/).
111110

112-
- `CIRCLE_PROJECT_USERNAME`: The GitHub username or organization name that hosts the Git repo, e.g. "facebook".
113-
- `CIRCLE_PROJECT_REPONAME`: The name of the Git repo, e.g. "Docusaurus".
111+
* `CIRCLE_PROJECT_USERNAME`: The GitHub username or organization name that hosts the Git repo, e.g. "facebook".
112+
* `CIRCLE_PROJECT_REPONAME`: The name of the Git repo, e.g. "Docusaurus".
114113

115114
You can learn more about configuring automatic deployments with CircleCI in the [Publishing guide](getting-started-publishing.md).
116115

@@ -122,10 +121,10 @@ Alias: `rename-version`
122121

123122
Renames an existing version of the docs to a new version name.
124123

125-
|Arguments|Default|Description|
126-
|---|---|---|
127-
|`<currentVersion>`|-|Version to be renamed.|
128-
|`<newVersion>`|-|Version to be renamed to.|
124+
| Arguments | Default | Description |
125+
| ------------------ | ------- | ------------------------- |
126+
| `<currentVersion>` | - | Version to be renamed. |
127+
| `<newVersion>` | - | Version to be renamed to. |
129128

130129
**Example**
131130

@@ -143,17 +142,17 @@ Alias: `start`.
143142

144143
This script will build the static website, apply translations if necessary, and then start a local server.
145144

146-
|Options|Default|Description|
147-
|---|---|---|
148-
|`--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.|
145+
| Options | Default | Description |
146+
| ----------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------ |
147+
| `--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. |
149148

150149
---
151150

152151
### `docusaurus-version <version>`
153152

154153
Alias: `version`
155154

156-
Generates a new version of the docs. This will result in a new copy of your site being generated and stored in its own versioned folder. Useful for capturing snapshots of API docs that map to specific versions of your software. Accepts any string as a version number.
155+
Generates a new version of the docs. This will result in a new copy of your site being generated and stored in its own versioned directory. Useful for capturing snapshots of API docs that map to specific versions of your software. Accepts any string as a version number.
157156

158157
See the [Versioning guide](guides-versioning.md) to learn more.
159158

‎docs/api-doc-markdown.md

+14-18
Original file line numberDiff line numberDiff line change
@@ -40,7 +40,7 @@ original_id: doc1
4040
---
4141
```
4242

43-
`custom_edit_url`: The url for editing this document. If this field is not present, the document's edit url will fallback to `editUrl` from optional fields of `siteConfig.js`. See [siteConfig.js](site-config.md) docs for more information.
43+
`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](site-config.md) docs for more information.
4444

4545
For example:
4646

@@ -54,7 +54,7 @@ custom_edit_url: https://github.com/facebook/Docusaurus/edit/master/docs/api-doc
5454

5555
### Blog Posts
5656

57-
Blog Posts use the following markdown header fields that are enclosed by a line `---` on either side:
57+
Blog posts use the following markdown header fields that are enclosed by a line `---` on either side:
5858

5959
`title`: The title of this blog post.
6060

@@ -81,20 +81,21 @@ Docusaurus supports some extra features when writing documentation in markdown.
8181

8282
### Linking other Documents
8383

84-
You can use relative urls to other documentation files which will automatically get converted to the corresponding html links when they get rendered.
84+
You can use relative URLs to other documentation files which will automatically get converted to the corresponding HTML links when they get rendered.
8585

8686
Example:
8787

8888
```md
8989
[This links to another document](other-document.md)
9090
```
91+
9192
This markdown will automatically get converted into a link to `/docs/other-document.html` (or the appropriately translated/versioned link) once it gets rendered.
9293

93-
This can help when you want to navigate through docs on GitHub since the links there will be functional links to other documents (still on GitHub), but the documents will have the correct html links when they get rendered.
94+
This can help when you want to navigate through docs on GitHub since the links there will be functional links to other documents (still on GitHub), but the documents will have the correct HTML links when they get rendered.
9495

9596
### Linking to Images and Other Assets
9697

97-
Static assets can be linked to in the same way that documents are, using relative urls. Static assets used in documents and blogs should go into `docs/assets` and `website/blog/assets`, respectively. The markdown will get converted into correct link paths so that these paths will work for documents of all languages and versions.
98+
Static assets can be linked to in the same way that documents are, using relative URLs. Static assets used in documents and blogs should go into `docs/assets` and `website/blog/assets`, respectively. The markdown will get converted into correct link paths so that these paths will work for documents of all languages and versions.
9899

99100
Example:
100101

@@ -104,7 +105,7 @@ Example:
104105

105106
### Generating Table of Contents
106107

107-
You can make an autogenerated list of links, which can be useful as a table of contents for API docs.
108+
You can make an auto-generated list of links, which can be useful as a table of contents for API docs.
108109

109110
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`>.
110111

@@ -123,8 +124,8 @@ Text describing my function
123124
will lead to a table of contents of the functions:
124125

125126
```md
126-
- `docusaurus.function(a, b)`
127-
- `docdoc(file)`
127+
* `docusaurus.function(a, b)`
128+
* `docdoc(file)`
128129
```
129130

130131
and each function will link to their corresponding sections in the page.
@@ -134,19 +135,13 @@ and each function will link to their corresponding sections in the page.
134135
Syntax highlighting is enabled by default on fenced code blocks. The language should be detected automatically, but you can sometimes get better results by specifying the language. You can do so using an [info string](https://github.github.com/gfm/#example-111), following the three opening backticks. The following JavaScript example...
135136

136137
```js
137-
ReactDOM.render(
138-
<h1>Hello, world!</h1>,
139-
document.getElementById('root')
140-
);
138+
ReactDOM.render(<h1>Hello, world!</h1>, document.getElementById('root'));
141139
```
142140

143141
...would be rendered with syntax highlighting like so:
144142

145143
```js
146-
ReactDOM.render(
147-
<h1>Hello, world!</h1>,
148-
document.getElementById('root')
149-
);
144+
ReactDOM.render(<h1>Hello, world!</h1>, document.getElementById('root'));
150145
```
151146

152147
Highlighting is provided by [Highlight.js](https://highlightjs.org) using the theme specified in your `siteConfig.js` file as part of the `highlight` key:
@@ -183,9 +178,10 @@ While Highlight.js provides support for [many popular languages out of the box](
183178

184179
### Using Prism as additional syntax highlighter
185180

186-
While highlight.js supports a lot of languages, you can opt to use Prism to syntax highlight certain languages available in the list [here](https://github.com/PrismJS/prism/tree/master/components). Include those languages in `usePrism` field in your [siteConfig.js](api-site-config.md)
181+
You can also opt to use Prism to syntax highlight certain languages available in the list [here](https://github.com/PrismJS/prism/tree/master/components). Include those languages in `usePrism` field in your [siteConfig.js](api-site-config.md)
187182

188183
Example:
184+
189185
```
190186
// siteConfig.js
191187
usePrism: ['jsx']
@@ -197,7 +193,7 @@ Notice that the code block below uses JSX syntax highlighting from Prism.
197193
class Example extends React.Component {
198194
render() {
199195
return (
200-
<View style={{ flex: 1, alignItems: 'center', justifyContent: 'center' }}>
196+
<View style={{flex: 1, alignItems: 'center', justifyContent: 'center'}}>
201197
<Text>Docusaurus</Text>
202198
<Button
203199
title="Click me"

0 commit comments

Comments
 (0)