gcg/static-cms
0
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

docs: split and expand backend docs (#3350)

Browse Source
This commit is contained in:
Shawn Erquhart 2020-03-02 12:34:33 -05:00 committed by GitHub
parent 4e1e5a9bd5
commit 567adc7e11
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
11 changed files with 287 additions and 236 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

196
website/content/docs/authentication-backends.md
View File

@ -1,196 +0,0 @@
---
title: Authentication & Backends
weight: 25
group: start
---
Netlify CMS stores content in your GitHub, GitLab, or Bitbucket repository. In order for this to work, it must authenticate with your Git host. In most cases that requires a server. We have a few options for handling this.
**Note:** If you prefer to run your own authentication server, check out the section on [external OAuth clients](#external-oauth-clients).
**Note:** Some static site generators have plugins for optimized integration with Netlify CMS, and starter templates may utilize these plugins. If you're using a starter template, read the template documentation before proceeding, as their instructions may differ.
## Git Gateway with Netlify Identity
[Git Gateway](https://github.com/netlify/git-gateway) is a Netlify open source project that allows you to add editors to your site CMS without giving them direct write access to your GitHub or GitLab repository. (For Bitbucket repositories, use the [Bitbucket backend](#bitbucket-backend) instead.) The [Netlify Identity](https://www.netlify.com/docs/identity/) service can handle the authentication and provides a simple interface for user management. The Netlify CMS [featured templates](../start-with-a-template) are working examples of this backend.
To use it in your own project stored on GitHub or GitLab, follow these steps:
1. Head over to the [Netlify Identity docs](https://www.netlify.com/docs/identity) and follow the steps to get started.
2. Add the following lines to your Netlify CMS `config.yml` file:
```yaml
backend:
name: git-gateway
```
### Reconnect after Changing Repository Permissions
If you change ownership on your repository, or convert a repository from public to private, you may need to reconnect Git Gateway with proper permissions. Find further instructions in the [Netlify Git Gateway docs](https://www.netlify.com/docs/git-gateway/#reconnect-after-changing-repository-permissions).
## Git Gateway without Netlify
You can use [Git Gateway](https://github.com/netlify/git-gateway) without Netlify by setting up your own Git Gateway server and connecting it with your own instance of [GoTrue](https://www.gotrueapi.org) (the open source microservice that powers Netlify Identity), or with any other identity service that can issue JSON Web Tokens (JWT).
To configure in Netlify CMS, use the same `backend` settings in your Netlify CMS `config.yml` file as described in Step 2 of the [Git Gateway with Netlify Identity](#git-gateway-with-netlify-identity) instructions above.
## GitHub Backend
For repositories stored on GitHub, the `github` backend allows CMS users to log in directly with their GitHub account. Note that all users must have push access to your content repository for this to work.
Because Github [requires a server](https://github.com/netlify/netlify-cms/issues/663#issuecomment-335023723) for authentication, Netlify facilitates basic GitHub authentication.
To enable basic GitHub authentication:
1. Follow the authentication provider setup steps in the [Netlify docs](https://www.netlify.com/docs/authentication-providers/#using-an-authentication-provider).
2. Add the following lines to your Netlify CMS `config.yml` file:
```yaml
backend:
name: github
repo: owner-name/repo-name # Path to your GitHub repository
```
### Specifying a status for deploy previews
The GitHub backend supports [deploy preview links](../deploy-preview-links). Netlify CMS checks the
`context` of a commit's [statuses](https://help.github.com/articles/about-status-checks/) and infers
one that seems to represent a deploy preview. If you need to customize this behavior, you can
specify which context to look for using `preview_context`:
```yaml
backend:
name: github
repo: my/repo
preview_context: my-provider/deployment
```
The above configuration would look for the status who's `"context"` is `"my-provider/deployment"`.
## GitLab Backend
For repositories stored on GitLab, the `gitlab` backend allows CMS users to log in directly with their GitLab account. Note that all users must have push access to your content repository for this to work.
The GitLab API allows for two types of OAuth2 flows:
* [Web Application Flow](https://docs.gitlab.com/ce/api/oauth2.html#web-application-flow), which works much like the GitHub OAuth flow described above.
* [Implicit Grant](https://docs.gitlab.com/ce/api/oauth2.html#implicit-grant-flow), which operates _without_ the need for an authentication server.
### Web Application Flow with Netlify
When using GitLab's Web Application Flow for authentication, you can use Netlify to handle the server-side authentication requests.
To enable it:
1. Follow the [GitLab docs](https://docs.gitlab.com/ee/integration/oauth_provider.html#adding-an-application-through-the-profile) to add your Netlify CMS instance as an OAuth application. For the **Redirect URI**, enter `https://api.netlify.com/auth/done`, and check the box for `api` scope.
2. Follow the [Netlify docs](https://www.netlify.com/docs/authentication-providers/#using-an-authentication-provider) to add your new GitLab Application ID and Secret to your Netlify site dashboard.
3. In your repository, add the following lines to your Netlify CMS `config.yml` file:
```yaml
backend:
name: gitlab
repo: owner-name/repo-name # Path to your GitLab repository
```
### Client-Side Implicit Grant (GitLab)
With GitLab's Implicit Grant, users can authenticate with GitLab directly from the client. To do this:
1. Follow the [GitLab docs](https://docs.gitlab.com/ee/integration/oauth_provider.html#adding-an-application-through-the-profile) to add your Netlify CMS instance as an OAuth application. For the **Redirect URI**, enter the address where you access Netlify CMS, for example, `https://www.mysite.com/admin/`. For scope, select `api`.
2. GitLab gives you an **Application ID**. Copy this ID and enter it in your Netlify CMS `config.yml` file, along with the following settings:
```yaml
backend:
name: gitlab
repo: owner-name/repo-name # Path to your GitLab repository
auth_type: implicit # Required for implicit grant
app_id: your-app-id # Application ID from your GitLab settings
```
You can also use Implicit Grant with a self-hosted GitLab instance. This requires adding `api_root`, `base_url`, and `auth_endpoint` fields:
```yaml
backend:
name: gitlab
repo: owner-name/repo-name # Path to your GitLab repository
auth_type: implicit # Required for implicit grant
app_id: your-app-id # Application ID from your GitLab settings
api_root: https://my-hosted-gitlab-instance.com/api/v4
base_url: https://my-hosted-gitlab-instance.com
auth_endpoint: oauth/authorize
```
**Note:** In both cases, GitLab also provides you with a client secret. You should _never_ store this in your repo or reveal it in the client.
## Bitbucket Backend
For repositories stored on Bitbucket, the `bitbucket` backend allows CMS users to log in directly with their Bitbucket account. Note that all users must have write access to your content repository for this to work.
To enable it:
1. Follow the authentication provider setup steps in the [Netlify docs](https://www.netlify.com/docs/authentication-providers/#using-an-authentication-provider).
2. Add the following lines to your Netlify CMS `config.yml` file:
```yaml
backend:
name: bitbucket
repo: owner-name/repo-name # Path to your Bitbucket repository
```
### Client-Side Implicit Grant (Bitbucket)
With Bitbucket's Implicit Grant, users can authenticate with Bitbucket directly from the client. To do this:
1. Follow the [Atlassian docs](https://confluence.atlassian.com/bitbucket/oauth-on-bitbucket-cloud-238027431.html) to create an OAuth consumer. Make sure you allow `Account/Read` and `Repository/Write` permissions. For the **Callback URL**, enter the address where you access Netlify CMS, for example, `https://www.mysite.com/admin/`.
2. Bitbucket gives you a **Key**. Copy this Key and enter it in your Netlify CMS `config.yml` file, along with the following settings:
```yaml
backend:
name: bitbucket
repo: owner-name/repo-name
branch: default
auth_type: implicit
app_id: # The Key from your Bitbucket settings
```
**Warning:** With Bitbucket implicit grant, the authentication is valid for 1 hour only. After that, the user has to login again, **which can lead to data loss** if the expiration occurs while content is being edited.
## Test Repo Backend
You can use the `test-repo` backend to try out Netlify CMS without connecting to a Git repo. With this backend, you can write and publish content normally, but any changes will disappear when you reload the page. This backend powers the Netlify CMS [demo site](https://cms-demo.netlify.com/).
**Note:** The `test-repo` backend can't access your local file system, nor does it connect to a Git repo, thus you won't see any existing files while using it.
To enable this backend, add the following lines to your Netlify CMS `config.yml` file:
```yaml
backend:
name: test-repo
```
## External OAuth Clients
If you would like to facilitate your own OAuth authentication rather than use Netlify's service or implicit grant, you can use one of the community-maintained projects below. Feel free to [submit a pull request](https://github.com/netlify/netlify-cms/blob/master/CONTRIBUTING.md) if you'd like to add yours!
| Author | Supported Git hosts | Language(s)/Platform(s) | Link |
| ---------------------------------------------- | ------------------------- | ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| [@vencax](https://github.com/vencax) | GitHub, GitHub Enterprise | Node.js | [Repo](https://github.com/vencax/netlify-cms-github-oauth-provider) |
| [@igk1972](https://github.com/igk1972) | GitHub, GitHub Enterprise | Go | [Repo](https://github.com/igk1972/netlify-cms-oauth-provider-go) |
| [@davidejones](https://github.com/davidejones) | GitHub, GitHub Enterprise | Python | [Repo](https://github.com/davidejones/netlify-cms-oauth-provider-python) |
| [@marcelkornblum](https://github.com/marcelkornblum) | GitHub, GitHub Enterprise | Google AppEngine with Python | [Repo](https://github.com/signal-noise/netlify-cms-oauth-provider-python-appengine) |
| [@marksteele](https://github.com/marksteele) | GitHub, GitHub Enterprise | Serverless | [Repo](https://github.com/marksteele/netlify-serverless-oauth2-backend), [Blog](https://www.control-alt-del.org/blog/serverless-blog-howto/) |
| [@Herohtar](https://github.com/Herohtar) | GitHub, GitHub Enterprise | Firebase Cloud Function | [Repo](https://github.com/Herohtar/netlify-cms-oauth-firebase) |
| [@abcalderon3](https://github.com/abcalderon3) | GitHub, GitHub Enterprise | Google Cloud Function with Python | [Repo](https://github.com/abcalderon3/netlify-cms-oauth-client-cloud-function) |
| [@TSV-Zorneding-1920](https://github.com/TSV-Zorneding-1920) | GitHub, GitHub Enterprise | PHP | [Repo](https://github.com/TSV-Zorneding-1920/netlify-cms-oauth-provider-php)
Check each project's documentation for instructions on how to configure it.
## Options
Netlify CMS backends allow some additional fields for certain use cases. A full reference is below. Note that these are properties of the `backend` field, and should be nested under that field.
| Field | Default | Description |
| --------------- | -------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| `repo` | none | **Required** for `github`, `gitlab`, and `bitbucket` backends; ignored by `git-gateway`. Follows the pattern `[org-or-username]/[repo-name]`. |
| `branch` | `master` | The branch where published content is stored. All CMS commits and PRs are made to this branch. |
| `api_root` | `https://api.github.com` (GitHub), `https://gitlab.com/api/v4` (GitLab), or `https://api.bitbucket.org/2.0` (Bitbucket) | The API endpoint. Only necessary in certain cases, like with GitHub Enterprise or self-hosted GitLab. |
| `site_domain` | `location.hostname` (or `cms.netlify.com` when on `localhost`) | Sets the `site_id` query param sent to the API endpoint. Non-Netlify auth setups will often need to set this for local development to work properly. |
| `base_url` | `https://api.netlify.com` (GitHub, Bitbucket) or `https://gitlab.com` (GitLab) | OAuth client hostname (just the base domain, no path). **Required** when using an external OAuth server or self-hosted GitLab. |
| `auth_endpoint` | `auth` (GitHub, Bitbucket) or `oauth/authorize` (GitLab) | Path to append to `base_url` for authentication requests. Optional. |

24
website/content/docs/backends-overview.md Normal file
View File

@ -0,0 +1,24 @@
---
title: Overview
weight: 1
group: backends
---
A backend is JavaScript code that allows Netlify CMS to communicate with a service that stores content - typically a Git host like GitHub or GitLab. It provides functions that Netlify CMS can use to do things like read and update files using API's provided by the service.
## Backend Configuration
Individual backends should provide their own configuration documentation, but there are some configuration options that are common to multiple backends. A full reference is below. Note that these are properties of the `backend` field, and should be nested under that field.
| Field | Default | Description |
| --------------- | -------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| `repo` | none | **Required** for `github`, `gitlab`, and `bitbucket` backends; ignored by `git-gateway`. Follows the pattern `[org-or-username]/[repo-name]`. |
| `branch` | `master` | The branch where published content is stored. All CMS commits and PRs are made to this branch. |
| `api_root` | `https://api.github.com` (GitHub), `https://gitlab.com/api/v4` (GitLab), or `https://api.bitbucket.org/2.0` (Bitbucket) | The API endpoint. Only necessary in certain cases, like with GitHub Enterprise or self-hosted GitLab. |
| `site_domain` | `location.hostname` (or `cms.netlify.com` when on `localhost`) | Sets the `site_id` query param sent to the API endpoint. Non-Netlify auth setups will often need to set this for local development to work properly. |
| `base_url` | `https://api.netlify.com` (GitHub, Bitbucket) or `https://gitlab.com` (GitLab) | OAuth client hostname (just the base domain, no path). **Required** when using an external OAuth server or self-hosted GitLab. |
| `auth_endpoint` | `auth` (GitHub, Bitbucket) or `oauth/authorize` (GitLab) | Path to append to `base_url` for authentication requests. Optional. |
## Creating a New Backend
Anyone can write a backend, but we don't yet have a finalized and documented API. If you would like to write your own backend for a service that does not have one currently, we recommend using the [GitHub backend](https://github.com/netlify/netlify-cms/tree/master/packages/netlify-cms-backend-github) as a reference for API and best practices.

36
website/content/docs/bitbucket-backend.md Normal file
View File

@ -0,0 +1,36 @@
---
title: Bitbucket
weight: 20
group: backends
---
For repositories stored on Bitbucket, the `bitbucket` backend allows CMS users to log in directly with their Bitbucket account. Note that all users must have write access to your content repository for this to work.
To enable it:
1. Follow the authentication provider setup steps in the [Netlify docs](https://www.netlify.com/docs/authentication-providers/#using-an-authentication-provider).
2. Add the following lines to your Netlify CMS `config.yml` file:
```yaml
backend:
name: bitbucket
repo: owner-name/repo-name # Path to your Bitbucket repository
```
### Client-Side Implicit Grant (Bitbucket)
With Bitbucket's Implicit Grant, users can authenticate with Bitbucket directly from the client. To do this:
1. Follow the [Atlassian docs](https://confluence.atlassian.com/bitbucket/oauth-on-bitbucket-cloud-238027431.html) to create an OAuth consumer. Make sure you allow `Account/Read` and `Repository/Write` permissions. For the **Callback URL**, enter the address where you access Netlify CMS, for example, `https://www.mysite.com/admin/`.
2. Bitbucket gives you a **Key**. Copy this Key and enter it in your Netlify CMS `config.yml` file, along with the following settings:
```yaml
backend:
name: bitbucket
repo: owner-name/repo-name
branch: default
auth_type: implicit
app_id: # The Key from your Bitbucket settings
```
**Warning:** With Bitbucket implicit grant, the authentication is valid for 1 hour only. After that, the user has to login again, **which can lead to data loss** if the expiration occurs while content is being edited.

20
website/content/docs/external-oauth-clients.md Normal file
View File

@ -0,0 +1,20 @@
---
title: External OAuth Clients
weight: 40
group: backends
---
If you would like to facilitate your own OAuth authentication rather than use Netlify's service or implicit grant, you can use one of the community-maintained projects below. Feel free to hit the "Edit this page" button if you'd like to add yours!
| Author | Supported Git hosts | Language(s)/Platform(s) | Link |
| ---------------------------------------------- | ------------------------- | ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| [@vencax](https://github.com/vencax) | GitHub, GitHub Enterprise | Node.js | [Repo](https://github.com/vencax/netlify-cms-github-oauth-provider) |
| [@igk1972](https://github.com/igk1972) | GitHub, GitHub Enterprise | Go | [Repo](https://github.com/igk1972/netlify-cms-oauth-provider-go) |
| [@davidejones](https://github.com/davidejones) | GitHub, GitHub Enterprise | Python | [Repo](https://github.com/davidejones/netlify-cms-oauth-provider-python) |
| [@marcelkornblum](https://github.com/marcelkornblum) | GitHub, GitHub Enterprise | Google AppEngine with Python | [Repo](https://github.com/signal-noise/netlify-cms-oauth-provider-python-appengine) |
| [@marksteele](https://github.com/marksteele) | GitHub, GitHub Enterprise | Serverless | [Repo](https://github.com/marksteele/netlify-serverless-oauth2-backend), [Blog](https://www.control-alt-del.org/blog/serverless-blog-howto/) |
| [@Herohtar](https://github.com/Herohtar) | GitHub, GitHub Enterprise | Firebase Cloud Function | [Repo](https://github.com/Herohtar/netlify-cms-oauth-firebase) |
| [@abcalderon3](https://github.com/abcalderon3) | GitHub, GitHub Enterprise | Google Cloud Function with Python | [Repo](https://github.com/abcalderon3/netlify-cms-oauth-client-cloud-function) |
| [@TSV-Zorneding-1920](https://github.com/TSV-Zorneding-1920) | GitHub, GitHub Enterprise | PHP | [Repo](https://github.com/TSV-Zorneding-1920/netlify-cms-oauth-provider-php)
Check each project's documentation for instructions on installation and usage.

26
website/content/docs/git-gateway-backend.md Normal file
View File

@ -0,0 +1,26 @@
---
title: Git Gateway
weight: 10
group: backends
---
[Git Gateway](https://github.com/netlify/git-gateway) is a Netlify open source project that allows you to add editors to your site CMS without giving them direct write access to your GitHub or GitLab repository. (For Bitbucket repositories, use the [Bitbucket backend](#bitbucket-backend) instead.) The [Netlify Identity](https://www.netlify.com/docs/identity/) service can handle the authentication and provides a simple interface for user management. The Netlify CMS [featured templates](../start-with-a-template) are working examples of this backend.
To use it in your own project stored on GitHub or GitLab, follow these steps:
1. Head over to the [Netlify Identity docs](https://www.netlify.com/docs/identity) and follow the steps to get started.
2. Add the following lines to your Netlify CMS `config.yml` file:
```yaml
backend:
name: git-gateway
```
## Reconnect after Changing Repository Permissions
If you change ownership on your repository, or convert a repository from public to private, you may need to reconnect Git Gateway with proper permissions. Find further instructions in the [Netlify Git Gateway docs](https://www.netlify.com/docs/git-gateway/#reconnect-after-changing-repository-permissions).
## Git Gateway without Netlify
You can use [Git Gateway](https://github.com/netlify/git-gateway) without Netlify by setting up your own Git Gateway server and connecting it with your own instance of [GoTrue](https://www.gotrueapi.org) (the open source microservice that powers Netlify Identity), or with any other identity service that can issue JSON Web Tokens (JWT).
To configure in Netlify CMS, use the same `backend` settings in your Netlify CMS `config.yml` file as described in Step 2 of the [Git Gateway with Netlify Identity](#git-gateway-with-netlify-identity) instructions above.

34
website/content/docs/github-backend.md Normal file
View File

@ -0,0 +1,34 @@
---
title: GitHub
weight: 20
group: backends
---
For repositories stored on GitHub, the `github` backend allows CMS users to log in directly with their GitHub account. Note that all users must have push access to your content repository for this to work.
Because Github [requires a server](https://github.com/netlify/netlify-cms/issues/663#issuecomment-335023723) for authentication, Netlify facilitates basic GitHub authentication.
To enable basic GitHub authentication:
1. Follow the authentication provider setup steps in the [Netlify docs](https://www.netlify.com/docs/authentication-providers/#using-an-authentication-provider).
2. Add the following lines to your Netlify CMS `config.yml` file:
```yaml
backend:
name: github
repo: owner-name/repo-name # Path to your GitHub repository
```
## Specifying a status for deploy previews
The GitHub backend supports [deploy preview links](../deploy-preview-links). Netlify CMS checks the
`context` of a commit's [statuses](https://help.github.com/articles/about-status-checks/) and infers
one that seems to represent a deploy preview. If you need to customize this behavior, you can
specify which context to look for using `preview_context`:
```yaml
backend:
name: github
repo: my/repo
preview_context: my-provider/deployment
```
The above configuration would look for the status who's `"context"` is `"my-provider/deployment"`.

58
website/content/docs/gitlab-backend.md Normal file
View File

@ -0,0 +1,58 @@
---
title: GitLab
weight: 20
group: backends
---
For repositories stored on GitLab, the `gitlab` backend allows CMS users to log in directly with their GitLab account. Note that all users must have push access to your content repository for this to work.
The GitLab API allows for two types of OAuth2 flows:
* [Web Application Flow](https://docs.gitlab.com/ce/api/oauth2.html#web-application-flow), which works much like the GitHub OAuth flow described above.
* [Implicit Grant](https://docs.gitlab.com/ce/api/oauth2.html#implicit-grant-flow), which operates _without_ the need for an authentication server.
## Web Application Flow with Netlify
When using GitLab's Web Application Flow for authentication, you can use Netlify to handle the server-side authentication requests.
To enable it:
1. Follow the [GitLab docs](https://docs.gitlab.com/ee/integration/oauth_provider.html#adding-an-application-through-the-profile) to add your Netlify CMS instance as an OAuth application. For the **Redirect URI**, enter `https://api.netlify.com/auth/done`, and check the box for `api` scope.
2. Follow the [Netlify docs](https://www.netlify.com/docs/authentication-providers/#using-an-authentication-provider) to add your new GitLab Application ID and Secret to your Netlify site dashboard.
3. In your repository, add the following lines to your Netlify CMS `config.yml` file:
```yaml
backend:
name: gitlab
repo: owner-name/repo-name # Path to your GitLab repository
```
## Client-Side Implicit Grant (GitLab)
With GitLab's Implicit Grant, users can authenticate with GitLab directly from the client. To do this:
1. Follow the [GitLab docs](https://docs.gitlab.com/ee/integration/oauth_provider.html#adding-an-application-through-the-profile) to add your Netlify CMS instance as an OAuth application. For the **Redirect URI**, enter the address where you access Netlify CMS, for example, `https://www.mysite.com/admin/`. For scope, select `api`.
2. GitLab gives you an **Application ID**. Copy this ID and enter it in your Netlify CMS `config.yml` file, along with the following settings:
```yaml
backend:
name: gitlab
repo: owner-name/repo-name # Path to your GitLab repository
auth_type: implicit # Required for implicit grant
app_id: your-app-id # Application ID from your GitLab settings
```
You can also use Implicit Grant with a self-hosted GitLab instance. This requires adding `api_root`, `base_url`, and `auth_endpoint` fields:
```yaml
backend:
name: gitlab
repo: owner-name/repo-name # Path to your GitLab repository
auth_type: implicit # Required for implicit grant
app_id: your-app-id # Application ID from your GitLab settings
api_root: https://my-hosted-gitlab-instance.com/api/v4
base_url: https://my-hosted-gitlab-instance.com
auth_endpoint: oauth/authorize
```
**Note:** In both cases, GitLab also provides you with a client secret. You should _never_ store this in your repo or reveal it in the client.

16
website/content/docs/test-backend.md Normal file
View File

@ -0,0 +1,16 @@
---
title: Test
weight: 30
group: backends
---
You can use the `test-repo` backend to try out Netlify CMS without connecting to a Git repo. With this backend, you can write and publish content normally, but any changes will disappear when you reload the page. This backend powers the Netlify CMS [demo site](https://cms-demo.netlify.com/).
**Note:** The `test-repo` backend can't access your local file system, nor does it connect to a Git repo, thus you won't see any existing files while using it.
To enable this backend, add the following lines to your Netlify CMS `config.yml` file:
```yaml
backend:
name: test-repo
```

2
website/site.yml
View File

@ -2,6 +2,8 @@ menu:
docs: docs:
- name: start - name: start
title: Quick Start title: Quick Start
- name: backends
title: Backends
- name: features - name: features
title: Features title: Features
- name: reference - name: reference

17
website/src/components/table-of-contents.js
View File

@ -33,6 +33,7 @@ const TableOfContents = () => {
const [headings, setHeadings] = useState([]); const [headings, setHeadings] = useState([]);
useEffect(() => { useEffect(() => {
// TODO: we should be generating headings during the build
const contentHeadings = document.querySelectorAll('[data-docs-content] h2'); const contentHeadings = document.querySelectorAll('[data-docs-content] h2');
const headings = []; const headings = [];
contentHeadings.forEach(h => { contentHeadings.forEach(h => {
@ -46,13 +47,15 @@ const TableOfContents = () => {
}, []); }, []);
return ( return (
<TocList> headings.length > 0 && (
{headings.map(h => ( <TocList>
<li key={h.id}> {headings.map(h => (
<TocLink href={`#${h.id}`}>{h.text}</TocLink> <li key={h.id}>
</li> <TocLink href={`#${h.id}`}>{h.text}</TocLink>
))} </li>
</TocList> ))}
</TocList>
)
); );
}; };

94
website/yarn.lock
View File

@ -843,9 +843,9 @@
source-map "^0.7.2" source-map "^0.7.2"
"@emotion/cache@^10.0.27": "@emotion/cache@^10.0.27":
version "10.0.27" version "10.0.29"
resolved "https://registry.yarnpkg.com/@emotion/cache/-/cache-10.0.27.tgz#7895db204e2c1a991ae33d51262a3a44f6737303" resolved "https://registry.yarnpkg.com/@emotion/cache/-/cache-10.0.29.tgz#87e7e64f412c060102d589fe7c6dc042e6f9d1e0"
integrity sha512-Zp8BEpbMunFsTcqAK4D7YTm3MvCp1SekflSLJH8lze2fCcSZ/yMkXHo8kb3t1/1Tdd3hAqf3Fb7z9VZ+FMiC9w== integrity sha512-fU2VtSVlHiF27empSbxi1O2JFdNWZO+2NFHfwO0pxgTep6Xa3uGb+3pVKfLww2l/IBGLNEZl5Xf/++A4wAYDYQ==
dependencies: dependencies:
"@emotion/sheet" "0.9.4" "@emotion/sheet" "0.9.4"
"@emotion/stylis" "0.8.5" "@emotion/stylis" "0.8.5"
@ -873,10 +873,10 @@
"@emotion/utils" "0.11.3" "@emotion/utils" "0.11.3"
babel-plugin-emotion "^10.0.27" babel-plugin-emotion "^10.0.27"
"@emotion/hash@0.7.4": "@emotion/hash@0.8.0":
version "0.7.4" version "0.8.0"
resolved "https://registry.yarnpkg.com/@emotion/hash/-/hash-0.7.4.tgz#f14932887422c9056b15a8d222a9074a7dfa2831" resolved "https://registry.yarnpkg.com/@emotion/hash/-/hash-0.8.0.tgz#bbbff68978fefdbe68ccb533bc8cbe1d1afb5413"
integrity sha512-fxfMSBMX3tlIbKUdtGKxqB1fyrH6gVrX39Gsv3y8lRYKUqlgDt3UMqQyGnR1bQMa2B8aGnhLZokZgg8vT0Le+A== integrity sha512-kBJtf7PH6aWwZ6fka3zQ0p6SBYzx4fl1LoZXE2RrnYST9Xljm7WfKJrU4g/Xr3Beg72MLrp1AWNUmuYJTL7Cow==
"@emotion/hash@^0.6.2", "@emotion/hash@^0.6.6": "@emotion/hash@^0.6.2", "@emotion/hash@^0.6.6":
version "0.6.6" version "0.6.6"
@ -900,12 +900,12 @@
resolved "https://registry.yarnpkg.com/@emotion/memoize/-/memoize-0.6.6.tgz#004b98298d04c7ca3b4f50ca2035d4f60d2eed1b" resolved "https://registry.yarnpkg.com/@emotion/memoize/-/memoize-0.6.6.tgz#004b98298d04c7ca3b4f50ca2035d4f60d2eed1b"
integrity sha512-h4t4jFjtm1YV7UirAFuSuFGyLa+NNxjdkq6DpFLANNQY5rHueFZHVY+8Cu1HYVP6DrheB0kv4m5xPjo7eKT7yQ== integrity sha512-h4t4jFjtm1YV7UirAFuSuFGyLa+NNxjdkq6DpFLANNQY5rHueFZHVY+8Cu1HYVP6DrheB0kv4m5xPjo7eKT7yQ==
"@emotion/serialize@^0.11.15": "@emotion/serialize@^0.11.15", "@emotion/serialize@^0.11.16":
version "0.11.15" version "0.11.16"
resolved "https://registry.yarnpkg.com/@emotion/serialize/-/serialize-0.11.15.tgz#9a0f5873fb458d87d4f23e034413c12ed60a705a" resolved "https://registry.yarnpkg.com/@emotion/serialize/-/serialize-0.11.16.tgz#dee05f9e96ad2fb25a5206b6d759b2d1ed3379ad"
integrity sha512-YE+qnrmGwyR+XB5j7Bi+0GT1JWsdcjM/d4POu+TXkcnrRs4RFCCsi3d/Ebf+wSStHqAlTT2+dfd+b9N9EO2KBg== integrity sha512-G3J4o8by0VRrO+PFeSc3js2myYNOXVJ3Ya+RGVxnshRYgsvErfAOglKAiy1Eo1vhzxqtUvjCyS5gtewzkmvSSg==
dependencies: dependencies:
"@emotion/hash" "0.7.4" "@emotion/hash" "0.8.0"
"@emotion/memoize" "0.7.4" "@emotion/memoize" "0.7.4"
"@emotion/unitless" "0.7.5" "@emotion/unitless" "0.7.5"
"@emotion/utils" "0.11.3" "@emotion/utils" "0.11.3"
@ -1461,7 +1461,7 @@ accepts@^1.3.7, accepts@~1.3.4, accepts@~1.3.5, accepts@~1.3.7:
mime-types "~2.1.24" mime-types "~2.1.24"
negotiator "0.6.2" negotiator "0.6.2"
acorn-jsx@^5.1.0: acorn-jsx@^5.2.0:
version "5.2.0" version "5.2.0"
resolved "https://registry.yarnpkg.com/acorn-jsx/-/acorn-jsx-5.2.0.tgz#4c66069173d6fdd68ed85239fc256226182b2ebe" resolved "https://registry.yarnpkg.com/acorn-jsx/-/acorn-jsx-5.2.0.tgz#4c66069173d6fdd68ed85239fc256226182b2ebe"
integrity sha512-HiUX/+K2YpkpJ+SzBffkM/AQ2YE03S0U1kjTLVpoJdhZMOWy8qvXVN9JdLqv2QsaQ6MPYQIuNmwD8zOiYUofLQ== integrity sha512-HiUX/+K2YpkpJ+SzBffkM/AQ2YE03S0U1kjTLVpoJdhZMOWy8qvXVN9JdLqv2QsaQ6MPYQIuNmwD8zOiYUofLQ==
@ -1970,14 +1970,14 @@ babel-plugin-dynamic-import-node@^2.3.0:
object.assign "^4.1.0" object.assign "^4.1.0"
babel-plugin-emotion@^10.0.27: babel-plugin-emotion@^10.0.27:
version "10.0.28" version "10.0.29"
resolved "https://registry.yarnpkg.com/babel-plugin-emotion/-/babel-plugin-emotion-10.0.28.tgz#731133577795ea04e5b1d11aff247fa0ad3fd364" resolved "https://registry.yarnpkg.com/babel-plugin-emotion/-/babel-plugin-emotion-10.0.29.tgz#89d8e497091fcd3d10331f097f1471e4cc3f35b4"
integrity sha512-h25EMmPxYVNOgsEkGIjCv2Ok+HzW/e/b5lf2v2U17T9k6y6g0ku3TG9b+jy94ZrqMh+b/njRF4uOQrwVr28QfQ== integrity sha512-7Jpi1OCxjyz0k163lKtqP+LHMg5z3S6A7vMBfHnF06l2unmtsOmFDzZBpGf0CWo1G4m8UACfVcDJiSiRuu/cSw==
dependencies: dependencies:
"@babel/helper-module-imports" "^7.0.0" "@babel/helper-module-imports" "^7.0.0"
"@emotion/hash" "0.7.4" "@emotion/hash" "0.8.0"
"@emotion/memoize" "0.7.4" "@emotion/memoize" "0.7.4"
"@emotion/serialize" "^0.11.15" "@emotion/serialize" "^0.11.16"
babel-plugin-macros "^2.0.0" babel-plugin-macros "^2.0.0"
babel-plugin-syntax-jsx "^6.18.0" babel-plugin-syntax-jsx "^6.18.0"
convert-source-map "^1.5.0" convert-source-map "^1.5.0"
@ -2551,9 +2551,9 @@ caniuse-api@^3.0.0:
lodash.uniq "^4.5.0" lodash.uniq "^4.5.0"
caniuse-lite@^1.0.0, caniuse-lite@^1.0.30000844, caniuse-lite@^1.0.30001020, caniuse-lite@^1.0.30001030: caniuse-lite@^1.0.0, caniuse-lite@^1.0.30000844, caniuse-lite@^1.0.30001020, caniuse-lite@^1.0.30001030:
version "1.0.30001030" version "1.0.30001031"
resolved "https://registry.yarnpkg.com/caniuse-lite/-/caniuse-lite-1.0.30001030.tgz#78076c4c6d67d3e41d6eb9399853fb27fe6e44ee" resolved "https://registry.yarnpkg.com/caniuse-lite/-/caniuse-lite-1.0.30001031.tgz#76f1bdd39e19567b855302f65102d9a8aaad5930"
integrity sha512-QGK0W4Ft/Ac+zTjEiRJfwDNATvS3fodDczBXrH42784kcfqcDKpEPfN08N0HQjrAp8He/Jw8QiSS9QRn7XAbUw== integrity sha512-DpAP5a1NGRLgYfaNCaXIRyGARi+3tJA2quZXNNA1Du26VyVkqvy2tznNu5ANyN1Y5aX44QDotZSVSUSi2uMGjg==
ccount@^1.0.0, ccount@^1.0.3: ccount@^1.0.0, ccount@^1.0.3:
version "1.0.5" version "1.0.5"
@ -4335,12 +4335,12 @@ eslint@^6.7.2, eslint@^6.8.0:
v8-compile-cache "^2.0.3" v8-compile-cache "^2.0.3"
espree@^6.1.2: espree@^6.1.2:
version "6.1.2" version "6.2.0"
resolved "https://registry.yarnpkg.com/espree/-/espree-6.1.2.tgz#6c272650932b4f91c3714e5e7b5f5e2ecf47262d" resolved "https://registry.yarnpkg.com/espree/-/espree-6.2.0.tgz#349fef01a202bbab047748300deb37fa44da79d7"
integrity sha512-2iUPuuPP+yW1PZaMSDM9eyVf8D5P0Hi8h83YtZ5bPc/zHYjII5khoixIUTMO794NOY8F/ThF1Bo8ncZILarUTA== integrity sha512-Xs8airJ7RQolnDIbLtRutmfvSsAe0xqMMAantCN/GMoqf81TFbeI1T7Jpd56qYu1uuh32dOG5W/X9uO+ghPXzA==
dependencies: dependencies:
acorn "^7.1.0" acorn "^7.1.0"
acorn-jsx "^5.1.0" acorn-jsx "^5.2.0"
eslint-visitor-keys "^1.1.0" eslint-visitor-keys "^1.1.0"
esprima@^4.0.0: esprima@^4.0.0:
@ -4919,7 +4919,6 @@ fsevents@^1.2.7:
dependencies: dependencies:
bindings "^1.5.0" bindings "^1.5.0"
nan "^2.12.1" nan "^2.12.1"
node-pre-gyp "*"
fsevents@~2.1.1: fsevents@~2.1.1:
version "2.1.2" version "2.1.2"
@ -5036,9 +5035,9 @@ gatsby-plugin-catch-links@2.1.26:
escape-string-regexp "^1.0.5" escape-string-regexp "^1.0.5"
gatsby-plugin-emotion@^4.1.22: gatsby-plugin-emotion@^4.1.22:
version "4.1.22" version "4.1.23"
resolved "https://registry.yarnpkg.com/gatsby-plugin-emotion/-/gatsby-plugin-emotion-4.1.22.tgz#e153debef74afa205336738dcf1988c95b308c4f" resolved "https://registry.yarnpkg.com/gatsby-plugin-emotion/-/gatsby-plugin-emotion-4.1.23.tgz#a4fe3c63717a17c07393b460a0f27eae6c510987"
integrity sha512-XG9YpkyUgbTHs/Uq7W6tDVDVQ2XHlj9rHPhCYiZHlJTdrJIHhviousHZ8+vEI/h0FQ4oW/Hs0CuX2gi5SlvWSQ== integrity sha512-SP3hGbyj2Kq42iIS9tDR6aZMvBsbH7GhPizfmr+1L1KxYjFedjd3U/gWa346wJbvtiwnSkeoLZKMUATX4w1VCA==
dependencies: dependencies:
"@babel/runtime" "^7.7.6" "@babel/runtime" "^7.7.6"
"@emotion/babel-preset-css-prop" "^10.0.23" "@emotion/babel-preset-css-prop" "^10.0.23"
@ -8087,9 +8086,9 @@ natural-compare@^1.4.0:
integrity sha1-Sr6/7tdUHywnrPspvbvRXI1bpPc= integrity sha1-Sr6/7tdUHywnrPspvbvRXI1bpPc=
needle@^2.2.1: needle@^2.2.1:
version "2.3.2" version "2.3.3"
resolved "https://registry.yarnpkg.com/needle/-/needle-2.3.2.tgz#3342dea100b7160960a450dc8c22160ac712a528" resolved "https://registry.yarnpkg.com/needle/-/needle-2.3.3.tgz#a041ad1d04a871b0ebb666f40baaf1fb47867117"
integrity sha512-DUzITvPVDUy6vczKKYTnWc/pBZ0EnjMJnQ3y+Jo5zfKFimJs7S3HFCxCRZYB9FUZcrzUQr3WsmvZgddMEIZv6w== integrity sha512-EkY0GeSq87rWp1hoq/sH/wnTWgFVhYlnIkbJ0YJFfRgEFlz2RraCjBpFQ+vrEgEdp0ThfyHADmkChEhcb7PKyw==
dependencies: dependencies:
debug "^3.2.6" debug "^3.2.6"
iconv-lite "^0.4.4" iconv-lite "^0.4.4"
@ -13105,7 +13104,36 @@ webpack-stats-plugin@^0.3.0:
resolved "https://registry.yarnpkg.com/webpack-stats-plugin/-/webpack-stats-plugin-0.3.1.tgz#1103c39a305a4e6ba15d5078db84bc0b35447417" resolved "https://registry.yarnpkg.com/webpack-stats-plugin/-/webpack-stats-plugin-0.3.1.tgz#1103c39a305a4e6ba15d5078db84bc0b35447417"
integrity sha512-pxqzFE055NlNTlNyfDG3xlB2QwT1EWdm/CF5dCJI/e+rRHVxrWhWg1rf1lfsWhI1/EePv8gi/A36YxO/+u0FgQ== integrity sha512-pxqzFE055NlNTlNyfDG3xlB2QwT1EWdm/CF5dCJI/e+rRHVxrWhWg1rf1lfsWhI1/EePv8gi/A36YxO/+u0FgQ==
webpack@^4.41.2, webpack@~4.41.2: webpack@^4.41.2:
version "4.42.0"
resolved "https://registry.yarnpkg.com/webpack/-/webpack-4.42.0.tgz#b901635dd6179391d90740a63c93f76f39883eb8"
integrity sha512-EzJRHvwQyBiYrYqhyjW9AqM90dE4+s1/XtCfn7uWg6cS72zH+2VPFAlsnW0+W0cDi0XRjNKUMoJtpSi50+Ph6w==
dependencies:
"@webassemblyjs/ast" "1.8.5"
"@webassemblyjs/helper-module-context" "1.8.5"
"@webassemblyjs/wasm-edit" "1.8.5"
"@webassemblyjs/wasm-parser" "1.8.5"
acorn "^6.2.1"
ajv "^6.10.2"
ajv-keywords "^3.4.1"
chrome-trace-event "^1.0.2"
enhanced-resolve "^4.1.0"
eslint-scope "^4.0.3"
json-parse-better-errors "^1.0.2"
loader-runner "^2.4.0"
loader-utils "^1.2.3"
memory-fs "^0.4.1"
micromatch "^3.1.10"
mkdirp "^0.5.1"
neo-async "^2.6.1"
node-libs-browser "^2.2.1"
schema-utils "^1.0.0"
tapable "^1.1.3"
terser-webpack-plugin "^1.4.3"
watchpack "^1.6.0"
webpack-sources "^1.4.1"
webpack@~4.41.2:
version "4.41.6" version "4.41.6"
resolved "https://registry.yarnpkg.com/webpack/-/webpack-4.41.6.tgz#12f2f804bf6542ef166755050d4afbc8f66ba7e1" resolved "https://registry.yarnpkg.com/webpack/-/webpack-4.41.6.tgz#12f2f804bf6542ef166755050d4afbc8f66ba7e1"
integrity sha512-yxXfV0Zv9WMGRD+QexkZzmGIh54bsvEs+9aRWxnN8erLWEOehAKUTeNBoUbA6HPEZPlRo7KDi2ZcNveoZgK9MA== integrity sha512-yxXfV0Zv9WMGRD+QexkZzmGIh54bsvEs+9aRWxnN8erLWEOehAKUTeNBoUbA6HPEZPlRo7KDi2ZcNveoZgK9MA==