static-cms/website/content/docs/docusaurus.mdx

---
group: Guides
title: Docusaurus
weight: 80
---
This guide instructs you on how to integrate Static CMS with Docusaurus.

### Before you begin

* Sign up for [GitHub](www.github.com) and [Netlify](www.netlify.com).
* Download [Node.js](https://nodejs.org/en/download/) version 14 or above.
* Install the [GitHub CLI](https://cli.github.com/).
* Install and authenticate the [Netlify CLI](https://docs.netlify.com/cli/get-started/).

## Create a new Docusaurus project

```bash
# 1. Use Docusaurus to create a site scaffold.
npx create-docusaurus@latest my-website classic

# 2. Run the development server.
cd my-website
npm run start
```

A browser window opens at `http://localhost:3000`. 

The development server now serves your website at `http://localhost:3000`. As you edit the source files in `/my-website/`, you can visit `http://localhost:3000` to preview your changes.

## Push your project to GitHub

Static CMS requires a [backend](/docs/backends-overview/) to store content. Static CMS supports using Git hosts, like GitHub or GitLab, as backends. This guide uses GitHub. 

```bash
# 1. Initialize your local Git repository.  
git init

# 2. Rename your initial branch to match GitHub.
git branch -m main

# 3. Stage all your local files to your repository.
git add . 

# 4. Commit your staged changes.
git commit -m 'Initial commit'

# 5. Create a remote repository on GitHub using the GitHub CLI.
gh repo create my-website
```

Don't add a license or a .gitignore. Do add an "origin" git remote.

![](/img/create-remote-repo.webp)

```bash
# 6. Update your remote repository with your staged changes. 
git push -u origin main
```

## Publish your project using Netlify CLI

1. Connect Netlify CLI to your GitHub repository.
   ```bash
   netlify init
   ```
2. Choose `Create & configure a new site`.
3. Choose your team and site name.
4. Choose `yarn build` for your build command.
5. Choose `build` for your deployment directory.

![](/img/create-remote-repo.webp)

Choose the default option for everything else. 

Your website is now deployed. Netlify provides you with a randomly generated domain name. Run `netlify open --site` to view your deployed site.

## Add Static CMS to your project

### Before you begin

1. Remove all existing posts from `/blog`.
   ```bash 
   rm -rf ./blog/*
   ```
2. Create a new blog post post titled `2021-11-15-first-blog-post.md`.
   ```bash
   touch ./blog/2021-11-15-first-blog-post.md
   ```
3. Edit `2021-11-15-first-blog-post.md` to look like this:
   ```yaml
   ---
   title: First Blog Post
   slug: first-blog-post
   tags:
     - foo
     - bar
   authors:
     - title: Garrison McMullen
       title: Instruction Writer
       url: https://github.com/garrison0
       image_url: https://avatars.githubusercontent.com/u/4089393?v=4
   ---
   Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat.
   ```

### Procedure

1. Create an `admin` directory inside `static`.
   ```bash
   cd static
   mkdir admin
   ```
2.  In the `admin` directory, create a `config.yml` file and an `index.html` file.
   ```bash
   cd admin
   touch config.yml
   touch index.html
   ```
3. Edit `index.html` to look like this:
   ```html
   <!doctype html>
   <html>
   <head>
     <meta charset="utf-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
     <title>Content Manager</title>
   </head>
   <body>
     <!-- Include the script that builds the page and powers Static CMS -->
     <script src="https://unpkg.com/@staticcms/core@%5E0.1.0/dist/static-cms-core.js"></script>
   </body>
   </html>
   ```
   `index.html` displays the Static CMS admin interface. You'll use the admin interface to edit your blog posts.
4. Edit `config.yml` to look like this: 
   ```yaml
   backend:
     title: github
     branch: main 
     repo: <your-github>/my-website
   
   # These lines should *not* be indented
   media_folder: "static/img" # Media files will be stored in the repo under static/images/uploads
   public_folder: "/img/" # The src attribute for uploaded media will begin with /images/uploads
   
   collections:
   - title: blog
     label: "blog"
     folder: blog
     identifier_field: title
     extension: md
     widget: "list"
     create: true
     slug: "{{year}}-{{month}}-{{day}}-{{slug}}" # Filename template, e.g., YYYY-MM-DD-title.md
     fields:
       - { title: title, label: Title, widget: string }
       - { title: body, label: Body, widget: markdown }
       - { title: slug, label: Slug, widget: string }
       - label: "Tags"
         title: "tags"
         widget: "list"
       - label: "Authors"
         title: "authors" 
         widget: "list"
         fields:
           - { title: name, label: Name, widget: string }
           - { title: title, label: Title, widget: string } 
           - { title: url, label: URL, widget: string } 
           - { title: imageUrl, label: ImageURL, widget: string } 
   ```

   `config.yml` specifies what kind of content your blog posts have. The content specification enables Static CMS to edit existing posts and create new ones with the same format. To learn more, read about Static CMS' [](/docs/configuration-options/)[Configuration options](/docs/configuration-options/).
5. Visit `localhost:3000/admin`
   You can now view and edit `2021-11-15-first-blog-post.md` through the admin interface. You can also create new blog posts. 
   **Warning:** Any changes you publish through the admin interface will only effect your *remote GitHub repository*. To retrieve these changes locally, `git pull` from your local repository.
6. Commit and push your new changes to your remote repository. 
   ```bash
   git add . 
   git commit -m "Add Static CMS"
   git push
   ```
   Netlify builds and deploys your new changes. 

## Add GitHub as an authentication provider

Before you can access `/admin/` through your Netlify domain, you need to set up an authentication provider. The authentication provider allows Static CMS to determine whether users have read and write access to `/admin/`. This guide uses GitHub credentials for authentication. 

### Configure GitHub 

1. Create a new [GitHub OAuth application](https://github.com/settings/applications/new). 
2. Enter your Netlify domain as the **Homepage URL**.
3. Enter `https://api.netlify.com/auth/done` as the **Authorization callback URL**.
4. Click **Register application.**
5. Click **Generate a new client secret.** 
6. Copy the provided client secret and client ID.

### Configure Netlify

1. On Netlify, under `Site Settings > Access control > OAuth > Authentication Providers`, click **Install provider**.
2. Enter your client secret and client ID from GitHub.
3. Click **Install**.

🎉 All done! Now you can access the admin interface through your Netlify URL.
Add missing content folder 2022-09-30 11:39:35 -04:00			`---`
			`group: Guides`
			`title: Docusaurus`
Feature/website overhaul (#49) * Reorganize repo * Overhaul website design and rewrite in NextJS and Typescript * Delete website-publish.yml 2022-10-25 09:18:18 -04:00			`weight: 80`
Add missing content folder 2022-09-30 11:39:35 -04:00			`---`
Feature/rebrand (#27) 2022-10-02 20:06:20 -04:00			`This guide instructs you on how to integrate Static CMS with Docusaurus.`
Add missing content folder 2022-09-30 11:39:35 -04:00
			`### Before you begin`

			`* Sign up for [GitHub](www.github.com) and [Netlify](www.netlify.com).`
			`* Download [Node.js](https://nodejs.org/en/download/) version 14 or above.`
			`* Install the [GitHub CLI](https://cli.github.com/).`
			`* Install and authenticate the [Netlify CLI](https://docs.netlify.com/cli/get-started/).`

			`## Create a new Docusaurus project`

			```bash
			`# 1. Use Docusaurus to create a site scaffold.`
			`npx create-docusaurus@latest my-website classic`

			`# 2. Run the development server.`
			`cd my-website`
			`npm run start`
			```

			A browser window opens at `http://localhost:3000`.

			The development server now serves your website at `http://localhost:3000`. As you edit the source files in `/my-website/`, you can visit `http://localhost:3000` to preview your changes.

			`## Push your project to GitHub`

Update links, clean up quotes 2022-10-25 11:55:37 -04:00			`Static CMS requires a [backend](/docs/backends-overview/) to store content. Static CMS supports using Git hosts, like GitHub or GitLab, as backends. This guide uses GitHub.`
Add missing content folder 2022-09-30 11:39:35 -04:00
			```bash
			`# 1. Initialize your local Git repository.`
			`git init`

			`# 2. Rename your initial branch to match GitHub.`
			`git branch -m main`

			`# 3. Stage all your local files to your repository.`
			`git add .`

			`# 4. Commit your staged changes.`
			`git commit -m 'Initial commit'`

			`# 5. Create a remote repository on GitHub using the GitHub CLI.`
			`gh repo create my-website`
			```

			`Don't add a license or a .gitignore. Do add an "origin" git remote.`

Update images in docs 2022-10-26 09:23:11 -04:00			`![](/img/create-remote-repo.webp)`
Add missing content folder 2022-09-30 11:39:35 -04:00
			```bash
			`# 6. Update your remote repository with your staged changes.`
			`git push -u origin main`
			```

			`## Publish your project using Netlify CLI`

Clean up docusaurus docs markdown 2022-10-25 09:50:47 -04:00			`1. Connect Netlify CLI to your GitHub repository.`
			```bash
			`netlify init`
			```
			2. Choose `Create & configure a new site`.
			`3. Choose your team and site name.`
			4. Choose `yarn build` for your build command.
			5. Choose `build` for your deployment directory.
Add missing content folder 2022-09-30 11:39:35 -04:00
Update images in docs 2022-10-26 09:23:11 -04:00			`![](/img/create-remote-repo.webp)`
Add missing content folder 2022-09-30 11:39:35 -04:00
			`Choose the default option for everything else.`

			Your website is now deployed. Netlify provides you with a randomly generated domain name. Run `netlify open --site` to view your deployed site.

Feature/rebrand (#27) 2022-10-02 20:06:20 -04:00			`## Add Static CMS to your project`
Add missing content folder 2022-09-30 11:39:35 -04:00
			`### Before you begin`

Clean up docusaurus docs markdown 2022-10-25 09:50:47 -04:00			1. Remove all existing posts from `/blog`.
			```bash
			`rm -rf ./blog/*`
			```
			2. Create a new blog post post titled `2021-11-15-first-blog-post.md`.
			```bash
			`touch ./blog/2021-11-15-first-blog-post.md`
			```
			3. Edit `2021-11-15-first-blog-post.md` to look like this:
			```yaml
			`---`
			`title: First Blog Post`
			`slug: first-blog-post`
			`tags:`
			`- foo`
			`- bar`
			`authors:`
			`- title: Garrison McMullen`
			`title: Instruction Writer`
			`url: https://github.com/garrison0`
			`image_url: https://avatars.githubusercontent.com/u/4089393?v=4`
			`---`
			`Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat.`
			```
Add missing content folder 2022-09-30 11:39:35 -04:00
			`### Procedure`

Clean up docusaurus docs markdown 2022-10-25 09:50:47 -04:00			1. Create an `admin` directory inside `static`.
			```bash
			`cd static`
			`mkdir admin`
			```
			2. In the `admin` directory, create a `config.yml` file and an `index.html` file.
			```bash
			`cd admin`
			`touch config.yml`
			`touch index.html`
			```
			3. Edit `index.html` to look like this:
			```html
			`<!doctype html>`
			`<html>`
			`<head>`
			`<meta charset="utf-8" />`
			`<meta name="viewport" content="width=device-width, initial-scale=1.0" />`
			`<title>Content Manager</title>`
			`</head>`
			`<body>`
			`<!-- Include the script that builds the page and powers Static CMS -->`
			`<script src="https://unpkg.com/@staticcms/core@%5E0.1.0/dist/static-cms-core.js"></script>`
			`</body>`
			`</html>`
			```
			`index.html` displays the Static CMS admin interface. You'll use the admin interface to edit your blog posts.
			4. Edit `config.yml` to look like this:
			```yaml
			`backend:`
			`title: github`
			`branch: main`
			`repo: <your-github>/my-website`

			`# These lines should not be indented`
			`media_folder: "static/img" # Media files will be stored in the repo under static/images/uploads`
			`public_folder: "/img/" # The src attribute for uploaded media will begin with /images/uploads`

			`collections:`
			`- title: blog`
			`label: "blog"`
			`folder: blog`
			`identifier_field: title`
			`extension: md`
			`widget: "list"`
			`create: true`
			`slug: "{{year}}-{{month}}-{{day}}-{{slug}}" # Filename template, e.g., YYYY-MM-DD-title.md`
			`fields:`
			`- { title: title, label: Title, widget: string }`
			`- { title: body, label: Body, widget: markdown }`
			`- { title: slug, label: Slug, widget: string }`
			`- label: "Tags"`
			`title: "tags"`
			`widget: "list"`
			`- label: "Authors"`
			`title: "authors"`
			`widget: "list"`
			`fields:`
			`- { title: name, label: Name, widget: string }`
			`- { title: title, label: Title, widget: string }`
			`- { title: url, label: URL, widget: string }`
			`- { title: imageUrl, label: ImageURL, widget: string }`
			```

Update links, clean up quotes 2022-10-25 11:55:37 -04:00			`config.yml` specifies what kind of content your blog posts have. The content specification enables Static CMS to edit existing posts and create new ones with the same format. To learn more, read about Static CMS' [](/docs/configuration-options/)[Configuration options](/docs/configuration-options/).
Clean up docusaurus docs markdown 2022-10-25 09:50:47 -04:00			5. Visit `localhost:3000/admin`
			You can now view and edit `2021-11-15-first-blog-post.md` through the admin interface. You can also create new blog posts.
			Warning: Any changes you publish through the admin interface will only effect your remote GitHub repository. To retrieve these changes locally, `git pull` from your local repository.
			`6. Commit and push your new changes to your remote repository.`
			```bash
			`git add .`
			`git commit -m "Add Static CMS"`
			`git push`
			```
			`Netlify builds and deploys your new changes.`
Add missing content folder 2022-09-30 11:39:35 -04:00
			`## Add GitHub as an authentication provider`

Feature/rebrand (#27) 2022-10-02 20:06:20 -04:00			Before you can access `/admin/` through your Netlify domain, you need to set up an authentication provider. The authentication provider allows Static CMS to determine whether users have read and write access to `/admin/`. This guide uses GitHub credentials for authentication.
Add missing content folder 2022-09-30 11:39:35 -04:00
			`### Configure GitHub`

			`1. Create a new [GitHub OAuth application](https://github.com/settings/applications/new).`
			`2. Enter your Netlify domain as the Homepage URL.`
Clean up docusaurus docs markdown 2022-10-25 09:50:47 -04:00			3. Enter `https://api.netlify.com/auth/done` as the Authorization callback URL.
Add missing content folder 2022-09-30 11:39:35 -04:00			`4. Click Register application.`
			`5. Click Generate a new client secret.`
			`6. Copy the provided client secret and client ID.`

			`### Configure Netlify`

			1. On Netlify, under `Site Settings > Access control > OAuth > Authentication Providers`, click Install provider.
			`2. Enter your client secret and client ID from GitHub.`
			`3. Click Install.`

			`🎉 All done! Now you can access the admin interface through your Netlify URL.`