Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
- Loading branch information
1 parent
8d676e6
commit 5b4fb4b
Showing
18 changed files
with
1,947 additions
and
3 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.
Oops, something went wrong.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,138 @@ | ||
| --- | ||
| id: version-1.0.15-commands | ||
| title: CLI Commands | ||
| original_id: 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 | ||
|
|
||
|
|
||
| ## 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: | ||
|
|
||
| ```bash | ||
| yarn run start | ||
| ``` | ||
|
|
||
| The same script can be invoked using npm: | ||
|
|
||
| ```bash | ||
| npm run start | ||
| ``` | ||
|
|
||
| To run a particular script, just replace the `start` command in the examples above with the command associated with your script. | ||
|
|
||
| ## Using arguments | ||
|
|
||
| Some commands support optional arguments. For example, to start a server on port 8080, you can specify the `--port` argument when running `start`: | ||
|
|
||
| ```bash | ||
| yarn run start --port 8080 | ||
| ``` | ||
|
|
||
| If you run Docusaurus using npm, you can still use the command line arguments by inserting a `--` between `npm run <command>` and the command arguments: | ||
|
|
||
| ```bash | ||
| npm run start -- --port 8080 | ||
| ``` | ||
|
|
||
| ## Configuration | ||
|
|
||
| These scripts are set up under the `"scripts"` key in your `website/package.json` file as part of the installation process. If you need help setting them up again, please refer to the [Installation guide](getting-started-installation.md). | ||
|
|
||
| Docusaurus provides some default mappings to allow you to run commands following Node conventions. Instead of typing `docusaurus-start` every time, you can type `yarn run start` or `npm start` to achieve the same. | ||
|
|
||
| ## Commands | ||
|
|
||
| <AUTOGENERATED_TABLE_OF_CONTENTS> | ||
|
|
||
| ----- | ||
|
|
||
| ## Reference | ||
|
|
||
| ### `docusaurus-build` | ||
|
|
||
| Alias: `build`. | ||
|
|
||
| Generates the static website, applying translations if necessary. Useful for building the website prior to deployment. | ||
|
|
||
| See also [`docusaurus-start`](api-commands.md#docusaurus-start-port-number). | ||
|
|
||
| --- | ||
|
|
||
| ### `docusaurus-examples [feature]` | ||
|
|
||
| Alias: `examples` | ||
|
|
||
| When no feature is specified, sets up a minimally configured example website in your project. This command is covered in depth in the [Site Preparation guide](getting-started-preparation.md). Specify a feature `translations` or `versions` to generate the extra example files for that feature. | ||
|
|
||
| --- | ||
|
|
||
| ### `docusaurus-publish` | ||
|
|
||
| Alias: `publish-gh-pages` | ||
|
|
||
| [Builds](api-commands.md#docusaurus-build), then deploys the static website to GitHub Pages. This command is meant to be run during the deployment step in Circle CI, and therefore expects a few environment variables to be defined: | ||
|
|
||
| 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. | ||
|
|
||
| e.g., | ||
|
|
||
| ```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. | ||
|
|
||
| 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". | ||
|
|
||
| You can learn more about configuring automatic deployments with CircleCI in the [Publishing guide](getting-started-publishing.md). | ||
|
|
||
| --- | ||
|
|
||
| ### `docusaurus-rename-version <currentVersion> <newVersion>` | ||
|
|
||
| Alias: `rename-version` | ||
|
|
||
| Renames an existing version of the docs to a new version name. | ||
|
|
||
| See the [Versioning guide](guides-versioning.md#renaming-existing-versions) to learn more. | ||
|
|
||
| --- | ||
|
|
||
| ### `docusaurus-start [--port <number>]` | ||
|
|
||
| Alias: `start`. | ||
|
|
||
| This script will build the static website, apply translations if necessary, and then start a local server. The website will be served from port 3000 by default. | ||
|
|
||
| --- | ||
|
|
||
| ### `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. | ||
|
|
||
| See the [Versioning guide](guides-versioning.md) to learn more. | ||
|
|
||
| --- | ||
|
|
||
| ### `docusaurus-write-translations` | ||
|
|
||
| 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. |
183 changes: 183 additions & 0 deletions
183
website/versioned_docs/version-1.0.15/api-doc-markdown.md
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,183 @@ | ||
| --- | ||
| id: version-1.0.15-doc-markdown | ||
| title: Markdown Features | ||
| original_id: doc-markdown | ||
| --- | ||
|
|
||
| ## Markdown Headers | ||
|
|
||
| ### Documents | ||
|
|
||
| Documents use the following markdown header fields that are enclosed by a line `---` on either side: | ||
|
|
||
| `id`: A unique document id. If this field is not present, the document's `id` will default to its file name (without the extension). | ||
|
|
||
| `title`: The title of your document. If this field is not present, the document's `title` will default to its `id`. | ||
|
|
||
| `hide_title`: Whether to hide the title at the top of the doc. | ||
|
|
||
| `sidebar_label`: The text shown in the document sidebar for this document. If this field is not present, the document's `sidebar_label` will default to its `title`. | ||
|
|
||
| For example: | ||
|
|
||
| ```yaml | ||
| --- | ||
| 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. | ||
|
|
||
| For example: | ||
|
|
||
| ```yaml | ||
| --- | ||
| id: version-1.0.0-doc1 | ||
| 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 fallback to `editUrl` from optional fields of `siteConfig.js`. See [siteConfig.js](site-config.md) docs for more information. | ||
|
|
||
| For example: | ||
|
|
||
| ```yaml | ||
| --- | ||
| id: doc-markdown | ||
| title: Markdown Features | ||
| custom_edit_url: https://github.com/facebook/Docusaurus/edit/master/docs/api-doc-markdown.md | ||
| --- | ||
| ``` | ||
|
|
||
| ### Blog Posts | ||
|
|
||
| Blog Posts use the following markdown header fields that are enclosed by a line `---` on either side: | ||
|
|
||
| `title`: The title of this blog post. | ||
|
|
||
| `author`: The author of this blog post. If this field is omitted, no author name will be shown. | ||
|
|
||
| `authorURL`: A page to link to when a site user clicks the author's name. If this field is omitted, the author's name will not link to anything. | ||
|
|
||
| `authorFBID`: The author's Facebook id, used only to get the author's profile picture to display with the blog post. If this field is omitted, no author picture will be shown for the blog post. | ||
|
|
||
| For example: | ||
|
|
||
| ```yaml | ||
| --- | ||
| title: My First Blog Post | ||
| author: Frank Li | ||
| authorURL: http://twitter.com/franchementli | ||
| authorFBID: 100002976521003 | ||
| --- | ||
| ``` | ||
|
|
||
| ## Extra Features | ||
|
|
||
| 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. | ||
|
|
||
| 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. | ||
|
|
||
| ### 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. | ||
|
|
||
| Example: | ||
|
|
||
| ```md | ||
|  | ||
| ``` | ||
|
|
||
| ### Generating Table of Contents | ||
|
|
||
| You can make an autogenerated 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`>. | ||
|
|
||
| Example: | ||
|
|
||
| ```md | ||
| ### `docusaurus.function(a, b)` | ||
|
|
||
| Text describing my function | ||
|
|
||
| ### `docdoc(file)` | ||
|
|
||
| Text describing my function | ||
| ``` | ||
|
|
||
| will lead to a table of contents of the functions: | ||
|
|
||
| ```md | ||
| - `docusaurus.function(a, b)` | ||
| - `docdoc(file)` | ||
| ``` | ||
|
|
||
| and each function will link to their corresponding sections in the page. | ||
|
|
||
| ## Syntax Highlighting | ||
|
|
||
| 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') | ||
| ); | ||
| ``` | ||
|
|
||
| ...would be rendered with syntax highlighting like so: | ||
|
|
||
| ```js | ||
| 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: | ||
|
|
||
| ```js | ||
| { | ||
| ... | ||
| highlight: { | ||
| theme: 'default' | ||
| } | ||
| ... | ||
| } | ||
| ``` | ||
|
|
||
| You can find the full list of supported themes in the Highlight.js [`styles`](https://github.com/isagalaev/highlight.js/tree/master/src/styles) directory. | ||
|
|
||
| ### Registering additional languages | ||
|
|
||
| While Highlight.js provides support for [many popular languages out of the box](https://highlightjs.org/static/demo/), you may find the need to register additional language support. For these cases, we provide an escape valve by exposing the `hljs` constant as part of the `highlight` config key. This in turn allows you to call [`registerLanguage`](http://highlightjs.readthedocs.io/en/latest/api.html#registerlanguage-name-language): | ||
|
|
||
| ```js | ||
| { | ||
| ... | ||
| highlight: { | ||
| theme: 'default', | ||
| hljs: function(hljs) { | ||
| hljs.registerLanguage('galacticbasic', function(hljs) { | ||
| // ... | ||
| }); | ||
| } | ||
| } | ||
| } | ||
| ``` |
Oops, something went wrong.