Understanding netlify CMS

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

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?

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

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)

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.

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.