Creating a blog with Bridgetown and Netlify CMS
This is a quick tutorial to showcase how you can quickly integrate Netlify CMS into your Bridgetown site.
The code for this tutorial can be found at:
{% github andrewmcodes/bridgetown-netlify-cms-starter no-readme %}
Let’s get started!
Setup
For detailed instructions on getting Bridgetown set up on your local machine, take a look at the Bridgetown Getting Started Documentation and the Bridgetown Installation Guides.
The TL;DR is you need Ruby >= 2.5, Bundler, Node >= 10.13, Yarn, and the Bridgetown gem installed.
You can install the gem by running the following command in your terminal:
gem install bridgetown
As far as the other dependencies go, you don’t have to use the same versions that I am as long as you meet the minimum requirements above, but this is what I am currently using:
- Ruby 2.7.1
- Bundler 2.4.1
- Node 13.11.0
- Yarn 1.22.4
Creating a new Bridgetown site
The first thing we are going to do is generate a new Bridgetown site.
Run the following command in your terminal:
bridgetown new bridgetown-netlify-cms-starter
cd bridgetown-netlify-cms-starter
Our new site has been generated! :tada:
Let’s take a look! Run yarn start in your terminal and open http://localhost:4000 in your browser.
Optional Styling
Just to make this a little prettier, I am going to add new.css, which just adds styles to your default HTML. If you’d like to do the same, add the following in your head component at src/_components/head.liquid:
<!-- src/_components/head.liquid -->
<link rel="stylesheet" href="https://fonts.xz.style/serve/inter.css">
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@exampledev/new.css@1.1.2/new.min.css">
And remove the contents of frontend/styles/index.scss.
Adding Netlify CMS to your site
I won’t be going in great depth about the specific features of Netlify CMS, I encourage taking a looking at the Netlify CMS Documentation to learn more.
We are going to create an admin folder with two files: index.html and config.yml:
mkdir src/admin
touch src/admin/index.html
touch src/admin/config.yml
Paste the following inside of src/admin/index.html:
<!doctype html>
<html>
<head>
<meta charset="utf-8">
<meta http-equiv="x-ua-compatible" content="ie=edge">
<meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no">
<title>Netlify CMS</title>
<script src="https://identity.netlify.com/v1/netlify-identity-widget.js" type="text/javascript"></script>
</head>
<body>
<script src="https://unpkg.com/netlify-cms@^2.0.0/dist/netlify-cms.js" type="text/javascript"></script>
</body>
</html>
And in src/admin/config.yml
backend:
name: git-gateway # required for using Github
branch: main # the default branch you want CMS changes merged to
commit_messages: # Optional: configure the commit messages Netlify CMS will use when publishing changes
create: "feat(): :sparkles: Create "
update: "chore(): :recycle: Update "
delete: "chore(): :recycle: Delete "
uploadMedia: "feat(assets): :bento: Upload "
deleteMedia: "chore(assets): :wastebasket: Delete "
media_folder: src/images/uploads # location of where we want images uploaded via the CMS put
collections:
- name: blog # collection name
label: Blog # label in the CMS
folder: src/_posts/ # location of the files that make up the collection
extension: .md # extension of those files
format: frontmatter # format to use
create: true # allow creation of new items in this collection
slug: '---' # the slug to use when creating new items
editor:
preview: false # According to the documentation, this won't work with our setup, but I didn't try
fields: # Fields for the collection
- { label: Layout, name: layout, widget: hidden, default: post }
- { label: Title, name: title, widget: string }
- { label: Publish Date, name: date, widget: datetime }
- { label: Body, name: body, widget: markdown }
- name: pages
label: Pages
editor:
preview: false
files:
- label: Index Page
name: index
file: src/index.md
fields:
- { label: Layout, name: title, widget: hidden, default: home }
- { label: Body, name: body, widget: markdown }
- label: About Page
name: about
file: src/about.md
fields:
- { label: Title, name: title, widget: hidden, default: About }
- { label: Layout, name: layout, widget: hidden, default: page }
- { label: Permalink, name: permalink, widget: string, default: '/about/' }
- { label: Body, name: body, widget: markdown }
For more information on these config options, checkout the Netlify CMS Configuration Options Documentation
I decided what fields needed to be used by looking at the frontmatter in the example pages that Bridgetown created with the new site.
For our posts, this looks like:
---
layout: post
title: "Your First Post on Bridgetown"
date: 2020-07-10 21:04:54 -0400
categories: updates
---
and in our config for Netlify CMS:
fields:
- { label: Layout, name: layout, widget: hidden, default: post }
- { label: Title, name: title, widget: string }
- { label: Publish Date, name: date, widget: datetime }
- { label: Body, name: body, widget: markdown }
I neglected to add categories, which would be a great contribution to this repository if you are interested!
You should now be able to navigate to http://localhost:4000/admin in your browser and see this page:
For some reason, there is a weird JS issue when clicking Login with Netlify Identity locally. While not necessary, it would be great to get this working. If I or one of you figures out the solution, I will make sure to update this post!
Create GitHub repo
Create a new GitHub repository and push this code to your default branch. If you have the GitHub CLI, that process would look something like:
# I am using main as my default branch
gco -b main
git add .
git commit -m "feat: :tada: Initial" -m "Initial commit"
gh repo create bridgetown-netlify-cms-starter --public
git push --set-upstream origin main
Create Netlify site
- Log in to Netlify
- Press the ‘New site from Git’ button
- Choose your repository
- Set your build command to
yarn deploy - Set the publish directory to
output - Deploy site
Netlify Identity
In order to log in to our CMS, we need to enable Netlify Identity on the Identity tab for our new site.
Registration preferences
Before setting this, make sure you have created your first user to make your life easier (next section) I would recommend setting this to invite only vs open once you have a configured user.
External providers
I find it is way easier to use an external provider (like GitHub) and highly suggest doing the same. There is a weird bug with the invitation links that I haven’t solved yet for normal signups and this will remove that headache.
Services
Enable the Git Gateway to allow Netlify to connect your site to GitHub’s API, which is required for using Netlify CMS.
Using the CMS
Navigate to your deployed site and go to the /admin route. For example, the admin page for this starter is located at https://bridgetown-netlify-cms-starter.netlify.app/admin
Your page should look like:
Click the Continue with GitHub button. After you authenticate with GitHub, you should be redirected to your CMS!
Note: At this point, I would go back to your site settings and set the registration preferences to invite only!
Publishing
From here you should be all set! You can create a new blog post, edit content on your pages, upload images, and more!
After changing the index page for example, hit the publish button at the top of the page and publish now.
What this will do is add a commit to your GitHub repo with the changes and if Netlify is set to deploy your default branch (this is default behavior), the Netlify will automatically redeploy the site with the changes.
To go back to your site, change your url to the root, or click the user icon in the top right of the CMS and log out.
Note: there is some weird bug that pops up after it logs you out. Either refresh the page or just change the url back to your root url.
After the deploy finishes (it is very quick if you followed along), the content you changed or added should be reflected! I updated the index page, and my site now looks like:
Wrap up
From this point, you can continue changing your Bridgetown site, and configure the CMS config file as needed. Hopefully this gives you all the excuse you need to try Bridgetown! If you encounter any issues or find a bug, feel free to report it on the repository.
You can find the demo for this project here.
Happy coding!