If so you may want to check out this repo instead
This repo is for using Netlify-CMS in order to edit the documentation and blog posts found in the default website built using Docusaurus version 1. According to the official website, version 2 is not ready for production
- Video demo: https://www.loom.com/share/cb7066a1e55542608b4fa911ce2891c1
- Live demo site: https://elegant-galileo-a5ce1d.netlify.app/
☝️ If you want to test locally then skip ahead to the test locally section. Otherwise, read below for how you can setup this project from scratch
The following are required to complete the step-by-step tutorial below:
- Github account (www.github.com)
- Git CLI and Github CLI installed
- Netlify account (www.netlify.com)
☝️ Please replace [projectName] with your desired title for the project e.g. myApp
- Create project folder in your desired location using
mkdir [projectName] && cd [projectName] - Inside the project folder, run the command
npx docusaurus-init - Try the default website on localhost by running the command
cd website && yarn start. Visithttp://localhost:3000on your browser and confirm the default site is working
☝️ Note that the default site provides example markdown files in the /docs and /website/blog folders. We will be using Netlify CMS
- Before we set up Netlify CMS, we need to have deployed the project to Github (or alternatively, where ever we intend to host the project). We can do running the Git and Github CLI commands from the root of the project as follows:
- Initialize the local git repo:
git init - Stage the new files to the git repo:
git add . - Update the local repo with the staged files:
git commit -m 'Initial commit' - Create a remote repo on github using Github CLI:
gh repo create [projectName](be sure to confirm adding the new repo as a remote) - Update the remote repo with the staged files:
git push -u origin master
- Initialize the local git repo:
- According to Netlify docs, the first step to configure Netlify CMS requires creating the necessary configuration files within an
adminfolder. We can do so by using the following commandsmkdir admin && cd admintouch index.htmltouch config.yml
- The
index.htmlfile will load the Netlify CMS application. We can do so by modifyingindex.htmlwith the following code:<!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 Netlify CMS --> <script src="https://unpkg.com/netlify-cms@^2.0.0/dist/netlify-cms.js"></script> </body> </html> - The
config.ymlfile will provide the configuration settings used by Netlify CMS for editing the identified files. We can configureconfig.ymlto use Github authentication and edit the files in thedocsandblogfolder by adding the following code:
☝️ Replace [github-username] with your github username
backend:
name: github
branch: master # Branch to update (optional; defaults to master)
repo: [github-username]/[projectName]
# These lines should *not* be indented
media_folder: "static/images/uploads" # Media files will be stored in the repo under static/images/uploads
public_folder: "/images/uploads" # The src attribute for uploaded media will begin with /images/uploads
collections:
- name: blog
label: "blog"
folder: website/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:
- { name: title, label: Title, widget: string }
- { name: author, label: Label, widget: string }
- { name: authorURL, label: "Author URL", widget: string }
- { name: authorFBID, label: "Author FBID", widget: number }
- { name: body, label: Body, widget: markdown }
☝️
Note that the 'blog' collection reflect is based on the default structure for the markdown files in the blog folder. More information on widgets for Netlify
- Visit the
localhost:3000/adminand authorize connection with Github profile - Once logged in, you will view the Netlify CMS admin section where you can view a list of the markdown files in the
docsfolder! - Select any of the files from the list and update any of the fields then click on the button
Publish nowin the upper right-hand corner. NetlifyCMS will update the remote repo identified in theconfig.yml - You can view these changes on your local repo by downloading the changes to the remote repo using the command
git pull. Once completed, revisitlocalhost:3000in order to view changes
-
According to the official docs for deploying to Netlify, your website can be deployed to Netlify using the following steps:
- Login to Netlify
- Create a new site from Github by clicking on
New Site from Git - Select Github and your project's repository
- In the Build Settings, use the following:
- Choose the
masterbranch - Enter the build command as
cd website; npm install; npm run build; - Enter the publish directory as
website/build/[projectName] - Click on
Deploy Sitebutton
- Choose the
-
Now your site should be successfully deployed to Netlify 😌 ! However, if you visit
/adminat the Netlify generated domain, you may be faced with an error similar to "No authentication provider":sweat_smile: . You may choose to use Netlify Identity or a custom authentication provider however we will utilize Github for this tutorial. -
You can add Github as an authentication provider using the following steps:
- Create a Github OAuth app at this link
- Visit the Netlify console to install a new OAuth provider via
Site Settings > Access control > OAuth > Authentication Providers > Install Provider. - Copy the Client ID and Client Secret for the Github OAuth app over to Netlify
- Create a Github OAuth app at this link
-
Reload the site at the deployed URL and then you will be able to access the Netlify console at the deployed URL just like you can on
http://localhost:3000
- Clone repo to local machine by running the command
git clone https://github.com/sajclarke/docusaurus-netlifycms.git - Install dependencies using
cd website && yarn - Deploy to localhost using
yarn start
MIT Licence View LICENSE