mirror of
https://github.com/facebook/docusaurus.git
synced 2025-08-06 10:20:09 +02:00
docs(v1): remove exclusive language (#1961)
* Initial commit to replace easy, easily, simple, just, of course * Revert ordered list change
This commit is contained in:
parent
f1180d0eb6
commit
b027db1b34
43 changed files with 56 additions and 56 deletions
4
.github/ISSUE_TEMPLATE/bug.md
vendored
4
.github/ISSUE_TEMPLATE/bug.md
vendored
|
@ -24,7 +24,7 @@ about: Submit a bug report to help us improve
|
||||||
<!--
|
<!--
|
||||||
How did you expect your project to behave?
|
How did you expect your project to behave?
|
||||||
It’s fine if you’re not sure your understanding is correct.
|
It’s fine if you’re not sure your understanding is correct.
|
||||||
Just write down what you thought would happen.
|
Write down what you thought would happen.
|
||||||
-->
|
-->
|
||||||
|
|
||||||
(Write what you thought would happen.)
|
(Write what you thought would happen.)
|
||||||
|
@ -35,7 +35,7 @@ about: Submit a bug report to help us improve
|
||||||
Did something go wrong?
|
Did something go wrong?
|
||||||
Is something broken, or not behaving as you expected?
|
Is something broken, or not behaving as you expected?
|
||||||
Describe this section in detail, and attach screenshots if possible.
|
Describe this section in detail, and attach screenshots if possible.
|
||||||
Don't just say "it doesn't work"!
|
Don't only say "it doesn't work"!
|
||||||
-->
|
-->
|
||||||
|
|
||||||
(Write what happened. Add screenshots, if applicable.)
|
(Write what happened. Add screenshots, if applicable.)
|
||||||
|
|
2
.github/ISSUE_TEMPLATE/feature.md
vendored
2
.github/ISSUE_TEMPLATE/feature.md
vendored
|
@ -5,7 +5,7 @@ about: Submit a proposal/request for a new feature
|
||||||
|
|
||||||
<!--
|
<!--
|
||||||
Consider requesting the feature on https://docusaurus-2.netlify.com/feedback/ instead.
|
Consider requesting the feature on https://docusaurus-2.netlify.com/feedback/ instead.
|
||||||
Feature requests on v1 will not be accepted easily as we're focusing on building v2.
|
Feature requests on v1 are more likely to be missed as we're focusing on building v2.
|
||||||
-->
|
-->
|
||||||
|
|
||||||
## 🚀 Feature
|
## 🚀 Feature
|
||||||
|
|
2
.github/ISSUE_TEMPLATE/proposal.md
vendored
2
.github/ISSUE_TEMPLATE/proposal.md
vendored
|
@ -5,7 +5,7 @@ about: Propose a non-trivial change to Docusaurus
|
||||||
|
|
||||||
<!--
|
<!--
|
||||||
Consider requesting the feature on https://docusaurus-2.netlify.com/feedback/ instead.
|
Consider requesting the feature on https://docusaurus-2.netlify.com/feedback/ instead.
|
||||||
Feature requests on v1 will not be accepted easily as we're focusing on building v2.
|
Feature requests on v1 are more likely to be missed as we're focusing on building v2.
|
||||||
-->
|
-->
|
||||||
|
|
||||||
## 💥 Proposal
|
## 💥 Proposal
|
||||||
|
|
|
@ -69,7 +69,7 @@
|
||||||
|
|
||||||
### Features
|
### Features
|
||||||
|
|
||||||
- Add `<Redirect>` component for easy client side redirect. Example Usage:
|
- Add `<Redirect>` component for client side redirect. Example Usage:
|
||||||
```js
|
```js
|
||||||
import React from 'react';
|
import React from 'react';
|
||||||
import {Redirect} from '@docusaurus/router';
|
import {Redirect} from '@docusaurus/router';
|
||||||
|
|
|
@ -162,7 +162,7 @@ In order to accept your pull request, we need you to submit a CLA. You only need
|
||||||
|
|
||||||
### What Happens Next?
|
### What Happens Next?
|
||||||
|
|
||||||
The core Docusaurus team will be monitoring for pull requests. Do help us by making your pull request easy to review by following the guidelines above.
|
The core Docusaurus team will be monitoring for pull requests. Do help us by keeping pull requests consistent by following the guidelines above.
|
||||||
|
|
||||||
## Style Guide
|
## Style Guide
|
||||||
|
|
||||||
|
|
|
@ -43,7 +43,7 @@ Read our [contributing guide](https://github.com/facebook/docusaurus/blob/master
|
||||||
|
|
||||||
### Beginner Friendly Bugs
|
### Beginner Friendly Bugs
|
||||||
|
|
||||||
To help you get your feet wet and get you familiar with our contribution process, we have a list of [beginner friendly bugs](https://github.com/facebook/docusaurus/labels/good%20first%20issue) that contain bugs which are fairly easy to fix. This is a great place to get started.
|
To help you get your feet wet and get you familiar with our contribution process, we have a list of [beginner friendly bugs](https://github.com/facebook/docusaurus/labels/good%20first%20issue) that might contain smaller issues to tackle first. This is a great place to get started.
|
||||||
|
|
||||||
## Contact
|
## Contact
|
||||||
|
|
||||||
|
|
|
@ -20,7 +20,7 @@ Let's talk a bit more about what is done as part of the parsing stage. The resul
|
||||||
|
|
||||||
#### Inline tokens
|
#### Inline tokens
|
||||||
|
|
||||||
Inline tokens are simple tokens that have text as a child. They are leaf nodes, and do not support having additional tokens within. An example of this might be `_emphasized text_`, which might be represented as a token of type `em` with contents of `emphasized text`.
|
Inline tokens are tokens that have text as a child. They are leaf nodes, and do not support having additional tokens within. An example of this might be `_emphasized text_`, which might be represented as a token of type `em` with contents of `emphasized text`.
|
||||||
|
|
||||||
#### Block tokens
|
#### Block tokens
|
||||||
|
|
||||||
|
@ -36,7 +36,7 @@ The plain markdown text above would be parsed into three tokens:
|
||||||
- `text`: Plain text token, with a value of "Hi there".
|
- `text`: Plain text token, with a value of "Hi there".
|
||||||
- `heading_close`: Marks the end of the heading. In this case, it would also have a `hLevel: 3` prop.
|
- `heading_close`: Marks the end of the heading. In this case, it would also have a `hLevel: 3` prop.
|
||||||
|
|
||||||
This is a basic example, because it contains a simple `text` token within the opening and closing tags. A common block encountered in markdown is the paragraph, which might be tokenized into a series of tokens such as `paragraph_open`, one or more `text` tokens, `link` tokens (if links are present within the text, for example), and, eventually, a `paragraph_close` token.
|
This is a basic example, because it contains a `text` token within the opening and closing tags. A common block encountered in markdown is the paragraph, which might be tokenized into a series of tokens such as `paragraph_open`, one or more `text` tokens, `link` tokens (if links are present within the text, for example), and, eventually, a `paragraph_close` token.
|
||||||
|
|
||||||
#### Core tokens
|
#### Core tokens
|
||||||
|
|
||||||
|
@ -48,7 +48,7 @@ After we have parsed everything into tokens, we go to the rendering phase. This
|
||||||
|
|
||||||
## Creating a Remarkable Extension
|
## Creating a Remarkable Extension
|
||||||
|
|
||||||
Now that you have a better idea of how parsing/rendering works, we can proceed to create a simple extension that renders heading anchors. First we need to determine if we need to extend the parser, or the renderer. In this case, we're only interested in changing how a heading is rendered to HTML, so we'll just need to override the heading renderers.
|
Now that you have a better idea of how parsing/rendering works, we can proceed to create an extension that renders heading anchors. First we need to determine if we need to extend the parser, or the renderer. In this case, we're only interested in changing how a heading is rendered to HTML, so we'll just need to override the heading renderers.
|
||||||
|
|
||||||
The default heading renderers may look like this (you can refer to the Remarkable source code here):
|
The default heading renderers may look like this (you can refer to the Remarkable source code here):
|
||||||
|
|
||||||
|
|
|
@ -221,4 +221,4 @@ There are several ways to access the default styles provided for your site. If y
|
||||||
|
|
||||||
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.
|
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.
|
One 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,7 +27,7 @@ Color configurations for the site.
|
||||||
|
|
||||||
- `primaryColor` is the color used the header navigation bar and sidebars.
|
- `primaryColor` is the color used the header navigation bar and sidebars.
|
||||||
- `secondaryColor` is the color seen in the second row of the header navigation bar when the site window is narrow (including on mobile).
|
- `secondaryColor` is the color seen in the second row of the header navigation bar when the site window is narrow (including on mobile).
|
||||||
- Custom color configurations can also be added. For example, if user styles are added with colors specified as `$myColor`, then adding a `myColor` field to `colors` will allow you to easily configure this color.
|
- Custom color configurations can also be added. For example, if user styles are added with colors specified as `$myColor`, then adding a `myColor` field to `colors` will allow you to configure this color.
|
||||||
|
|
||||||
#### `copyright` [string]
|
#### `copyright` [string]
|
||||||
|
|
||||||
|
|
|
@ -8,7 +8,7 @@ Docusaurus was designed from the ground up to be easily installed and used to ge
|
||||||
|
|
||||||
## Installing Docusaurus
|
## Installing Docusaurus
|
||||||
|
|
||||||
We have created an easy script that will get all of the infrastructure set up for you:
|
We have created a helpful 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.
|
||||||
|
|
||||||
|
|
|
@ -194,7 +194,7 @@ Now, whenever a new commit lands in `master`, CircleCI will run your suite of te
|
||||||
|
|
||||||
When initially deploying to a `gh-pages` branch using CircleCI, you may notice that some jobs triggered by commits to the `gh-pages` branch fail to run successfully due to a lack of tests (This can also result in chat/slack build failure notifications).
|
When initially deploying to a `gh-pages` branch using CircleCI, you may notice that some jobs triggered by commits to the `gh-pages` branch fail to run successfully due to a lack of tests (This can also result in chat/slack build failure notifications).
|
||||||
|
|
||||||
You can work around this easily by:
|
You can work around this by:
|
||||||
- Setting the environment variable `CUSTOM_COMMIT_MESSAGE` flag to the `publish-gh-pages` command with the contents of `[skip ci]`.
|
- Setting the environment variable `CUSTOM_COMMIT_MESSAGE` flag to the `publish-gh-pages` command with the contents of `[skip ci]`.
|
||||||
e.g.
|
e.g.
|
||||||
```bash
|
```bash
|
||||||
|
@ -247,7 +247,7 @@ Now, whenever a new commit lands in `master`, Travis CI will run your suite of t
|
||||||
|
|
||||||
### Hosting on ZEIT Now
|
### Hosting on ZEIT Now
|
||||||
|
|
||||||
With [ZEIT Now](#using-zeit-now), you can deploy your site easily and connect it to [GitHub](https://zeit.co/github) or [GitLab](https://zeit.co/gitlab) to automatically receive a new deployment every time you push a commit.
|
With [ZEIT Now](#using-zeit-now), you can deploy your site and connect it to [GitHub](https://zeit.co/github) or [GitLab](https://zeit.co/gitlab) to automatically receive a new deployment every time you push a commit.
|
||||||
|
|
||||||
### Hosting on Netlify
|
### Hosting on Netlify
|
||||||
|
|
||||||
|
|
|
@ -35,7 +35,7 @@ All of your documentation files should be placed inside the `docs` directory as
|
||||||
|
|
||||||
To create a fully functional site, you only need to do a few steps:
|
To create a fully functional site, you only need to do a few steps:
|
||||||
|
|
||||||
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 the webpage's title.
|
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. One example header would be the following, where `id` is the link name (e.g., `docs/intro.html`) and the `title` is the webpage's title.
|
||||||
|
|
||||||
```yaml
|
```yaml
|
||||||
---
|
---
|
||||||
|
|
|
@ -94,7 +94,7 @@ blogSidebarTitle: { default: 'Recent posts', all: 'All blog posts' },
|
||||||
|
|
||||||
## RSS Feed
|
## RSS Feed
|
||||||
|
|
||||||
Docusaurus provides a simple RSS feed for your blog posts. Both RSS and Atom feed formats are supported. This data is automatically added to your website page's HTML `<HEAD>` tag.
|
Docusaurus provides an RSS feed for your blog posts. Both RSS and Atom feed formats are supported. This data is automatically added to your website page's HTML `<HEAD>` tag.
|
||||||
|
|
||||||
A summary of the post's text is provided in the RSS feed up to the `<!--truncate-->`. If no `<!--truncate-->` tag is found, then all text up to 250 characters is used.
|
A summary of the post's text is provided in the RSS feed up to the `<!--truncate-->`. If no `<!--truncate-->` tag is found, then all text up to 250 characters is used.
|
||||||
|
|
||||||
|
|
|
@ -13,7 +13,7 @@ You can [start](getting-started-preparation.md#verifying-installation) your loca
|
||||||
|
|
||||||
## Adding Other Custom Pages
|
## Adding Other Custom Pages
|
||||||
|
|
||||||
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.
|
Docusaurus provides some helpful 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
|
```bash
|
||||||
root-directory
|
root-directory
|
||||||
|
@ -33,7 +33,7 @@ root-directory
|
||||||
└── static
|
└── 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).
|
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).
|
||||||
|
|
||||||
> If you want your page to show up in your navigation header, you will need to update `siteConfig.js` to add to the `headerLinks` element. e.g., `{ page: 'about-slash', label: 'About/' }`,
|
> If you want your page to show up in your navigation header, you will need to update `siteConfig.js` to add to the `headerLinks` element. e.g., `{ page: 'about-slash', label: 'About/' }`,
|
||||||
|
|
||||||
|
|
|
@ -262,7 +262,7 @@ These are two separate class names so you can have the active styles applied to
|
||||||
|
|
||||||
## Secondary On-Page Navigation
|
## Secondary On-Page Navigation
|
||||||
|
|
||||||
We support secondary on-page navigation so you can more easily see the topics associated with a given document. To enable this feature, you need to add the `onPageNav` site configuration [option](api-site-config.md#optional-fields) to your `siteConfig.js`.
|
We support secondary on-page navigation so you can quickly see the topics associated with a given document. To enable this feature, you need to add the `onPageNav` site configuration [option](api-site-config.md#optional-fields) to your `siteConfig.js`.
|
||||||
|
|
||||||
```js
|
```js
|
||||||
{
|
{
|
||||||
|
|
|
@ -3,7 +3,7 @@ id: translation
|
||||||
title: Translations & Localization
|
title: Translations & Localization
|
||||||
---
|
---
|
||||||
|
|
||||||
Docusaurus allows for easy translation functionality using [Crowdin](https://crowdin.com/). Documentation files written in English are uploaded to Crowdin for translation by users within a community. Top-level pages written with English strings can be translated by wrapping any strings you want to translate in a `<translate>` tag. Other titles and labels will also be found and properly translated.
|
Docusaurus allows for useful translation functionality using [Crowdin](https://crowdin.com/). Documentation files written in English are uploaded to Crowdin for translation by users within a community. Top-level pages written with English strings can be translated by wrapping any strings you want to translate in a `<translate>` tag. Other titles and labels will also be found and properly translated.
|
||||||
|
|
||||||
## Docusaurus Translation Configurations
|
## Docusaurus Translation Configurations
|
||||||
|
|
||||||
|
|
|
@ -43,7 +43,7 @@ Read our [contributing guide](https://github.com/facebook/docusaurus/blob/master
|
||||||
|
|
||||||
### Beginner Friendly Bugs
|
### Beginner Friendly Bugs
|
||||||
|
|
||||||
To help you get your feet wet and get you familiar with our contribution process, we have a list of [beginner friendly bugs](https://github.com/facebook/docusaurus/labels/good%20first%20issue) that contain bugs which are fairly easy to fix. This is a great place to get started.
|
To help you get your feet wet and get you familiar with our contribution process, we have a list of [beginner friendly bugs](https://github.com/facebook/docusaurus/labels/good%20first%20issue) that might contain smaller issues to tackle first. This is a great place to get started.
|
||||||
|
|
||||||
## Contact
|
## Contact
|
||||||
|
|
||||||
|
|
|
@ -222,4 +222,4 @@ There are several ways to access the default styles provided for your site. If y
|
||||||
|
|
||||||
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.
|
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.
|
One 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.
|
||||||
|
|
|
@ -28,7 +28,7 @@ Color configurations for the site.
|
||||||
|
|
||||||
- `primaryColor` is the color used the header navigation bar and sidebars.
|
- `primaryColor` is the color used the header navigation bar and sidebars.
|
||||||
- `secondaryColor` is the color seen in the second row of the header navigation bar when the site window is narrow (including on mobile).
|
- `secondaryColor` is the color seen in the second row of the header navigation bar when the site window is narrow (including on mobile).
|
||||||
- Custom color configurations can also be added. For example, if user styles are added with colors specified as `$myColor`, then adding a `myColor` field to `colors` will allow you to easily configure this color.
|
- Custom color configurations can also be added. For example, if user styles are added with colors specified as `$myColor`, then adding a `myColor` field to `colors` will allow you to configure this color.
|
||||||
|
|
||||||
#### `copyright` [string]
|
#### `copyright` [string]
|
||||||
|
|
||||||
|
|
|
@ -188,7 +188,7 @@ Now, whenever a new commit lands in `master`, CircleCI will run your suite of te
|
||||||
|
|
||||||
When initially deploying to a `gh-pages` branch using CircleCI, you may notice that some jobs triggered by commits to the `gh-pages` branch fail to run successfully due to a lack of tests (This can also result in chat/slack build failure notifications).
|
When initially deploying to a `gh-pages` branch using CircleCI, you may notice that some jobs triggered by commits to the `gh-pages` branch fail to run successfully due to a lack of tests (This can also result in chat/slack build failure notifications).
|
||||||
|
|
||||||
You can work around this easily by:
|
You can work around this by:
|
||||||
- Setting the environment variable `CUSTOM_COMMIT_MESSAGE` flag to the `publish-gh-pages` command with the contents of `[skip ci]`.
|
- Setting the environment variable `CUSTOM_COMMIT_MESSAGE` flag to the `publish-gh-pages` command with the contents of `[skip ci]`.
|
||||||
e.g.
|
e.g.
|
||||||
```bash
|
```bash
|
||||||
|
@ -241,7 +241,7 @@ Now, whenever a new commit lands in `master`, Travis CI will run your suite of t
|
||||||
|
|
||||||
### Hosting on ZEIT Now
|
### Hosting on ZEIT Now
|
||||||
|
|
||||||
With [ZEIT Now](#using-zeit-now), you can deploy your site easily and connect it to [GitHub](https://zeit.co/github) or [GitLab](https://zeit.co/gitlab) to automatically receive a new deployment every time you push a commit.
|
With [ZEIT Now](#using-zeit-now), you can deploy your site and connect it to [GitHub](https://zeit.co/github) or [GitLab](https://zeit.co/gitlab) to automatically receive a new deployment every time you push a commit.
|
||||||
|
|
||||||
### Hosting on Netlify
|
### Hosting on Netlify
|
||||||
|
|
||||||
|
|
|
@ -36,7 +36,7 @@ All of your documentation files should be placed inside the `docs` directory as
|
||||||
|
|
||||||
To create a fully functional site, you only need to do a few steps:
|
To create a fully functional site, you only need to do a few steps:
|
||||||
|
|
||||||
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 the webpage's title.
|
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. One example header would be the following, where `id` is the link name (e.g., `docs/intro.html`) and the `title` is the webpage's title.
|
||||||
|
|
||||||
```yaml
|
```yaml
|
||||||
---
|
---
|
||||||
|
|
|
@ -14,7 +14,7 @@ You can [start](getting-started-preparation.md#verifying-installation) your loca
|
||||||
|
|
||||||
## Adding Other Custom Pages
|
## Adding Other Custom Pages
|
||||||
|
|
||||||
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.
|
Docusaurus provides some helpful 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
|
```bash
|
||||||
root-directory
|
root-directory
|
||||||
|
@ -33,7 +33,7 @@ root-directory
|
||||||
└── static
|
└── 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).
|
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).
|
||||||
|
|
||||||
> If you want your page to show up in your navigation header, you will need to update `siteConfig.js` to add to the `headerLinks` element. e.g., `{ page: 'about-slash', label: 'About/' }`,
|
> If you want your page to show up in your navigation header, you will need to update `siteConfig.js` to add to the `headerLinks` element. e.g., `{ page: 'about-slash', label: 'About/' }`,
|
||||||
|
|
||||||
|
|
|
@ -263,7 +263,7 @@ These are two separate class names so you can have the active styles applied to
|
||||||
|
|
||||||
## Secondary On-Page Navigation
|
## Secondary On-Page Navigation
|
||||||
|
|
||||||
We support secondary on-page navigation so you can more easily see the topics associated with a given document. To enable this feature, you need to add the `onPageNav` site configuration [option](api-site-config.md#optional-fields) to your `siteConfig.js`.
|
We support secondary on-page navigation so you can quickly see the topics associated with a given document. To enable this feature, you need to add the `onPageNav` site configuration [option](api-site-config.md#optional-fields) to your `siteConfig.js`.
|
||||||
|
|
||||||
```js
|
```js
|
||||||
{
|
{
|
||||||
|
|
|
@ -28,7 +28,7 @@ Color configurations for the site.
|
||||||
|
|
||||||
- `primaryColor` is the color used the header navigation bar and sidebars.
|
- `primaryColor` is the color used the header navigation bar and sidebars.
|
||||||
- `secondaryColor` is the color seen in the second row of the header navigation bar when the site window is narrow (including on mobile).
|
- `secondaryColor` is the color seen in the second row of the header navigation bar when the site window is narrow (including on mobile).
|
||||||
- Custom color configurations can also be added. For example, if user styles are added with colors specified as `$myColor`, then adding a `myColor` field to `colors` will allow you to easily configure this color.
|
- Custom color configurations can also be added. For example, if user styles are added with colors specified as `$myColor`, then adding a `myColor` field to `colors` will allow you to configure this color.
|
||||||
|
|
||||||
#### `copyright` [string]
|
#### `copyright` [string]
|
||||||
|
|
||||||
|
|
|
@ -95,7 +95,7 @@ blogSidebarTitle: { default: 'Recent posts', all: 'All blog posts' },
|
||||||
|
|
||||||
## RSS Feed
|
## RSS Feed
|
||||||
|
|
||||||
Docusaurus provides a simple RSS feed for your blog posts. Both RSS and Atom feed formats are supported. This data is automatically added to your website page's HTML `<HEAD>` tag.
|
Docusaurus provides an RSS feed for your blog posts. Both RSS and Atom feed formats are supported. This data is automatically added to your website page's HTML `<HEAD>` tag.
|
||||||
|
|
||||||
A summary of the post's text is provided in the RSS feed up to the `<!--truncate-->`. If no `<!--truncate-->` tag is found, then all text up 250 characters are used.
|
A summary of the post's text is provided in the RSS feed up to the `<!--truncate-->`. If no `<!--truncate-->` tag is found, then all text up 250 characters are used.
|
||||||
|
|
||||||
|
|
|
@ -14,7 +14,7 @@ You can [start](getting-started-preparation.md#verifying-installation) your loca
|
||||||
|
|
||||||
## Adding Other Custom Pages
|
## Adding Other Custom Pages
|
||||||
|
|
||||||
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.
|
Docusaurus provides some helpful 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
|
```bash
|
||||||
root-directory
|
root-directory
|
||||||
|
@ -34,7 +34,7 @@ root-directory
|
||||||
└── static
|
└── 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).
|
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).
|
||||||
|
|
||||||
> If you want your page to show up in your navigation header, you will need to update `siteConfig.js` to add to the `headerLinks` element. e.g., `{ page: 'about-slash', label: 'About/' }`,
|
> If you want your page to show up in your navigation header, you will need to update `siteConfig.js` to add to the `headerLinks` element. e.g., `{ page: 'about-slash', label: 'About/' }`,
|
||||||
|
|
||||||
|
|
|
@ -189,7 +189,7 @@ Now, whenever a new commit lands in `master`, CircleCI will run your suite of te
|
||||||
|
|
||||||
When initially deploying to a `gh-pages` branch using CircleCI, you may notice that some jobs triggered by commits to the `gh-pages` branch fail to run successfully due to a lack of tests (This can also result in chat/slack build failure notifications).
|
When initially deploying to a `gh-pages` branch using CircleCI, you may notice that some jobs triggered by commits to the `gh-pages` branch fail to run successfully due to a lack of tests (This can also result in chat/slack build failure notifications).
|
||||||
|
|
||||||
You can work around this easily by:
|
You can work around this by:
|
||||||
- Setting the environment variable `CUSTOM_COMMIT_MESSAGE` flag to the `publish-gh-pages` command with the contents of `[skip ci]`.
|
- Setting the environment variable `CUSTOM_COMMIT_MESSAGE` flag to the `publish-gh-pages` command with the contents of `[skip ci]`.
|
||||||
e.g.
|
e.g.
|
||||||
```bash
|
```bash
|
||||||
|
@ -242,7 +242,7 @@ Now, whenever a new commit lands in `master`, Travis CI will run your suite of t
|
||||||
|
|
||||||
### Hosting on ZEIT Now
|
### Hosting on ZEIT Now
|
||||||
|
|
||||||
With [ZEIT Now](#using-zeit-now), you can deploy your site easily and connect it to [GitHub](https://zeit.co/github) or [GitLab](https://zeit.co/gitlab) to automatically receive a new deployment every time you push a commit.
|
With [ZEIT Now](#using-zeit-now), you can deploy your site and connect it to [GitHub](https://zeit.co/github) or [GitLab](https://zeit.co/gitlab) to automatically receive a new deployment every time you push a commit.
|
||||||
|
|
||||||
### Hosting on Netlify
|
### Hosting on Netlify
|
||||||
|
|
||||||
|
|
|
@ -95,7 +95,7 @@ blogSidebarTitle: { default: 'Recent posts', all: 'All blog posts' },
|
||||||
|
|
||||||
## RSS Feed
|
## RSS Feed
|
||||||
|
|
||||||
Docusaurus provides a simple RSS feed for your blog posts. Both RSS and Atom feed formats are supported. This data is automatically added to your website page's HTML `<HEAD>` tag.
|
Docusaurus provides an RSS feed for your blog posts. Both RSS and Atom feed formats are supported. This data is automatically added to your website page's HTML `<HEAD>` tag.
|
||||||
|
|
||||||
A summary of the post's text is provided in the RSS feed up to the `<!--truncate-->`. If no `<!--truncate-->` tag is found, then all text up to 250 characters is used.
|
A summary of the post's text is provided in the RSS feed up to the `<!--truncate-->`. If no `<!--truncate-->` tag is found, then all text up to 250 characters is used.
|
||||||
|
|
||||||
|
|
|
@ -28,7 +28,7 @@ Color configurations for the site.
|
||||||
|
|
||||||
- `primaryColor` is the color used the header navigation bar and sidebars.
|
- `primaryColor` is the color used the header navigation bar and sidebars.
|
||||||
- `secondaryColor` is the color seen in the second row of the header navigation bar when the site window is narrow (including on mobile).
|
- `secondaryColor` is the color seen in the second row of the header navigation bar when the site window is narrow (including on mobile).
|
||||||
- Custom color configurations can also be added. For example, if user styles are added with colors specified as `$myColor`, then adding a `myColor` field to `colors` will allow you to easily configure this color.
|
- Custom color configurations can also be added. For example, if user styles are added with colors specified as `$myColor`, then adding a `myColor` field to `colors` will allow you to configure this color.
|
||||||
|
|
||||||
#### `copyright` [string]
|
#### `copyright` [string]
|
||||||
|
|
||||||
|
|
|
@ -28,7 +28,7 @@ Color configurations for the site.
|
||||||
|
|
||||||
- `primaryColor` is the color used the header navigation bar and sidebars.
|
- `primaryColor` is the color used the header navigation bar and sidebars.
|
||||||
- `secondaryColor` is the color seen in the second row of the header navigation bar when the site window is narrow (including on mobile).
|
- `secondaryColor` is the color seen in the second row of the header navigation bar when the site window is narrow (including on mobile).
|
||||||
- Custom color configurations can also be added. For example, if user styles are added with colors specified as `$myColor`, then adding a `myColor` field to `colors` will allow you to easily configure this color.
|
- Custom color configurations can also be added. For example, if user styles are added with colors specified as `$myColor`, then adding a `myColor` field to `colors` will allow you to configure this color.
|
||||||
|
|
||||||
#### `copyright` [string]
|
#### `copyright` [string]
|
||||||
|
|
||||||
|
|
|
@ -222,4 +222,4 @@ There are several ways to access the default styles provided for your site. If y
|
||||||
|
|
||||||
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.
|
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.
|
One 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.
|
||||||
|
|
|
@ -28,7 +28,7 @@ Color configurations for the site.
|
||||||
|
|
||||||
- `primaryColor` is the color used the header navigation bar and sidebars.
|
- `primaryColor` is the color used the header navigation bar and sidebars.
|
||||||
- `secondaryColor` is the color seen in the second row of the header navigation bar when the site window is narrow (including on mobile).
|
- `secondaryColor` is the color seen in the second row of the header navigation bar when the site window is narrow (including on mobile).
|
||||||
- Custom color configurations can also be added. For example, if user styles are added with colors specified as `$myColor`, then adding a `myColor` field to `colors` will allow you to easily configure this color.
|
- Custom color configurations can also be added. For example, if user styles are added with colors specified as `$myColor`, then adding a `myColor` field to `colors` will allow you to configure this color.
|
||||||
|
|
||||||
#### `copyright` [string]
|
#### `copyright` [string]
|
||||||
|
|
||||||
|
|
|
@ -188,7 +188,7 @@ Now, whenever a new commit lands in `master`, CircleCI will run your suite of te
|
||||||
|
|
||||||
When initially deploying to a `gh-pages` branch using CircleCI, you may notice that some jobs triggered by commits to the `gh-pages` branch fail to run successfully due to a lack of tests (This can also result in chat/slack build failure notifications).
|
When initially deploying to a `gh-pages` branch using CircleCI, you may notice that some jobs triggered by commits to the `gh-pages` branch fail to run successfully due to a lack of tests (This can also result in chat/slack build failure notifications).
|
||||||
|
|
||||||
You can work around this easily by:
|
You can work around this by:
|
||||||
- Setting the environment variable `CUSTOM_COMMIT_MESSAGE` flag to the `publish-gh-pages` command with the contents of `[skip ci]`.
|
- Setting the environment variable `CUSTOM_COMMIT_MESSAGE` flag to the `publish-gh-pages` command with the contents of `[skip ci]`.
|
||||||
e.g.
|
e.g.
|
||||||
```bash
|
```bash
|
||||||
|
@ -241,7 +241,7 @@ Now, whenever a new commit lands in `master`, Travis CI will run your suite of t
|
||||||
|
|
||||||
### Hosting on ZEIT Now
|
### Hosting on ZEIT Now
|
||||||
|
|
||||||
With [ZEIT Now](#using-zeit-now), you can deploy your site easily and connect it to [GitHub](https://zeit.co/github) or [GitLab](https://zeit.co/gitlab) to automatically receive a new deployment every time you push a commit.
|
With [ZEIT Now](#using-zeit-now), you can deploy your site and connect it to [GitHub](https://zeit.co/github) or [GitLab](https://zeit.co/gitlab) to automatically receive a new deployment every time you push a commit.
|
||||||
|
|
||||||
### Hosting on Netlify
|
### Hosting on Netlify
|
||||||
|
|
||||||
|
|
|
@ -36,7 +36,7 @@ All of your documentation files should be placed inside the `docs` directory as
|
||||||
|
|
||||||
To create a fully functional site, you only need to do a few steps:
|
To create a fully functional site, you only need to do a few steps:
|
||||||
|
|
||||||
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 the webpage's title.
|
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. One example header would be the following, where `id` is the link name (e.g., `docs/intro.html`) and the `title` is the webpage's title.
|
||||||
|
|
||||||
```yaml
|
```yaml
|
||||||
---
|
---
|
||||||
|
|
|
@ -95,7 +95,7 @@ blogSidebarTitle: { default: 'Recent posts', all: 'All blog posts' },
|
||||||
|
|
||||||
## RSS Feed
|
## RSS Feed
|
||||||
|
|
||||||
Docusaurus provides a simple RSS feed for your blog posts. Both RSS and Atom feed formats are supported. This data is automatically to your website page's HTML `<HEAD>` tag.
|
Docusaurus provides an RSS feed for your blog posts. Both RSS and Atom feed formats are supported. This data is automatically to your website page's HTML `<HEAD>` tag.
|
||||||
|
|
||||||
A summary of the post's text is provided in the RSS feed up to the `<!--truncate-->`. If no `<!--truncate-->` tag is found, then all text up 250 characters are used.
|
A summary of the post's text is provided in the RSS feed up to the `<!--truncate-->`. If no `<!--truncate-->` tag is found, then all text up 250 characters are used.
|
||||||
|
|
||||||
|
|
|
@ -14,7 +14,7 @@ You can [start](getting-started-preparation.md#verifying-installation) your loca
|
||||||
|
|
||||||
## Adding Other Custom Pages
|
## Adding Other Custom Pages
|
||||||
|
|
||||||
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.
|
Docusaurus provides some helpful 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
|
```bash
|
||||||
root-directory
|
root-directory
|
||||||
|
@ -33,7 +33,7 @@ root-directory
|
||||||
└── static
|
└── 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).
|
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).
|
||||||
|
|
||||||
> If you want your page to show up in your navigation header, you will need to update `siteConfig.js` to add to the `headerLinks` element. e.g., `{ page: 'about-slash', label: 'About/' }`,
|
> If you want your page to show up in your navigation header, you will need to update `siteConfig.js` to add to the `headerLinks` element. e.g., `{ page: 'about-slash', label: 'About/' }`,
|
||||||
|
|
||||||
|
|
|
@ -263,7 +263,7 @@ These are two separate class names so you can have the active styles applied to
|
||||||
|
|
||||||
## Secondary On-Page Navigation
|
## Secondary On-Page Navigation
|
||||||
|
|
||||||
We support secondary on-page navigation so you can more easily see the topics associated with a given document. To enable this feature, you need to add the `onPageNav` site configuration [option](api-site-config.md#optional-fields) to your `siteConfig.js`.
|
We support secondary on-page navigation so you can quickly see the topics associated with a given document. To enable this feature, you need to add the `onPageNav` site configuration [option](api-site-config.md#optional-fields) to your `siteConfig.js`.
|
||||||
|
|
||||||
```js
|
```js
|
||||||
{
|
{
|
||||||
|
|
|
@ -5,7 +5,7 @@ title: Configuration
|
||||||
|
|
||||||
Docusaurus has a unique take on configurations. We encourage you to congregate information of your site into one place. We will guard the fields of this file, and facilitate making this data object accessible across your site.
|
Docusaurus has a unique take on configurations. We encourage you to congregate information of your site into one place. We will guard the fields of this file, and facilitate making this data object accessible across your site.
|
||||||
|
|
||||||
Keeping a well-maintained `docusaurus.config.js` helps you, your collaborators, and your open source contributors be able to focus on documentation while still being able to easily customize fields.
|
Keeping a well-maintained `docusaurus.config.js` helps you, your collaborators, and your open source contributors be able to focus on documentation while still being able to customize fields.
|
||||||
|
|
||||||
## What goes into `docusaurus.config.js`?
|
## What goes into `docusaurus.config.js`?
|
||||||
|
|
||||||
|
|
|
@ -183,7 +183,7 @@ In order to accept your pull request, we need you to submit a CLA. You only need
|
||||||
|
|
||||||
### What happens next?
|
### What happens next?
|
||||||
|
|
||||||
The core Docusaurus team will be monitoring for pull requests. Do help us by making your pull request easy to review by following the guidelines above.
|
The core Docusaurus team will be monitoring for pull requests. Do help us by keeping pull requests consistent by following the guidelines above.
|
||||||
|
|
||||||
## License
|
## License
|
||||||
|
|
||||||
|
|
|
@ -41,7 +41,7 @@ Docusaurus is built with high attention to your experience building your site an
|
||||||
- Open source your plugins to share with your fellow documentarians, because sharing is caring.
|
- Open source your plugins to share with your fellow documentarians, because sharing is caring.
|
||||||
- ✂️ **Developer experience**
|
- ✂️ **Developer experience**
|
||||||
- Multiple bootstrapping templates to get your site up and running, start writing your docs right now
|
- Multiple bootstrapping templates to get your site up and running, start writing your docs right now
|
||||||
- Universal configuration entry point to make it easily maintainable by contributors
|
- Universal configuration entry point to make it more maintainable by contributors
|
||||||
- Hot reloading with lightning fast incremental build on changes
|
- Hot reloading with lightning fast incremental build on changes
|
||||||
- Route-based code and data splitting
|
- Route-based code and data splitting
|
||||||
- Publish to GitHub Pages, Netlify, and other deployment services with ease
|
- Publish to GitHub Pages, Netlify, and other deployment services with ease
|
||||||
|
|
|
@ -10,7 +10,7 @@ combining:
|
||||||
- markdown features
|
- markdown features
|
||||||
-->
|
-->
|
||||||
|
|
||||||
Documentation is one of your product's interfaces with your users. A well-written and well-organized set of docs helps your users understand your product quickly. Our aligned goal here is to help your users find and understand the information they need, as easily as possible.
|
Documentation is one of your product's interfaces with your users. A well-written and well-organized set of docs helps your users understand your product quickly. Our aligned goal here is to help your users find and understand the information they need, as quickly as possible.
|
||||||
|
|
||||||
Docusaurus 2 uses modern tooling to help you compose your interactive documentations with ease. You may embed React components, or build live coding blocks where your users may play with the code on the spot. Start sharing your eureka moments with the code your audience cannot walk away from. It is perhaps the most effective way of attracting potential users.
|
Docusaurus 2 uses modern tooling to help you compose your interactive documentations with ease. You may embed React components, or build live coding blocks where your users may play with the code on the spot. Start sharing your eureka moments with the code your audience cannot walk away from. It is perhaps the most effective way of attracting potential users.
|
||||||
|
|
||||||
|
@ -20,7 +20,7 @@ In this section, we'd like to introduce you to the tools we've picked that we be
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
Markdown is a syntax that enables you to write formatted content in an easy-to-use syntax. The [standard Markdown syntax](https://daringfireball.net/projects/markdown/syntax) is supported and we use [MDX](https://mdxjs.com/) as the parsing engine, which can do much more than just parsing Markdown. More on that later.
|
Markdown is a syntax that enables you to write formatted content in a readable syntax. The [standard Markdown syntax](https://daringfireball.net/projects/markdown/syntax) is supported and we use [MDX](https://mdxjs.com/) as the parsing engine, which can do much more than just parsing Markdown. More on that later.
|
||||||
|
|
||||||
Create a markdown file, `greeting.md`, and place it under the `docs` directory.
|
Create a markdown file, `greeting.md`, and place it under the `docs` directory.
|
||||||
|
|
||||||
|
|
|
@ -6,7 +6,7 @@ keywords:
|
||||||
- search
|
- search
|
||||||
---
|
---
|
||||||
|
|
||||||
Docusaurus's own `@docusaurus/preset-classic` supports easy search integration.
|
Docusaurus's own `@docusaurus/preset-classic` supports a search integration.
|
||||||
|
|
||||||
There are two main options, you can use [Algolia DocSearch](https://community.algolia.com/docsearch/) or bring in your own `SearchBar` component.
|
There are two main options, you can use [Algolia DocSearch](https://community.algolia.com/docsearch/) or bring in your own `SearchBar` component.
|
||||||
|
|
||||||
|
|
|
@ -4,7 +4,7 @@ title: Themes
|
||||||
sidebar_label: Introduction
|
sidebar_label: Introduction
|
||||||
---
|
---
|
||||||
|
|
||||||
Like plugins, themes are designed to add functionality to your Docusaurus site. As a good rule of thumb, themes are mostly focused on client-side, where plugins are more focused on server-side functionalities. Themes are also designed to be easily replace-able with other themes.
|
Like plugins, themes are designed to add functionality to your Docusaurus site. As a good rule of thumb, themes are mostly focused on client-side, where plugins are more focused on server-side functionalities. Themes are also designed to be replace-able with other themes.
|
||||||
|
|
||||||
## Using themes
|
## Using themes
|
||||||
|
|
||||||
|
@ -75,7 +75,7 @@ The content plugin remains the same and the only thing you need to change is the
|
||||||
|
|
||||||
## Swizzling theme components
|
## Swizzling theme components
|
||||||
|
|
||||||
Docusaurus Themes' components are designed to be easily replaceable. To make it easier for you, we created a command for you to replace theme components called `swizzle`.
|
Docusaurus Themes' components are designed to be replaceable. To make it easier for you, we created a command for you to replace theme components called `swizzle`.
|
||||||
|
|
||||||
To swizzle a component for a theme, run the following command in your doc site:
|
To swizzle a component for a theme, run the following command in your doc site:
|
||||||
|
|
||||||
|
|
Loading…
Add table
Add a link
Reference in a new issue