Skip to content

Commit

Permalink
Reformat, proofread and tidy up docs (#749)
Browse files Browse the repository at this point in the history
  • Loading branch information
@yangshun @JoelMarcey
yangshun authored and JoelMarcey committed Jun 10, 2018
1 parent 33a0f30 commit 18c0132
Show file tree
Hide file tree
Showing 14 changed files with 200 additions and 212 deletions.
7 changes: 2 additions & 5 deletions admin/testing-changes-on-Docusaurus-itself.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -31,10 +31,7 @@ Use the following code in VSCode to enable breakpoints. Please ensure you have a
"request": "launch",
"cwd": "${workspaceFolder}/website",
"runtimeExecutable": "npm",
"runtimeArgs": [
"run",
"start-debug"
],
"runtimeArgs": ["run", "start-debug"],
"port": 9229
}
]
Expand All @@ -47,4 +44,4 @@ Feel free to contribute debug instructions for other IDEs

### Observing changes

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
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.
51 changes: 25 additions & 26 deletions docs/api-commands.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,6 @@ Docusaurus provides a set of scripts to help you generate, serve, and deploy you
* [`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

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:
Expand Down Expand Up @@ -49,17 +48,17 @@ Docusaurus provides some default mappings to allow you to run commands following

<AUTOGENERATED_TABLE_OF_CONTENTS>

-----
---

## Reference

### `docusaurus-build`

Alias: `build`.

|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.|
| 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. |

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

Expand All @@ -71,9 +70,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**

Expand All @@ -93,24 +92,24 @@ 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**
**Example**

```bash
GIT_USER=docusaurus-bot USE_SSH=true yarn run publish-gh-pages
```
```bash
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).

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

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

|Arguments|Default|Description|
|---|---|---|
|`<currentVersion>`|-|Version to be renamed.|
|`<newVersion>`|-|Version to be renamed to.|
| Arguments | Default | Description |
| ------------------ | ------- | ------------------------- |
| `<currentVersion>` | - | Version to be renamed. |
| `<newVersion>` | - | Version to be renamed to. |

**Example**

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

This script 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.|
| 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. |

---

### `docusaurus-version <version>`

Alias: `version`

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.
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.

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

Expand Down
32 changes: 14 additions & 18 deletions docs/api-doc-markdown.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -40,7 +40,7 @@ original_id: doc1
---
```

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

For example:

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

### Blog Posts

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

`title`: The title of this blog post.

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

### Linking other Documents

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

Example:

```md
[This links to another document](other-document.md)
```

This markdown will automatically get converted into a link to `/docs/other-document.html` (or the appropriately translated/versioned link) once it gets rendered.

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.
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.

### Linking to Images and Other Assets

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.
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.

Example:

Expand All @@ -104,7 +105,7 @@ Example:

### Generating Table of Contents

You can make an autogenerated list of links, which can be useful as a table of contents for API docs.
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`>.

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

```md
- `docusaurus.function(a, b)`
- `docdoc(file)`
* `docusaurus.function(a, b)`
* `docdoc(file)`
```

and each function will link to their corresponding sections in the page.
Expand All @@ -134,19 +135,13 @@ and each function will link to their corresponding sections in the page.
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...

```js
ReactDOM.render(
<h1>Hello, world!</h1>,
document.getElementById('root')
);
ReactDOM.render(<h1>Hello, world!</h1>, document.getElementById('root'));
```

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

```js
ReactDOM.render(
<h1>Hello, world!</h1>,
document.getElementById('root')
);
ReactDOM.render(<h1>Hello, world!</h1>, document.getElementById('root'));
```

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

### Using Prism as additional syntax highlighter

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)
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)

Example:

```
// siteConfig.js
usePrism: ['jsx']
Expand All @@ -197,7 +193,7 @@ Notice that the code block below uses JSX syntax highlighting from Prism.
class Example extends React.Component {
render() {
return (
<View style={{ flex: 1, alignItems: 'center', justifyContent: 'center' }}>
<View style={{flex: 1, alignItems: 'center', justifyContent: 'center'}}>
<Text>Docusaurus</Text>
<Button
title="Click me"
Expand Down
Loading

0 comments on commit 18c0132

Please sign in to comment.