mirror of
https://github.com/facebook/docusaurus.git
synced 2025-04-29 10:17:55 +02:00
Reformat, proofread and tidy up docs (#749)
This commit is contained in:
Yangshun Tay
Joel Marcey
parent
33a0f309ff
commit
18c01327a3
14 changed files with 200 additions and 212 deletions
|
|
@ -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.
|
||||
|
|
|
|||
|
|
@ -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
|
|||
|
||||
<AUTOGENERATED_TABLE_OF_CONTENTS>
|
||||
|
||||
-----
|
||||
---
|
||||
|
||||
## 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|
|
||||
|---|---|---|
|
||||
|`<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,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|
|
||||
|---|---|---|
|
||||
|`<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**
|
||||
|
||||
|
|
@ -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 <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. |
|
||||
|
||||
---
|
||||
|
||||
|
|
@ -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.
|
||||
|
||||
|
|
|
|||
|
|
@ -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(
|
||||
<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:
|
||||
|
|
@ -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 (
|
||||
<View style={{ flex: 1, alignItems: 'center', justifyContent: 'center' }}>
|
||||
<View style={{flex: 1, alignItems: 'center', justifyContent: 'center'}}>
|
||||
<Text>Docusaurus</Text>
|
||||
<Button
|
||||
title="Click me"
|
||||
|
|
|
|||
|
|
@ -3,11 +3,11 @@ id: api-pages
|
|||
title: Pages and Styles
|
||||
---
|
||||
|
||||
Docusaurus provides support for writing pages as React components inside the `website/pages` folder which will share the same header, footer, and styles as the rest of the site.
|
||||
Docusaurus provides support for writing pages as React components inside the `website/pages` directory which will share the same header, footer, and styles as the rest of the site.
|
||||
|
||||
## URLs for Pages
|
||||
|
||||
Any `.js` files in `website/pages` will be rendered to static html using the path of the file after "pages". Files in `website/pages/en` will also get copied out into `pages` and will OVERRIDE any files of the same name in `pages`. For example, the page for the `website/pages/en/help.js` file will be found at the url `${baseUrl}en/help.js` as well as the url `${baseUrl}help.js`, where `${baseUrl}` is the `baseUrl` field set in your [siteConfig.js file](api-site-config.md).
|
||||
Any `.js` files in `website/pages` will be rendered to static HTML using the path of the file after `pages`. Files in `website/pages/en` will also get copied out into `pages` and will OVERRIDE any files of the same name in `pages`. For example, the page for the `website/pages/en/help.js` file will be found at the URL `${baseUrl}en/help.js` as well as the URL `${baseUrl}help.js`, where `${baseUrl}` is the `baseUrl` field set in your [siteConfig.js file](api-site-config.md).
|
||||
|
||||
## Titles for Pages
|
||||
|
||||
|
|
@ -31,11 +31,11 @@ module.exports = MyPage;
|
|||
|
||||
## Page Require Paths
|
||||
|
||||
Docusaurus provides a few useful React components for users to write their own pages, found in the `CompLibrary` module. This module is provided as part of Docusaurus in `node_modules/docusaurus`, so to access it, pages in the `pages` folder are temporarily copied into `node_modules/docusaurus` when rendering to static html. As seen in the example files, this means that a user page at `pages/en/index.js` uses a require path to `'../../core/CompLibrary.js'` to import the provided components.
|
||||
Docusaurus provides a few useful React components for users to write their own pages, found in the `CompLibrary` module. This module is provided as part of Docusaurus in `node_modules/docusaurus`, so to access it, pages in the `pages` directory are temporarily copied into `node_modules/docusaurus` when rendering to static HTML. As seen in the example files, this means that a user page at `pages/en/index.js` uses a require path to `'../../core/CompLibrary.js'` to import the provided components.
|
||||
|
||||
What this means to the user is that if you wish to use the `CompLibrary` module, make sure the require path is set correctly. For example, a page at `page/mypage.js` would use a path `'../core/CompLibrary.js'`.
|
||||
|
||||
If you wish to use your own components inside the website folder, use `process.cwd()` which will refer to the `website` folder to construct require paths. For example, if you add a component to `website/core/mycomponent.js`, you can use the require path, `'process.cwd() + /core/mycomponent.js'`.
|
||||
If you wish to use your own components inside the website directory, use `process.cwd()` which will refer to the `website` directory to construct require paths. For example, if you add a component to `website/core/mycomponent.js`, you can use the require path, `'process.cwd() + /core/mycomponent.js'`.
|
||||
|
||||
## Provided Components
|
||||
|
||||
|
|
@ -61,11 +61,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**
|
||||
|
||||
|
|
@ -84,23 +84,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**
|
||||
|
||||
|
|
@ -131,11 +131,11 @@ A React component to organize text and images.
|
|||
/>
|
||||
```
|
||||
|
||||
More examples of how these components are used can be found in the [generated example files](getting-started-preparation.md) as well as in Docusaurus' own repo for its website set-up.
|
||||
More examples of how these components are used can be found in the [generated example files](getting-started-preparation.md) as well as in Docusaurus' own repository for its website set-up.
|
||||
|
||||
## Translating Strings
|
||||
|
||||
When translations are enabled, any pages inside `website/pages/en` will be translated for all enabled languages. Urls for non-English pages will use their language tags as specified in the `languages.js` file. E.g. The url for a French page of `website/pages/en/help.js` would be found at `${baseUrl}fr/help.html`.
|
||||
When translations are enabled, any pages inside `website/pages/en` will be translated for all enabled languages. URLs for non-English pages will use their language tags as specified in the `languages.js` file. E.g. The URL for a French page of `website/pages/en/help.js` would be found at `${baseUrl}fr/help.html`.
|
||||
|
||||
When writing pages that you wish to translate, wrap any strings to be translated inside a `<translate>` tag. e.g.,
|
||||
|
||||
|
|
@ -165,12 +165,12 @@ Note that this path is valid for files inside `pages/en` and should be adjusted
|
|||
|
||||
## Using Static Assets
|
||||
|
||||
Static assets should be placed into the `website/static` folder. They can be accessed by their paths, excluding `static`. For example, if the site's `baseUrl` is `/docusaurus/`, an image in `website/static/img/logo.png` is available at `/docusaurus/img/logo.png`.
|
||||
Static assets should be placed into the `website/static` directory. They can be accessed by their paths, excluding `static`. For example, if the site's `baseUrl` is `/docusaurus/`, an image in `website/static/img/logo.png` is available at `/docusaurus/img/logo.png`.
|
||||
|
||||
## Styles
|
||||
|
||||
You should configure your site's primary, secondary, and code block colors using the `colors` field in `siteConfig` as specified [here](api-site-config.md). You can also configure other colors in the same way as described in the `siteConfig` doc.
|
||||
|
||||
You can provide your own custom styles by adding them anywhere in the `website/static` folder. Any `.css` files you provide in the `static` folder will get concatenated to the end of Docusaurus' provided styles, allowing you to add to or override Docusaurus default styles as you wish.
|
||||
You can provide your own custom styles by adding them anywhere in the `website/static` directory. Any `.css` files you provide in the `static` directory will get concatenated to the end of Docusaurus' provided styles, allowing you to add to or override Docusaurus default styles as you wish.
|
||||
|
||||
An easy way to figure out what classes you wish to override or add to is to [start your server locally](api-commands.md) and use your browser's inspect element tool.
|
||||
|
|
|
|||
|
|
@ -27,9 +27,9 @@ The `siteConfig` object contains the bulk of the configuration settings for your
|
|||
|
||||
`copyright` - The copyright string at footer of site and within feed
|
||||
|
||||
`favicon` - url for site favicon.
|
||||
`favicon` - URL for site favicon.
|
||||
|
||||
`headerIcon` - url for icon used in header navigation bar.
|
||||
`headerIcon` - URL for icon used in header navigation bar.
|
||||
|
||||
`headerLinks` - Links that will be used in the header navigation bar. The `label` field of each object will be the link text and will also be translated for each language.
|
||||
|
||||
|
|
@ -56,7 +56,7 @@ headerLinks: [
|
|||
|
||||
`organizationName` - GitHub username of the organization or user hosting this project. This is used by the publishing script to determine where your GitHub pages website will be hosted.
|
||||
|
||||
`projectName` - Project name. This must match your GitHub repo project name (case sensitive).
|
||||
`projectName` - Project name. This must match your GitHub repository project name (case-sensitive).
|
||||
|
||||
`tagline` - Tagline for your website.
|
||||
|
||||
|
|
@ -74,9 +74,9 @@ headerLinks: [
|
|||
|
||||
`blogSidebarCount` - Control the number of blog posts that show up in the sidebar. See the [adding a blog docs](guides-blog.md#changing-how-many-blog-posts-show-on-sidebar) for more information.
|
||||
|
||||
`cleanUrl` - If `true`, allow URLs with no `html` extension. Example: request to URL https://docusaurus.io/docs/installation will returns the same result as https://docusaurus.io/docs/installation.html.
|
||||
`cleanUrl` - If `true`, allow URLs with no `html` extension. For example, a request to URL https://docusaurus.io/docs/installation will returns the same result as https://docusaurus.io/docs/installation.html.
|
||||
|
||||
`cname` - The CNAME for your website. It will go into a `CNAME` file when your site it built.
|
||||
`cname` - The CNAME for your website. It will go into a `CNAME` file when your site is built.
|
||||
|
||||
`customDocsPath` - By default, Docusaurus expects your documentation to be in a directory called `docs`. This directory is at the same level as the `website` directory (i.e., not inside the `website` directory). You can specify a custom path to your documentation with this field.
|
||||
|
||||
|
|
@ -94,7 +94,7 @@ customDocsPath: 'website-docs';
|
|||
|
||||
`disableTitleTagline` - An option to disable showing the tagline in the title of main pages. Exclude this field to keep page titles as `Title • Tagline`. Set to `true` to make page titles just `Title`.
|
||||
|
||||
`editUrl` - url for editing docs, usage example: `editUrl + 'en/doc1.md'`. If this field is omitted, there will be no "Edit this Doc" button for each document.
|
||||
`editUrl` - URL for editing docs, usage example: `editUrl + 'en/doc1.md'`. If this field is omitted, there will be no "Edit this Doc" button for each document.
|
||||
|
||||
`facebookAppId` - If you want Facebook Like/Share buttons in the footer and at the bottom of your blog posts, provide a [Facebook application id](https://www.facebook.com/help/audiencenetwork/804209223039296).
|
||||
|
||||
|
|
@ -102,7 +102,7 @@ customDocsPath: 'website-docs';
|
|||
|
||||
`facebookPixelId` - [Facebook Pixel](https://www.facebook.com/business/a/facebook-pixel) ID to track page views.
|
||||
|
||||
`fonts` - Font-family css configuration for the site. If a font family is specified in `siteConfig.js` as `$myFont`, then adding a `myFont` key to an array in `fonts` will allow you to configure the font. Items appearing earlier in the array will take priority of later elements, so ordering of the fonts matter.
|
||||
`fonts` - Font-family CSS configuration for the site. If a font family is specified in `siteConfig.js` as `$myFont`, then adding a `myFont` key to an array in `fonts` will allow you to configure the font. Items appearing earlier in the array will take priority of later elements, so ordering of the fonts matter.
|
||||
|
||||
In the below example, we have two sets of font configurations, `myFont` and `myOtherFont`. `Times New Roman` is the preferred font in `myFont`. `-apple-system` is the preferred in `myOtherFont`.
|
||||
|
||||
|
|
@ -153,11 +153,11 @@ h1 {
|
|||
|
||||
`scripts` - Array of JavaScript sources to load. The script tag will be inserted in the HTML head.
|
||||
|
||||
`separateCss` - Folders inside which any `css` files will not be processed and concatenated to Docusaurus' styles. This is to support static `html` pages that may be separate from Docusaurus with completely separate styles.
|
||||
`separateCss` - Directories inside which any `css` files will not be processed and concatenated to Docusaurus' styles. This is to support static `html` pages that may be separate from Docusaurus with completely separate styles.
|
||||
|
||||
`scrollToTop` - Set this to `true` if you want to enable the scroll to top button at the bottom of your site.
|
||||
|
||||
`scrollToTopOptions` - Optional options configuration for the scroll to top button. You do not need to use this, even if you set `scrollToTop` to `true`; it just provides you more configuration control of the button. You can find more options [here](https://github.com/vfeskov/vanilla-back-to-top/blob/v7.1.14/OPTIONS.md). By default, we set the zIndex option to 100.
|
||||
`scrollToTopOptions` - Optional options configuration for the scroll to top button. You do not need to use this, even if you set `scrollToTop` to `true`; it just provides you more configuration control of the button. You can find more options [here](https://github.com/vfeskov/vanilla-back-to-top/blob/v7.1.14/OPTIONS.md). By default, we set the zIndex option to 100.
|
||||
|
||||
`stylesheets` - Array of CSS sources to load. The link tag will be inserted in the HTML head.
|
||||
|
||||
|
|
@ -196,7 +196,7 @@ const siteConfig = {
|
|||
tagline: 'Generate websites!',
|
||||
url: 'https://docusaurus.io',
|
||||
baseUrl: '/',
|
||||
// For github.io type URLS, you would combine the url and baseUrl like:
|
||||
// For github.io type URLS, you would combine the URL and baseUrl like:
|
||||
// url: 'https://reasonml.github.io',
|
||||
// baseUrl: '/reason-react/',
|
||||
defaultVersionShown: '1.0.0',
|
||||
|
|
@ -257,8 +257,8 @@ const siteConfig = {
|
|||
cleanUrl: true,
|
||||
scrollToTop: true,
|
||||
scrollToTopOptions: {
|
||||
zIndex: 100
|
||||
}
|
||||
zIndex: 100,
|
||||
},
|
||||
};
|
||||
|
||||
module.exports = siteConfig;
|
||||
|
|
|
|||
|
|
@ -5,12 +5,12 @@ title: Installation
|
|||
|
||||
Docusaurus was designed from the ground up to be easily installed and used to get your website up and running quickly. To install Docusaurus, we have created an easy script that will get all of the infrastructure set up for you:
|
||||
|
||||
1. Ensure you have the latest version of [Node](https://nodejs.org/en/download/) installed. We also recommend you install [Yarn](https://yarnpkg.com/en/docs/install) as well.
|
||||
1. Ensure you have the latest version of [Node](https://nodejs.org/en/download/) installed. We also recommend you install [Yarn](https://yarnpkg.com/en/docs/install) as well.
|
||||
|
||||
> While we recommend Node 8.x or greater, your Node version must at least 6.x. Your Yarn version must also be at at least 1.5 as well.
|
||||
> You have to be on Node >= 8.x and Yarn >= 1.5.
|
||||
|
||||
1. Go into the root of your GitHub repo directory where you will be creating the docs.
|
||||
1. `npx docusaurus-init`
|
||||
1. Go into the root of your GitHub repo directory where you will be creating the docs.
|
||||
1. `npx docusaurus-init`
|
||||
|
||||
> If you don't have Node 8.2+ or if you prefer to install Docusaurus globally, run `yarn global add docusaurus-init` or `npm install --global docusaurus-init`. After that, run `docusaurus-init`.
|
||||
|
||||
|
|
@ -46,11 +46,11 @@ root-directory
|
|||
|
||||
Running the Docusaurus initialization script, `docusaurus-init`, produces a runnable, example website to base your site upon.
|
||||
|
||||
1. In your root, rename `docs-examples-from-docusaurus` to `docs`.
|
||||
1. `cd website`
|
||||
1. Rename `blog-examples-from-docusaurus` to `blog`.
|
||||
1. Run the local webserver via `yarn start` or `npm start`.
|
||||
1. Load the example site at http://localhost:3000. You should see the example site loaded in your web browser.
|
||||
1. In your root, rename `docs-examples-from-docusaurus` to `docs`.
|
||||
1. `cd website`
|
||||
1. Rename `blog-examples-from-docusaurus` to `blog`.
|
||||
1. Run the local webserver via `yarn start` or `npm start`.
|
||||
1. Load the example site at http://localhost:3000. 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.
|
||||
|
||||
|
||||
|
||||
|
|
|
|||
|
|
@ -35,13 +35,13 @@ root-directory
|
|||
|
||||
> You may have already renamed the example blog (`website/blog-examples-from-docusaurus`) and document (`docs-examples-from-docusaurus`) directories when you [verified the installation](getting-started-installation.md##verifying-installation).
|
||||
|
||||
- The `website/core/Footer.js` file is a React component that acts as the footer for the site generated by Docusaurus and should be customized by the user.
|
||||
- The `website/blog-examples-from-docusaurus` folder contains examples of blog posts written in markdown.
|
||||
- The `docs-examples-from-docusaurus` folder contains example documentation files written in markdown.
|
||||
- The `website/pages` folder contains example top-level pages for the site.
|
||||
- The `website/static` folder contains static assets used by the example site.
|
||||
- The `website/siteConfig.js` file is the main configuration file used by Docusaurus.
|
||||
* The `website/core/Footer.js` file is a React component that acts as the footer for the site generated by Docusaurus and should be customized by the user.
|
||||
* The `website/blog-examples-from-docusaurus` directory contains examples of blog posts written in markdown.
|
||||
* The `docs-examples-from-docusaurus` directory contains example documentation files written in markdown.
|
||||
* The `website/pages` directory contains example top-level pages for the site.
|
||||
* The `website/static` directory contains static assets used by the example site.
|
||||
* The `website/siteConfig.js` file is the main configuration file used by Docusaurus.
|
||||
|
||||
You will need to keep the `website/siteConfig.js` and `website/core/Footer.js` files, but may edit them as you wish.
|
||||
|
||||
You should keep the `website/pages` and `website/static` folders, but may change the content inside them as you wish. At the bare minimum you should have an `en/index.js` or `en/index.html` file inside `website/pages` and an image to use as your header icon inside `website/static`.
|
||||
You should keep the `website/pages` and `website/static` directories, but may change the content inside them as you wish. At the bare minimum you should have an `en/index.js` or `en/index.html` file inside `website/pages` and an image to use as your header icon inside `website/static`.
|
||||
|
|
|
|||
|
|
@ -13,11 +13,11 @@ To create a static build of your website, run the following script from the `web
|
|||
yarn run build # or `npm run build`
|
||||
```
|
||||
|
||||
This will generate a `build` folder inside the `website` directory containing the `.html` files from all of your docs and other pages included in `pages`.
|
||||
This will generate a `build` directory inside the `website` directory containing the `.html` files from all of your docs and other pages included in `pages`.
|
||||
|
||||
## Hosting Static HTML Pages
|
||||
|
||||
At this point, you can grab all of the files inside the `website/build` folder and copy them over to your favorite web server's `html` directory.
|
||||
At this point, you can grab all of the files inside the `website/build` directory and copy them over to your favorite web server's `html` directory.
|
||||
|
||||
> For example, both Apache and nginx serve content from `/var/www/html` by default. That said, choosing a web server or provider is outside the scope of Docusaurus.
|
||||
|
||||
|
|
@ -34,7 +34,7 @@ While choosing a web server or host is outside Docusaurus' scope, Docusaurus was
|
|||
|
||||
Deploying your Docusaurus site to GitHub Pages is straightforward if you are already using GitHub to host your project. Your code repository does not even need to be public.
|
||||
|
||||
> Even if your repo is private, anything published to a `gh-pages` branch will be [public](https://help.github.com/articles/user-organization-and-project-pages/).
|
||||
> 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/).
|
||||
|
||||
Most of the work to publish to GitHub pages is done for you automatically through the [`publish-gh-pages`](./api-commands.md#docusaurus-publish) script. You just need to determine the values for a few parameters required by the script.
|
||||
|
||||
|
|
@ -64,7 +64,7 @@ There are also two optional parameters that are set as environment variables:
|
|||
|
||||
Once you have the parameter value information, you can go ahead and run the publish script, ensuring you have inserted your own values inside the various parameter placeholders:
|
||||
|
||||
To run the script directly from the command-line, you can use the following, filling in the parameter values as appropriate. If you run into issues related to SSH keys, visit [Github's authentication documentation](https://help.github.com/articles/connecting-to-github-with-ssh/).
|
||||
To run the script directly from the command-line, you can use the following, filling in the parameter values as appropriate. If you run into issues related to SSH keys, visit [GitHub's authentication documentation](https://help.github.com/articles/connecting-to-github-with-ssh/).
|
||||
|
||||
```bash
|
||||
GIT_USER=<GIT_USER> \
|
||||
|
|
@ -75,7 +75,7 @@ GIT_USER=<GIT_USER> \
|
|||
|
||||
> The specified `GIT_USER` must have push access to the repository specified in the combination of `organizationName` and `projectName`.
|
||||
|
||||
You should now be able to load your website by visiting its GitHub Pages URL, which could be something along the lines of https://_username_.github.io/_projectName_, or a custom domain if you have set that up. For example, Docusaurus' own GitHub Pages URL is https://facebook.github.io/Docusaurus (it can also be accessed via https://docusaurus.io/), because it is served from the `gh-pages` branch of the https://github.com/facebook/docusaurus GitHub repo. We highly encourage reading through the [GitHub Pages documentation](https://pages.github.com) to learn more about how this hosting solution works.
|
||||
You should now be able to load your website by visiting its GitHub Pages URL, which could be something along the lines of https://_username_.github.io/_projectName_, or a custom domain if you have set that up. For example, Docusaurus' own GitHub Pages URL is https://facebook.github.io/Docusaurus (it can also be accessed via https://docusaurus.io/), because it is served from the `gh-pages` branch of the https://github.com/facebook/docusaurus GitHub repository. We highly encourage reading through the [GitHub Pages documentation](https://pages.github.com) to learn more about how this hosting solution works.
|
||||
|
||||
You can run the command above any time you update the docs and wish to deploy the changes to your site. Running the script manually may be fine for sites where the documentation rarely changes and it is not too much of an inconvenience to remember to manually deploy changes.
|
||||
|
||||
|
|
@ -89,13 +89,13 @@ Continuous integration (CI) services are typically used to perform routine tasks
|
|||
|
||||
If you haven't done so already, you can [setup CircleCI](https://circleci.com/signup/) for your open source project. Afterwards, in order to enable automatic deployment of your site and documentation via CircleCI, just configure Circle to run the `publish-gh-pages` script as part of the deployment step. You can follow the steps below to get that setup.
|
||||
|
||||
1. Ensure the GitHub account that will be set as the `GIT_USER` has `write` access to the repo that contains the documentation, by checking `Settings | Collaborators & teams` in the repo.
|
||||
1. Log into GitHub as the `GIT_USER`.
|
||||
1. Go to https://github.com/settings/tokens for the `GIT_USER` and generate a new [personal access token](https://help.github.com/articles/creating-a-personal-access-token-for-the-command-line/), granting it full control of private repositories through the `repo` access scope. Store this token in a safe place, making sure to not share it with anyone. This token can be used to authenticate GitHub actions on your behalf in place of your GitHub password.
|
||||
1. Open your Circle CI dashboard, and navigate to the Settings page for your repository, then select "Environment variables". The URL looks like https://circleci.com/gh/ORG/REPO/edit#env-vars, where "ORG/REPO" should be replaced with your own GitHub org/repo.
|
||||
1. Create a new environment variable named `GITHUB_TOKEN`, using your newly generated access token as the value.
|
||||
1. Create a `.circleci` folder and create a `config.yml` under that folder.
|
||||
1. Copy the text below into `.circleci/config.yml`.
|
||||
1. Ensure the GitHub account that will be set as the `GIT_USER` has `write` access to the repository that contains the documentation, by checking `Settings | Collaborators & teams` in the repository.
|
||||
1. Log into GitHub as the `GIT_USER`.
|
||||
1. Go to https://github.com/settings/tokens for the `GIT_USER` and generate a new [personal access token](https://help.github.com/articles/creating-a-personal-access-token-for-the-command-line/), granting it full control of private repositories through the `repository` access scope. Store this token in a safe place, making sure to not share it with anyone. This token can be used to authenticate GitHub actions on your behalf in place of your GitHub password.
|
||||
1. Open your Circle CI dashboard, and navigate to the Settings page for your repository, then select "Environment variables". The URL looks like https://circleci.com/gh/ORG/REPO/edit#env-vars, where "ORG/REPO" should be replaced with your own GitHub organization/repository.
|
||||
1. Create a new environment variable named `GITHUB_TOKEN`, using your newly generated access token as the value.
|
||||
1. Create a `.circleci` directory and create a `config.yml` under that directory.
|
||||
1. Copy the text below into `.circleci/config.yml`.
|
||||
|
||||
```yaml
|
||||
# If you only want circle to run on direct commits to master, you can uncomment this out
|
||||
|
|
@ -132,11 +132,11 @@ workflows:
|
|||
# filters: *filter-only-master
|
||||
```
|
||||
|
||||
Make sure to replace all `<....>` in the `command:` sequence with appropriate values. For `<GIT_USER>`, it should be a GitHub account that has access to push documentation to your GitHub repo. Many times `<GIT_USER>` and `<GITHUB_USERNAME>` will be the same.
|
||||
Make sure to replace all `<....>` in the `command:` sequence with appropriate values. For `<GIT_USER>`, it should be a GitHub account that has access to push documentation to your GitHub repository. Many times `<GIT_USER>` and `<GITHUB_USERNAME>` will be the same.
|
||||
|
||||
**DO NOT** place the actual value of `$GITHUB_TOKEN` in `circle.yml`. We already configured that as an environment variable back in Step 3.
|
||||
|
||||
> If you want to use SSH for your GitHub repo connection, you can set `USE_SSH=true`. So the above command would look something like: `cd website && npm install && GIT_USER=<GIT_USER> USE_SSH=true npm run publish-gh-pages`.
|
||||
> If you want to use SSH for your GitHub repository connection, you can set `USE_SSH=true`. So the above command would look something like: `cd website && npm install && GIT_USER=<GIT_USER> USE_SSH=true npm run publish-gh-pages`.
|
||||
|
||||
> Unlike when you run the `publish-gh-pages` script manually, when the script runs within the Circle environment, the value of `CURRENT_BRANCH` is already defined as an [environment variable within CircleCI](https://circleci.com/docs/1.0/environment-variables/) and will be picked up by the script automatically.
|
||||
|
||||
|
|
@ -161,15 +161,15 @@ jobs:
|
|||
- run: echo "Skipping tests on gh-pages branch"
|
||||
```
|
||||
|
||||
Save this file as `config.yml` and place it in a `.circleci` folder inside your `website/static` folder.
|
||||
Save this file as `config.yml` and place it in a `.circleci` directory inside your `website/static` directory.
|
||||
|
||||
### Using Travis CI
|
||||
|
||||
1. Go to https://github.com/settings/tokens and generate a new [personal access token](https://help.github.com/articles/creating-a-personal-access-token-for-the-command-line/)
|
||||
1. Using your GitHub account, [add the Travis CI app](https://github.com/marketplace/travis-ci) to the repository you want to activate.
|
||||
1. Open your Travis CI dashboard. The URL looks like https://travis-ci.com/USERNAME/REPO, and navigate to the `More options` > `Setting` > `Environment Variables` section of your repository.
|
||||
1. Create a new environment variable named `GH_TOKEN` with your newly generated token as its value, then `GH_EMAIL` (your email address) and `GH_NAME` (your GitHub username).
|
||||
1. Create a `.travis.yml` on the root of your repository with below text.
|
||||
1. Go to https://github.com/settings/tokens and generate a new [personal access token](https://help.github.com/articles/creating-a-personal-access-token-for-the-command-line/)
|
||||
1. Using your GitHub account, [add the Travis CI app](https://github.com/marketplace/travis-ci) to the repository you want to activate.
|
||||
1. Open your Travis CI dashboard. The URL looks like https://travis-ci.com/USERNAME/REPO, and navigate to the `More options` > `Setting` > `Environment Variables` section of your repository.
|
||||
1. Create a new environment variable named `GH_TOKEN` with your newly generated token as its value, then `GH_EMAIL` (your email address) and `GH_NAME` (your GitHub username).
|
||||
1. Create a `.travis.yml` on the root of your repository with below text.
|
||||
|
||||
```yaml
|
||||
# .travis.yml
|
||||
|
|
@ -194,23 +194,24 @@ Now, whenever a new commit lands in `master`, Travis CI will run your suite of t
|
|||
|
||||
Steps to configure your Docusaurus-powered site on Netlify.
|
||||
|
||||
1. Select **New site from Git**
|
||||
1. Connect to your preferred Git provider.
|
||||
1. Select the branch to deploy. Default is `master`
|
||||
1. Configure your build steps:
|
||||
1. Select **New site from Git**
|
||||
1. Connect to your preferred Git provider.
|
||||
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`)
|
||||
|
||||
1. Click **Deploy site**
|
||||
1. Click **Deploy site**
|
||||
|
||||
You can also configure Netlify to rebuild on every commit to your repo, or only `master` branch commits.
|
||||
You can also configure Netlify to rebuild on every commit to your repository, or only `master` branch commits.
|
||||
|
||||
### Publishing to GitHub Enterprise
|
||||
|
||||
GitHub enterprise installations should work in the same manner as github.com; you only need to identify the organization's GitHub Enterprise host.
|
||||
|
||||
| Name | Description |
|
||||
| ------------- | ----------------------------------------------- |
|
||||
| `GITHUB_HOST` | The hostname for the GitHub enterprise server. |
|
||||
| Name | Description |
|
||||
| ------------- | ---------------------------------------------- |
|
||||
| `GITHUB_HOST` | The hostname for the GitHub enterprise server. |
|
||||
|
||||
Alter your `siteConfig.js` to add a property `'githubHost'` which represents the GitHub Enterprise hostname. Alternatively, set an environment variable `GITHUB_HOST` when executing the publish command.
|
||||
|
|
|
|||
|
|
@ -12,23 +12,22 @@ After [installation](getting-started-installation.md) and [preparation](getting-
|
|||
Your site structure looks like the following:
|
||||
|
||||
```bash
|
||||
root-of-repo
|
||||
root-directory
|
||||
├── docs
|
||||
├── website
|
||||
│ ├── blog
|
||||
│ ├── core
|
||||
│ │ └── Footer.js
|
||||
│ ├── node_modules
|
||||
│ ├── package.json
|
||||
│ ├── pages
|
||||
│ ├── sidebars.json
|
||||
│ ├── siteConfig.js
|
||||
│ └── static
|
||||
└── website
|
||||
├── blog
|
||||
├── core
|
||||
│ └── Footer.js
|
||||
├── package.json
|
||||
├── pages
|
||||
├── sidebars.json
|
||||
├── siteConfig.js
|
||||
└── static
|
||||
```
|
||||
|
||||
> This assumes that you removed the example `.md` files that were installed with the [initialization](getting-started-installation.md) script.
|
||||
|
||||
All of your documentation files should be placed inside the `docs` folder as markdown `.md` files. Any blog posts should be inside the `blog` folder.
|
||||
All of your documentation files should be placed inside the `docs` directory as markdown `.md` files. Any blog posts should be inside the `blog` directory.
|
||||
|
||||
> The blog posts must be formatted as `YYYY-MM-DD-your-file-name.md`
|
||||
|
||||
|
|
@ -36,7 +35,7 @@ All of your documentation files should be placed inside the `docs` folder as mar
|
|||
|
||||
To create a fully functional site, you only need to do a few steps:
|
||||
|
||||
1. Add your documentation to the `/docs` folder as `.md` files, ensuring you have the proper [header](api-doc-markdown.md#documents) in each file. The simplest header would be the following, where `id` is the link name (e.g., `docs/intro.html`) and the `title`, is, of course, the title of the browser page.
|
||||
1. Add your documentation to the `/docs` directory as `.md` files, ensuring you have the proper [header](api-doc-markdown.md#documents) in each file. The simplest header would be the following, where `id` is the link name (e.g., `docs/intro.html`) and the `title`, is, of course, the title of the browser page.
|
||||
|
||||
```yaml
|
||||
---
|
||||
|
|
@ -47,20 +46,20 @@ To create a fully functional site, you only need to do a few steps:
|
|||
My new content here..
|
||||
```
|
||||
|
||||
1. Add zero or more docs to the [`sidebars.json`](guides-navigation.md#adding-docs-to-a-sidebar) file so that your documentation is rendered in a sidebar, if you choose them to be.
|
||||
1. Add zero or more docs to the [`sidebars.json`](guides-navigation.md#adding-docs-to-a-sidebar) file so that your documentation is rendered in a sidebar, if you choose them to be.
|
||||
|
||||
> If you do not add your documentation to the `sidebars.json` file, the docs will be rendered, but they can only be linked to from other documentation and visited with the known URL.
|
||||
> If you do not add your documentation to the `sidebars.json` file, the docs will be rendered, but they can only be linked to from other documentation and visited with the known URL.
|
||||
|
||||
3. Modify the `website/siteConfig.js` file to [configure your site](api-site-config.md), following the comments included in the [docs](api-site-config.md) and the `website/siteConfig.js` to guide you.
|
||||
1. Create any [custom pages](guides-custom-pages.md#customizing-your-site-footer) and/or [customize](guides-custom-pages.md#customizing-your-site-footer) the `website/core/Footer.js` file that provides the footer for your site.
|
||||
1. Place assets, such as images, in the `website/static/` folder.
|
||||
1. Run the site to see the results of your changes.
|
||||
3. Modify the `website/siteConfig.js` file to [configure your site](api-site-config.md), following the comments included in the [docs](api-site-config.md) and the `website/siteConfig.js` to guide you.
|
||||
1. Create any [custom pages](guides-custom-pages.md#customizing-your-site-footer) and/or [customize](guides-custom-pages.md#customizing-your-site-footer) the `website/core/Footer.js` file that provides the footer for your site.
|
||||
1. Place assets, such as images, in the `website/static/` directory.
|
||||
1. Run the site to see the results of your changes.
|
||||
|
||||
```bash
|
||||
cd website
|
||||
yarn run start # or `npm run start`
|
||||
# Navigate to http://localhost:3000
|
||||
```
|
||||
```bash
|
||||
cd website
|
||||
yarn run start # or `npm run start`
|
||||
# Navigate to http://localhost:3000
|
||||
```
|
||||
|
||||
## Special Customization
|
||||
|
||||
|
|
@ -68,8 +67,8 @@ To create a fully functional site, you only need to do a few steps:
|
|||
|
||||
If you prefer to have your landing page be straight to your documentation, you can do this through a redirect.
|
||||
|
||||
1. Remove the `index.js` file from the `website/pages` directory, if it exists.
|
||||
1. Add a [custom static `index.html` page](guides-custom-pages.md#adding-static-pages) in the `website/static` folder with the following contents:
|
||||
1. Remove the `index.js` file from the `website/pages` directory, if it exists.
|
||||
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>
|
||||
|
|
|
|||
|
|
@ -5,7 +5,7 @@ title: Adding a Blog
|
|||
|
||||
## Initial Setup
|
||||
|
||||
To setup your site's blog, start by creating a `blog` folder within your repo's `website` directory.
|
||||
To setup your site's blog, start by creating a `blog` directory within your repo's `website` directory.
|
||||
|
||||
Then, add a header link to your blog within `siteConfig.js`:
|
||||
|
||||
|
|
@ -19,7 +19,7 @@ headerLinks: [
|
|||
|
||||
## Adding Posts
|
||||
|
||||
To publish in the blog, create a file within the blog folder with a formatted name of `YYYY-MM-DD-My-Blog-Post-Title.md`. The post date is extracted from the file name.
|
||||
To publish in the blog, create a file within the blog directory with a formatted name of `YYYY-MM-DD-My-Blog-Post-Title.md`. The post date is extracted from the file name.
|
||||
|
||||
For example, at `website/blog/2017-08-18-Introducing-Docusaurus.md`:
|
||||
|
||||
|
|
@ -46,7 +46,7 @@ The only required field is `title`; however, we provide options to add author in
|
|||
|
||||
## Summary Truncation
|
||||
|
||||
Use the `<!--truncate-->` marker in your blog post to represent what will be shown as the summary when viewing all blog published blog posts. Anything above `<!--truncate-->` will be part of the summary. For example:
|
||||
Use the `<!--truncate-->` marker in your blog post to represent what will be shown as the summary when viewing all published blog posts. Anything above `<!--truncate-->` will be part of the summary. For example:
|
||||
|
||||
```yaml
|
||||
---
|
||||
|
|
@ -72,12 +72,12 @@ By default, 5 recent blog posts are shown on the sidebar.
|
|||
|
||||
You can configure a specific amount of blog posts to show by adding a `blogSidebarCount` setting to your `siteConfig.js`.
|
||||
|
||||
The available options are an integer representing the number of posts you wish to show or a string with the value 'ALL'.
|
||||
The available options are an integer representing the number of posts you wish to show or a string with the value `'ALL'`.
|
||||
|
||||
Example:
|
||||
|
||||
```js
|
||||
blogSidebarCount: 'ALL'
|
||||
blogSidebarCount: 'ALL';
|
||||
```
|
||||
|
||||
## RSS Feed
|
||||
|
|
@ -98,12 +98,12 @@ You can run your Docusaurus site without a landing page and instead have your bl
|
|||
|
||||
To do this:
|
||||
|
||||
1. Create a file `index.html` in `website/static/`.
|
||||
1. Place the contents of the template below into `website/static/index.html`
|
||||
1. Customize the `<title>` of `website/static/index.html`
|
||||
1. Delete the dynamic landing page `website/pages/en/index.js`
|
||||
1. Create a file `index.html` in `website/static/`.
|
||||
1. Place the contents of the template below into `website/static/index.html`
|
||||
1. Customize the `<title>` of `website/static/index.html`
|
||||
1. Delete the dynamic landing page `website/pages/en/index.js`
|
||||
|
||||
> Now, when Docusaurus generates or builds your site, it will copy the file from `static/index.html` and place it in the site's main folder. The static file is served when a visitor arrives on your page. When the page loads it will redirect the visitor to `/blog`.
|
||||
> Now, when Docusaurus generates or builds your site, it will copy the file from `static/index.html` and place it in the site's main directory. The static file is served when a visitor arrives on your page. When the page loads it will redirect the visitor to `/blog`.
|
||||
|
||||
You can use this template:
|
||||
|
||||
|
|
|
|||
|
|
@ -16,21 +16,20 @@ You can [start](getting-started-preparation.md#verifying-installation) your loca
|
|||
Docusaurus provides some simple example pages in the `website/pages/en` directory, including `index.js`, `users.js`, and `help.js`. These are good examples to showcase how to create a custom page for Docusaurus.
|
||||
|
||||
```bash
|
||||
root-of-repo
|
||||
root-directory
|
||||
├── docs
|
||||
├── website
|
||||
│ ├── blog
|
||||
│ ├── core
|
||||
│ │ └── Footer.js
|
||||
│ ├── node_modules
|
||||
│ ├── package.json
|
||||
│ ├── pages
|
||||
│ │ ├── index.js
|
||||
│ │ ├── users.js
|
||||
│ │ └── help.js
|
||||
│ ├── sidebars.json
|
||||
│ ├── siteConfig.js
|
||||
│ └── static
|
||||
└── website
|
||||
├── blog
|
||||
├── core
|
||||
│ └── Footer.js
|
||||
├── package.json
|
||||
├── pages
|
||||
│ ├── index.js
|
||||
│ ├── users.js
|
||||
│ └── help.js
|
||||
├── sidebars.json
|
||||
├── siteConfig.js
|
||||
└── static
|
||||
```
|
||||
|
||||
Of course, you are also free to write your own pages. It is strongly suggested that you at least have an index page, but none of the pages provided are mandatory to include in your site. More information on how to use the provided components or include your own can be found [here](api-pages.md). Information on how to link to your different pages in the header navigation bar can be found [here](guides-navigation.md).
|
||||
|
|
@ -39,7 +38,7 @@ Of course, you are also free to write your own pages. It is strongly suggested t
|
|||
|
||||
## Adding Static Pages
|
||||
|
||||
Static `.html` files can also be used, but they will not include Docusaurus' header, footer, or styles by default. These can be added to the `static` folder in the same way as other [static assets](api-pages.md#using-static-assets). Alternatively, they can be placed in the `pages` folder and would be served as-is instead of being rendered from React.
|
||||
Static `.html` files can also be used, but they will not include Docusaurus' header, footer, or styles by default. These can be added to the `static` directory in the same way as other [static assets](api-pages.md#using-static-assets). Alternatively, they can be placed in the `pages` directory and would be served as-is instead of being rendered from React.
|
||||
|
||||
If you wish to use Docusaurus' stylesheet, you can access it at `${baseUrl}css/main.css`. If you wish to use separate css for these static pages, you can exclude them from being concatenated to Docusaurus' styles by adding them into the `siteConfig.separateCss` field in `siteConfig.js`.
|
||||
|
||||
|
|
@ -53,7 +52,7 @@ The example provided has three columns with a footer image on the left and Faceb
|
|||
|
||||
Some suggestions for links you may want to provide: documentation, API, Twitter, Discord, Facebook groups, Stack Overflow, GitHub, etc.
|
||||
|
||||
Your footer will automatically get applied to all pages on your site, including docs and blog posts. The sole exception to this is any static html pages you include.
|
||||
Your footer will automatically get applied to all pages on your site, including docs and blog posts. The sole exception to this is any static HTML pages you include.
|
||||
|
||||
If you do not want a footer for your site, change the `render` function of `core/Footer.js` to return `null`. e.g.,
|
||||
|
||||
|
|
|
|||
|
|
@ -5,7 +5,7 @@ title: Navigation and Sidebars
|
|||
|
||||
## Referencing Site Documents
|
||||
|
||||
If you want to reference another document in your `docs` folder (or the location you set via the [optional `customDocsPath`](https://docusaurus.io/docs/en/site-config.html#optional-fields) path site configuration option), then you just use the name of the document you want to reference.
|
||||
If you want to reference another document in your `docs` directory (or the location you set via the [optional `customDocsPath`](https://docusaurus.io/docs/en/site-config.html#optional-fields) path site configuration option), then you just use the name of the document you want to reference.
|
||||
|
||||
For example, if you are in `doc2.md` and you want to reference `doc1.md`:
|
||||
|
||||
|
|
@ -13,8 +13,6 @@ For example, if you are in `doc2.md` and you want to reference `doc1.md`:
|
|||
I am referencing a [document](doc1.md).
|
||||
```
|
||||
|
||||
> Docusaurus currently does not support documents in nested folders; only in a flat folder structure. We are looking into adding support for nested folders.
|
||||
|
||||
## How Documents are Linked
|
||||
|
||||
New markdown files within `docs` will show up as pages on the website. Links to those documents are created first by using the `id` in the header of each document. If there is no `id` field, then the name of the file will serve as the link name.
|
||||
|
|
@ -94,7 +92,7 @@ It is important to note that until you [add a document from the `"examples-sideb
|
|||
|
||||
## Additions to the Site Navigation Bar
|
||||
|
||||
To expose sidebars, you will add clickable labels to the site navigation bar at the top of the website. You can add documents, pages and external links.
|
||||
To expose sidebars, you will add click-able labels to the site navigation bar at the top of the website. You can add documents, pages and external links.
|
||||
|
||||
### Adding Documents
|
||||
|
||||
|
|
|
|||
|
|
@ -27,24 +27,23 @@ 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
|
||||
|
||||
Your documentation files (e.g., the `.md` files that live in your `docs` directory) do not need to be changed or moved to support translations. They will be uploaded to Crowdin to be translated directly.
|
||||
|
||||
|
||||
## Enabling Translations on Pages
|
||||
|
||||
Pages allow you to customize layout and specific content of pages like a custom index page or help page.
|
||||
|
||||
Pages with text that you want translated should be placed in `website/pages/en` folder.
|
||||
Pages with text that you want translated should be placed in `website/pages/en` directory.
|
||||
|
||||
Wrap strings you want translated in a `<translate>` tag, and add the following `require` statement to the top of the file:
|
||||
|
||||
|
|
@ -88,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`
|
||||
|
||||
## How Strings Get Translated
|
||||
|
||||
|
|
|
|||
|
|
@ -3,7 +3,7 @@ id: versioning
|
|||
title: Versioning
|
||||
---
|
||||
|
||||
You can use the `version` script to cut a new documentation version based on the latest content in the `docs` folder. That specific set of documentation will then be preserved and accessible even as the documentation in the `docs` folder changes moving forward.
|
||||
You can use the `version` script to cut a new documentation version based on the latest content in the `docs` directory. That specific set of documentation will then be preserved and accessible even as the documentation in the `docs` directory changes moving forward.
|
||||
|
||||
## How to Create New Versions
|
||||
|
||||
|
|
@ -33,22 +33,22 @@ Run the script with a command line argument of the version you wish to create. e
|
|||
yarn run version 1.0.0
|
||||
```
|
||||
|
||||
This will preserve all documents currently in the `docs` folder and make them available as documentation for version `1.0.0`.
|
||||
This will preserve all documents currently in the `docs` directory and make them available as documentation for version `1.0.0`.
|
||||
|
||||
If, for example, you ran the version script with `1.0.0` as the version number, version `1.0.0` is considered the latest release version for your project. The site will display the version number next to the title in the header. This version number links to a versions page that you created earlier.
|
||||
|
||||
Documents in the `docs` folder will be considered part of version `next` and they are available, for example, at the url `docs/next/doc1.html`. Documents from the latest version use the url `docs/doc1.html`.
|
||||
Documents in the `docs` directory will be considered part of version `next` and they are available, for example, at the URL `docs/next/doc1.html`. Documents from the latest version use the URL `docs/doc1.html`.
|
||||
|
||||
Running the script again with `yarn run version 2.0.0` will create a version `2.0.0`, making version `2.0.0` the most recent set of documentation. Documents from version `1.0.0` will use the url `docs/1.0.0/doc1.html` while `2.0.0` will use `docs/doc1.html`.
|
||||
Running the script again with `yarn run version 2.0.0` will create a version `2.0.0`, making version `2.0.0` the most recent set of documentation. Documents from version `1.0.0` will use the URL `docs/1.0.0/doc1.html` while `2.0.0` will use `docs/doc1.html`.
|
||||
|
||||
This table below summarizes Docusaurus versioning at a glance:
|
||||
|
||||
| Version | Tag | URL
|
||||
| --- | --- | --- |
|
||||
| 1.0.0 | 1.0.0 | docs/1.0.0/doc1.html |
|
||||
| 1.0.1 | 1.0.1 | docs/1.0.1/doc1.html |
|
||||
| 2.0.0 | current | docs/doc1.html |
|
||||
| `master` branch | next | docs/next/doc1.html |
|
||||
| Version | Tag | URL |
|
||||
| --------------- | ------- | -------------------- |
|
||||
| 1.0.0 | 1.0.0 | docs/1.0.0/doc1.html |
|
||||
| 1.0.1 | 1.0.1 | docs/1.0.1/doc1.html |
|
||||
| 2.0.0 | current | docs/doc1.html |
|
||||
| `master` branch | next | docs/next/doc1.html |
|
||||
|
||||
## Versioning Patterns
|
||||
|
||||
|
|
@ -68,9 +68,9 @@ If you wish to change the documentation for a past version, you can access the f
|
|||
|
||||
## Fallback Functionality
|
||||
|
||||
Only files in the `docs` folder and sidebar files that differ from those of the latest version will get copied each time a new version is specified. If there is no change across versions, Docusaurus will use the file from the latest version with that file.
|
||||
Only files in the `docs` directory and sidebar files that differ from those of the latest version will get copied each time a new version is specified. If there is no change across versions, Docusaurus will use the file from the latest version with that file.
|
||||
|
||||
For example, a document with the original id `doc1` exists for the latest version, `1.0.0`, and has the same content as the document with the id `doc1` in the `docs` folder. When a new version `2.0.0` is created, the file for `doc1` will not be copied into `versioned_docs/version-2.0.0/`. There will still be a page for `docs/2.0.0/doc1.html`, but it will use the file from version `1.0.0`.
|
||||
For example, a document with the original id `doc1` exists for the latest version, `1.0.0`, and has the same content as the document with the id `doc1` in the `docs` directory. When a new version `2.0.0` is created, the file for `doc1` will not be copied into `versioned_docs/version-2.0.0/`. There will still be a page for `docs/2.0.0/doc1.html`, but it will use the file from version `1.0.0`.
|
||||
|
||||
## Renaming Existing Versions
|
||||
|
||||
|
|
@ -92,4 +92,4 @@ yarn run rename-version 1.0.0 1.0.1
|
|||
|
||||
## Versioning and Translations
|
||||
|
||||
If you wish to use versioning and translations features, the `crowdin.yaml` file should be set up to upload and download versioned documents to and from Crowdin for translation. Translated, versioned files will go into the folder `translated_docs/${language}/version-${version}/`. For more information, check out the [translations guide](guides-translation.md).
|
||||
If you wish to use versioning and translations features, the `crowdin.yaml` file should be set up to upload and download versioned documents to and from Crowdin for translation. Translated, versioned files will go into the directory `translated_docs/${language}/version-${version}/`. For more information, check out the [translations guide](guides-translation.md).
|
||||
|
|
|
|||
Loading…
Add table
Reference in a new issue