Add Netlify CMS to your VuePress site

If you're using VuePress, but you want to add a bit of content management to your markdown files, Netlify CMS is the perfect choice.

It's a light-weight CMS hosted on your site that hooks directly into your Git repo, creating branches for drafts and merging your content into master when you click to publish. What I love about this CMS is that I still have complete control of my content. No vendor lock-in. No databases. Just some helpful tools to manage your markdown files, including:

  • Rich text editing and preview for your markdown files
  • Publishing workflow to manage content (draft, review, ready, publish and unpublish)
  • Configurable inputs and defaults for your frontmatter
  • Multiple author access controls (with Netlify Identity)

Rich text editor screen

If you don't already have a VuePress site, or if you just want to play with Netlify CMS, I've made a GitHub template for you which you can deploy using this magic button:

Deploy to Netlify

If you do already have a VuePress site and you want to add Netlify CMS, this tutorial is for you.

# Setup OAuth on GitHub

To keep it simple for now, we are going to set up access to the CMS with GitHub

  1. Go to your developer settings on GitHub and add a new OAuth app.
  2. Enter the name and full URL of your website and set the authorization callback URL:
https://api.netlify.com/auth/done
  1. Click Register application to get your Client ID and Client Secret. You will need these in a moment.
  2. In your site Settings, open 'Access control'. Under OAuth, click 'Install provider' and copy in the Client ID and Secret from GitHub.

# Add Netlify CMS admin files to your project

In your .vuepress folder, add a public folder and within that, add an admin folder where you will add two files:

  1. index.html
<!doctype html>
<html>

<head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>Netlify CMS</title>
</head>

<body>
    <script src="https://unpkg.com/netlify-cms@^2.0.0/dist/netlify-cms.js"></script>
</body>

</html>
  1. config.yml
backend:
  name: github
  repo: username/repository
media_folder: ".vuepress/public/media"
public_folder: "/media"
publish_mode: editorial_workflow
collections:
  - label: "Home"
    name: "home"
    files:
      - label: "Homepage"
        name: "homepage"
        file: "index.md"
        delete: false
        fields:
          - {label: Body, name: body, widget: markdown}
  - label: "Pages"
    name: "pages"
    folder: "_pages"
    create: true
    fields:
      - {label: "Title", name: "title", widget: "string"}
      - {label: "Body", name: "body", widget: "markdown"}
      - {label: "Permalink", name: "permalink", widget: "hidden", default: "/:slug"}

This config will enable you to edit your homepage, but not delete it. It will also give you the ability to create, edit and delete pages. It will manage pages in a _pages folder, so edit this if you have a different folder for your pages.

# Login to your CMS and create pages

With these files deployed, you can now access your CMS. Simply add `/admin` to the end of your website url in the browser and you will be invited to login with GitHub. Once logged in you will see a collection called Home, which contains your homepage and a collection called Pages, which will be empty or contain your existing pages.

CMS Contents screen

Now you can start using the CMS to edit and add pages.

Be aware that new pages do not appear in the pages list or on your website until they have been published, and they cannot be published until they have been marked as "Ready", so go to the workflow tab to edit your drafts.

Workflow screen

Try creating some new pages (e.g. About and Contact) and see the new branches that appear automatically in your Git repo. Netlify will publish these branches as previews, so that you can see exactly how your website will look once they have been published.

View Preview link

Set these pages as ready and then publish them. This merges the branch to master, so Netlify will build and deploy your site with your new pages, but you'll need some navigation to get to them.

Open up your .vuepress/congif.js file and add the following theme config:




 
 
 
 
 
 
 

module.exports = {
    title: 'My Website',
    description: 'Description of my website',
    themeConfig: {
        nav: [
            { text: 'Home', link: '/' },
            { text: 'About', link: '/about/' },
            { text: 'Contact', link: '/contact/' }
        ]
    }
}

Now you can get to the pages you created with your CMS.

# Next...

Netlify CMS docs

Netlify Identity docs

Join my mailing list