With the rise of JAMstack in the web development world, using static site generators like Gridsome is a no brainer. Developing with Gridsome and using markdown files is easy whether you are making static or server rendered sites. If you're writing for your blog, it comes handy. But what if you are working on a project for a client with multiple writers and editors and have no background in tech? Or let say you're building a blog platform in JAMstack for multiple users, how to do you simplify the workflow? Netlify CMS comes to the rescue.
Netlify CMS is an open source content management system for your Git workflow that enables you to provide editors with a friendly UI and intuitive workflows. It is available to most static generators like Nuxt, Gatsby, Gridsome, Hugo, etc. Markdown files are stored in your Git repository alongside your code for easier versioning, multi-channel publishing, and the option to handle content updates directly in Git. I won't explain the complete feature of Netlify CMS. To learn more about it, head over to official docs.
Enough talking and let's proceed to the tutorial.
Table of Contents
1. Getting Started
2. Integrate Netlify CMS
3. Create Netlify Site
4. Add Authentication using Netlify Identity
5. Add Netlify Identity Widget1. Getting Started
For this tutorial, we will use the official blog from the Gridsome Github repo. Clone the official example of Gridsome blog and install the dependencies.
cd workspace
git clone git@github.com:gridsome/gridsome-starter-blog.git
cd gridsome-starter-blog
yarnRun the project to make sure there are no errors.
gridsome developCheck your project at https://localhost:8080.
2. Integrate Netlify CMS.
Adding Netlify CMS in the project is easy. It takes only a few minutes to set up.
Inside the root project /static folder, add the admin folder.
static/adminInside admin folder, add config.yml and index.html.
static/admin/index.html
static/admin/config.ymlThe first file, admin/index.html, is the entry point for the Netlify CMS admin interface. The use will point to yournetlifysite/admin to access the admin page of Netlify CMS.
Now inside static/admin/index.html, paste this 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 code above is just a simple html file with preloaded Netlify CMS javascript file pulled from CDN.
The second file, config.yml, is the heart of Netlify CMS. It defines the whole architecture of your project with Netlify CMS.
And inside the static/admin/config.yml, paste this code:
backend:
name: git-gateway
branch: master # Branch to update (optional; defaults to master)
# 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" # Used in routes, e.g., /admin/collections/blog
label: "Blog" # Used in the UI
folder: "content/posts" # The path to the folder where the documents are stored
create: true # Allow users to create new documents in this collection
slug: "{{slug}}" # Filename template, e.g., YYYY-MM-DD-title.md
fields: # The fields for each document, usually in the front matter
- {label: "Title", name: "title", widget: "string"}
- {label: "Publish Date", name: "date", widget: "datetime"}
- {label: "Published", name: "published", widget: "boolean"}
- {label: "Tags", name: "tags", widget: "string"}
- {label: "Series", name: "series", widget: "boolean"}
- {label: "Featured Image", name: "cover_image", widget: "image"}
- {label: "Canonical URL", name: "canonical_url", widget: "boolean"}
- {label: "Description", name: "description", widget: "string"}
- {label: "Body", name: "body", widget: "markdown"}Here's the brief description of the code above: backend - specifies your backend protocol and your publication branch. Git Gateway is an open source API that acts as a proxy between authenticated users of your site and your site repo. media_folder - Netlify CMS allows users to upload images directly within the editor. media_folder specifies where uploaded files are saved in the repo. public_folder - indicates where they are found in the published site. collections - define the structure for the different content types on your static site.
3. Create a Netlify site
Now push your code on Github. On the root of your project:
rm -rf .git
git init
git add .
git commit -m "Initial commit"
git remote add origin <github repo>
git push -u origin masterOpen your Netlify dashboard and create a new site. Choose Github as your git provider and select your newly created repo. Wait for Netlify to finish building your site.
4. Add Authentication using Netlify Identity
Now we need to enable Netlify Identity to authenticate our users before they can access the admin page.
Go to Identity page. Select settings and usage.
Choose registration preferences.
Enable Git Gateway for authentication.
5. Add the Netlify Identity Widget.
Now we need a frontend interface to connect to Netlify CMS. Luckily for us, Netlify CMS has built-in widget for us to use. The open source Netlify Identity Widget is a drop-in widget. We need to include this widget in two places: In static/admin/index.html and In src/index.html
<script src="https://identity.netlify.com/v1/netlify-identity-widget.js"></script>Inside static/admin/index.html
<!doctype html>
<html>
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<title>Content Manager</title>
<script src="https://identity.netlify.com/v1/netlify-identity-widget.js"></script>
</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>In src/index.html:
<!DOCTYPE html>
<html ${htmlAttrs}>
<head>
${head}
<script src="https://identity.netlify.com/v1/netlify-identity-widget.js"></script>
</head>
<body ${bodyAttrs}>
<script>
...
</script>
${app}
${scripts}
</body>
</html>When a user logs in with the Netlify Identity widget, an access token directs to the site homepage. In order to complete the login and get back to the CMS, redirect the user back to the /admin/ path. To do this, add the following script before the closing body tag of your site's main index page:
<script>
if (window.netlifyIdentity) {
window.netlifyIdentity.on("init", user => {
if (!user) {
window.netlifyIdentity.on("login", () => {
document.location.href = "/admin/";
});
}
});
}
</script>Our complete src/index.html code will look like this:
<!DOCTYPE html>
<html ${htmlAttrs}>
<head>
${head}
<script src="https://identity.netlify.com/v1/netlify-identity-widget.js"></script>
</head>
<body ${bodyAttrs}>
<script>
// Add dark / light detection that runs before Vue.js load. Borrowed from overreacted.io
(function() {
window.__onThemeChange = function() {};
function setTheme(newTheme) {
window.__theme = newTheme;
preferredTheme = newTheme;
document.body.setAttribute('data-theme', newTheme);
window.__onThemeChange(newTheme);
}
var preferredTheme;
try {
preferredTheme = localStorage.getItem('theme');
} catch (err) { }
window.__setPreferredTheme = function(newTheme) {
setTheme(newTheme);
try {
localStorage.setItem('theme', newTheme);
} catch (err) {}
}
var darkQuery = window.matchMedia('(prefers-color-scheme: dark)');
darkQuery.addListener(function(e) {
window.__setPreferredTheme(e.matches ? 'dark' : 'light')
});
setTheme(preferredTheme || (darkQuery.matches ? 'dark' : 'light'));
})();
</script>
<script>
if (window.netlifyIdentity) {
window.netlifyIdentity.on("init", user => {
if (!user) {
window.netlifyIdentity.on("login", () => {
document.location.href = "/admin/";
});
}
});
}
</script>
${app}
${scripts}
</body>
</html>Save changes. And we're done!
To access the admin page of your Netlify CMS, go to your netlify-site/admin.
You can invite multiple users for your Netlify CMS via Netlify dashboard.
That's it. You now have Netlify CMS installed and configured on your Gridsome site.
