From 18c01327a3082962165263c37b4a49d5426fbf53 Mon Sep 17 00:00:00 2001 From: Yangshun Tay Date: Sun, 10 Jun 2018 08:02:04 -0700 Subject: [PATCH] Reformat, proofread and tidy up docs (#749) --- admin/testing-changes-on-Docusaurus-itself.md | 7 +-- docs/api-commands.md | 51 ++++++++-------- docs/api-doc-markdown.md | 32 +++++----- docs/api-pages.md | 54 ++++++++--------- docs/api-site-config.md | 24 ++++---- docs/getting-started-installation.md | 18 +++--- docs/getting-started-preparation.md | 14 ++--- docs/getting-started-publishing.md | 59 ++++++++++--------- docs/getting-started-site-creation.md | 51 ++++++++-------- docs/guides-blog.md | 20 +++---- docs/guides-custom-pages.md | 31 +++++----- docs/guides-navigation.md | 6 +- docs/guides-translation.md | 19 +++--- docs/guides-versioning.md | 26 ++++---- 14 files changed, 200 insertions(+), 212 deletions(-) diff --git a/admin/testing-changes-on-Docusaurus-itself.md b/admin/testing-changes-on-Docusaurus-itself.md index 3ec45b4102b3..a675521c0570 100644 --- a/admin/testing-changes-on-Docusaurus-itself.md +++ b/admin/testing-changes-on-Docusaurus-itself.md @@ -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 } ] @@ -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. diff --git a/docs/api-commands.md b/docs/api-commands.md index 2beba786d7f8..7b10c40aa20b 100644 --- a/docs/api-commands.md +++ b/docs/api-commands.md @@ -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: @@ -49,7 +48,7 @@ Docusaurus provides some default mappings to allow you to run commands following ------ +--- ## Reference @@ -57,9 +56,9 @@ Docusaurus provides some default mappings to allow you to run commands following 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. @@ -71,9 +70,9 @@ See also [`docusaurus-start`](api-commands.md#docusaurus-start). Alias: `examples` -|Arguments|Default|Description| -|---|---|---| -|``|-|Specify a feature `translations` or `versions` to generate the extra example files for that feature.| +| Arguments | Default | Description | +| ----------- | ------- | ---------------------------------------------------------------------------------------------------- | +| `` | - | Specify a feature `translations` or `versions` to generate the extra example files for that feature. | **Example** @@ -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). @@ -122,10 +121,10 @@ Alias: `rename-version` Renames an existing version of the docs to a new version name. -|Arguments|Default|Description| -|---|---|---| -|``|-|Version to be renamed.| -|``|-|Version to be renamed to.| +| Arguments | Default | Description | +| ------------------ | ------- | ------------------------- | +| `` | - | Version to be renamed. | +| `` | - | Version to be renamed to. | **Example** @@ -143,9 +142,9 @@ Alias: `start`. This script will build the static website, apply translations if necessary, and then start a local server. -|Options|Default|Description| -|---|---|---| -|`--port `|`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 ` | `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. | --- @@ -153,7 +152,7 @@ This script will build the static website, apply translations if necessary, and 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. diff --git a/docs/api-doc-markdown.md b/docs/api-doc-markdown.md index 932284c0c36e..3c2d0920e8a2 100644 --- a/docs/api-doc-markdown.md +++ b/docs/api-doc-markdown.md @@ -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: @@ -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. @@ -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: @@ -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`>. @@ -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. @@ -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( -

Hello, world!

, - document.getElementById('root') - ); + ReactDOM.render(

Hello, world!

, document.getElementById('root')); ``` ...would be rendered with syntax highlighting like so: ```js -ReactDOM.render( -

Hello, world!

, - document.getElementById('root') -); +ReactDOM.render(

Hello, world!

, 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: @@ -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'] @@ -197,7 +193,7 @@ Notice that the code block below uses JSX syntax highlighting from Prism. class Example extends React.Component { render() { return ( - + Docusaurus