Understanding netlify CMS
Table of Contents
I had a lot of trouble understanding the netlify documentation, and the templates were far too busy for me to understand what netlify actually does. This document goes through the most basic config to connect a github repository to netlify, without deciding how you create your site. Additionally, we will see how to use only the authentication and cms parts of netlify smoothly.
The basic repository exists here: https://github.com/nikonikoniko/netlify-bones
0.0.1 Set up a git repository
First, we set up a bare bones repository:
mkdir netlify-bones cd netlify-bones touch readme.md echo "# Hello World" > readme.md git init . git add . git commit -m "initial commit"
in my case, I created a repository on github to host these files. Github will give me a url that I can link to this repository. I connect and push my readme document with:
git remote add origin git@github.com:nikonikoniko/netlify-bones.git git push origin master
1 Connect Netlify to the Repository
Inside of the netlify admin, (which should already be linked to your github)
Next you need to “add a new site from git” TODO real button
You need to give github access to your newly created repository.
For now, leave the build command
as well as the rest blank. After the deploy was finished, I was able to access my readme file at: https://serene-almeida-d05db6.netlify.app/readme.md
In this step, netlify added itself to your github repo. You should be able to see it if you go to the repository settings > integrations
Now, whenever you push to master on this repository, it will be deployed to the above URL. Try editing the readme and then pushing to master. You should see the changes you made being reflected in the above url.
is this step necessary just for the cms?
2 Install Netlify CMS
Netlify CMS is a 1 page app, which lives at /admin
on your website. Whichever static site, or build script you decide to use, for the netlify CMS to work, it will have to be hosted at /admin.
Let’s create the directory and the necessary files for the admin:
mkdir admin touch admin/index.html touch admin/config.yml
The config file makes your data types
, as well as having other crucial information about your website. The config file seems to describe the ORM.
A simplest config file should look like this:
# admin/config.yml backend: name: git-gateway branch: master media_folder: media # public_folder: /assets collections: - name: "pages" label: "Pages" label_singular: "Page" # Used in the UI, ie: "New Post" folder: "content" create: true fields: - { label: "Title", name: "title", widget: "string", required: false} - { label: "Publish Date", name: "date", widget: "datetime", required: false } - { label: "Subtitle", name: "subtitle", widget: "string", required: false} - { label: "Cover", name: "cover", widget: "image", required: false} - { label: "Tags", name: "tags", widget: "string", required: false } - { label: "Body", name: "body", widget: "markdown", required: false }
Then, your index file should look like this: https://github.com/nikonikoniko/netlify-bones/blob/master/admin/index.html
I am not sure if this is a standard file, or if it is just the one I copied from one of the netlify examples.
This single page app will read the markdown
files you have in your repository. Let’s create them here:
mkdir content touch content/page1.md touch content/page2.md echo "# page1 title" > content/page1.md echo "# page2 title" > content/page2.md
3 Enabling Necessary Netlify Services
If you now try to visit your website admin, at https://serene-almeida-d05db6.netlify.app/admin, you will notice a message welcoming you to log in. However, it will not work yet.
From the netlify control panel, click on your website “site settings”. Here, you should see an identity panel, where you can click on “enable identity”
I also set registration to closed.
Under Identiy > Services, you should also be able to enable “git gateway”
When you do this, Netlify gets a lot more permissions to your Github account. It is allowed to push code there, so it has github api access and an api key.
After this, you must add an admin user to the website, in the Netlify dashboard “Identity” tab
(note, i had to prepend /admin/
to the invite link that i received in the email, not sure why)
4 Checking out the admin
At this point, you can access the admin app of your website at https://serene-almeida-d05db6.netlify.app/admin. You should now see two blank markdown pages page1
and page2
from before. You can now edit these and add titles and so on.
5 Hosting the website yourself
In case you want to host the website yourself, you can deploy the repository to your own server.
In this case, I cloned my repository on my own server using
git clone https://github.com/nikonikoniko/netlify-bones.git
This process is a little tricky, to use Netlify CMS only for authentication and connection to git. IE, only for hosting the CMS functions, and not for building or deploying the site at all.
according to this github issue, It will not work with the Identity widgets, so you need to remove
<script src="https://identity.netlify.com/v1/netlify-identity-widget.js"></script>
from admin/index.html
. note - these changes have already been done in the given repository.
admin/config.yml
should be edited to look like this:
backend: name: git-gateway branch: master identity_url: "https://serene-almeida-d05db6.netlify.app/.netlify/identity" gateway_url: "https://serene-almeida-d05db6.netlify.app/.netlify/git" base_url: https://api.netlify.com auth_endpoint: auth
After these changes have been made, the website admin should be available at: https://niko.io/projects/netlify-bones/admin
If not, see this stackoverflow issue, it might help with working with the widget as well. Once these steps have been done, you can host your website however you want, on your own server, but have the content and authentication be managed by netlify.