decap-cms Documentation

File: README.md

A CMS for static site generators. Give teams a simple way to edit and add content to any site built with a static site generator.

Decap CMS is the new name of Netlify CMS since February 2023.

Join us on Discord for community chat.

How It Works

Decap CMS is a single-page app that you pull into the /admin part of your site.

It presents a clean UI for editing content stored in a Git repository.

You setup a YAML config to describe the content model of your site, and typically
tweak the main layout of the CMS a bit to fit your own site.

When a user navigates to /admin/ they'll be prompted to log in, and once authenticated
they'll be able to create new content or edit existing content.

Read more about Decap CMS Core Concepts.

Installation and Configuration

Decap CMS can be used in two different ways.

A quick and easy install that requires a single HTML file and a configuration file. All CMS JavaScript and CSS are loaded from a CDN.
Learn more in the Quick Start Guide.
A complete, more advanced install that gives you more flexibility but requires a static site builder with a build system that supports npm packages.

Need centralized user management, advanced roles, a database proxy, or premium support? Explore Decap Turbo.

Contribute

New contributors are always welcome! Check out CONTRIBUTING.md to get involved.

Change Log

This project adheres to Semantic Versioning.
Every release is documented on the GitHub Releases page.

License

Decap CMS is released under the MIT License.
Please make sure you understand its implications and guarantees.

Expert Services

Get hands-on help from Decap experts and partners for onboarding, custom feature development, website development and premium support.

Explore expert services

File: cypress/utils/README.md

Utilities for integration tests

Utils in this dir must be explicitly included in each spec file, e.g.:

text

import '../utils/dismiss-local-backup';

For routines to be executed on all tests, please use the cypress/plugins.index.js file instead: https://docs.cypress.io/guides/core-concepts/writing-and-organizing-tests.html#Plugin-files

File: cypress/Readme.md

Cypress Tests Guide

Introduction

Cypress is a JavaScript End to End Testing Framework that runs in the browser.

Cypress tests run with a local version of the CMS.

During the setup of a spec file, the relevant index.html and config.yml are copied from dev-test/backends/ to dev-test.

Tests for the test backend use mock data generated in dev-test/backends/test/index.html.

Tests for the other backends use previously recorded data and stub fetch calls. See more about recording tests data here.

Run Tests Locally

bash

npm run test:e2e # builds the demo site and runs Cypress in headless mode with mock data

Debug Tests

bash

npm run develop # starts a local dev server with the demo site
npm run test:e2e:exec # runs Cypress in non-headless mode with mock data

Recording Tests Data

When recording tests, access to the relevant backend API is required, thus one must set up a .env file in the root project directory in the following format:

bash

GITHUB_REPO_OWNER=owner
GITHUB_REPO_NAME=repo
GITHUB_REPO_TOKEN=tokenWithWritePermissions
GITHUB_OPEN_AUTHORING_OWNER=forkOwner
GITHUB_OPEN_AUTHORING_TOKEN=tokenWithWritePermissions

GITLAB_REPO_OWNER=owner
GITLAB_REPO_NAME=repo
GITLAB_REPO_TOKEN=tokenWithWritePermissions

BITBUCKET_REPO_OWNER=owner
BITBUCKET_REPO_NAME=repo
BITBUCKET_OUATH_CONSUMER_KEY=ouathConsumerKey
BITBUCKET_OUATH_CONSUMER_SECRET=ouathConsumerSecret

NETLIFY_API_TOKEN=netlifyApiToken
NETLIFY_INSTALLATION_ID=netlifyGitHubInstallationId

The structure of the relevant repo should match the settings in config.yml

To start a recording run the following commands:

bash

npm run develop # starts a local dev server with the demo site
npm run mock:server:start # starts the recording proxy
npm run test:e2e:record-fixtures:dev # runs Cypress in non-headless and pass data through the recording proxy
npm run mock:server:stop # stops the recording proxy

During the recorded process a clone of the relevant repo will be created under .temp and reset between tests.

Recordings are sanitized from any possible sensitive data and transformed into an easier to process format.

To avoid recording all the tests over and over again, a recommended process is to:

Mark the specific test as only by changing it("some test... to it.only("some test... for the relevant test.
Run the test in recording mode.
Exit Cypress and stop the proxy.
Run the test normally (with mock data) to verify the recording works.

Debugging Playback Failures

Most common failures are:

The recorded data is not transformed properly (e.g. sanitization broke something).
The stubbed requests and responses are not matched properly (e.g. timestamp changes in request body between recording and playback).

Dumping all recorded data as is to a file here and adding a debugger; statement here is useful to gain insights.

Also comparing console log messages between recording and playback is very useful (ordering of requests, etc.)

File: packages/decap-server/README.md

Decap CMS Proxy Server

Decap CMS Proxy Server is an express server created to facilitate local development.

How It Works

Navigate to a local Git repository configured with the CMS.
Run npx decap-server from the root directory of the above repository.
Update your config.yml to connect to the server:

yaml

backend:
  name: proxy
  proxy_url: http://localhost:8081/api/v1
  branch: master # optional, defaults to master

Start you local development server (e.g. run gatsby develop).

Custom Configuration

Create a .env file in the root directory of your local Git repository.
Update the file as follows:

bash

# optional, defaults to current directory
GIT_REPO_DIRECTORY=FULL_PATH_TO_LOCAL_GIT_REPO
# optional, defaults to 8081
PORT=CUSTOM_PORT
# optional, only listen for incoming connections on a specific IP address
BIND_HOST=127.0.0.1
# optional, restrict API requests to a specific origin. Default is /^https?:\/\/(localhost|127\.0\.0\.1)(:\d+)?$/ to allow requests from localhost and 127.0.0.1.
ORIGIN=https://example.com