Decap CMS — Complete Editor Reference

Complete guide to using Decap CMS on Dax Pro: logging in, the editorial interface, editing collections, managing the media library, publishing workflow, viewing history, and inviting editors. Everything an editor or site owner needs to work with content through the visual CMS.

What Decap CMS Is

Decap CMS is a web-based content management system that runs entirely in the browser. It is not a traditional CMS — there is no database, no server, no runtime. It is a single-page application (SPA) that:

1. Loads from /admin/ on your site

2. Authenticates through Netlify Identity

3. Reads your content from the Git repository via Git Gateway

4. Presents it in visual editing forms

5. Commits changes back to the Git repository when you publish

6. Triggers a rebuild, which updates the live site

The key insight: Decap CMS does not serve your site. It only edits the source files. The site itself is static HTML generated from those files at build time. The CMS is a tool for editing, not a part of the site visitors see.

This means:

  • Your site is not dependent on Decap CMS. If you disable the CMS tomorrow, the site keeps working.
  • The CMS is not a runtime. There is no "CMS server" that can go down and take the site with it.
  • Content is always in Git. Even if the CMS breaks, you can edit files directly and push.

    • This chapter covers everything an editor or site owner needs to know about working with Decap CMS on Dax Pro:

    1. Logging in — how authentication works

    2. The interface — the sidebar, the collections, the editing panel

    3. Editing collections — how to edit posts, services, pages, settings

    4. The media library — uploading and managing images

    5. Publishing — what happens when you click Publish

    6. Editorial workflow — draft, review, publish

    7. History and rollback — how to see past changes and restore them

    8. Inviting editors — how to add team members

    9. Resetting passwords — what to do when an editor forgets

    10. Common problems — the issues that block publishing

    Logging In

    Decap CMS uses Netlify Identity for authentication. Only users who have been invited by the site owner can log in.

    Accessing the CMS

    Open a browser and navigate to:

    https://yourdomain.com/admin/

    The trailing slash matters. /admin may redirect but /admin/ is the canonical path.

    Note: if you are running locally (development), the URL is http://localhost:8080/admin/. Local login works differently — see the Installation chapter.

    The login screen

    If you are not logged in, you see:

  • A login button — "Login with Netlify Identity"
  • A "Sign up" link — only visible if open registration is enabled (Dax Pro recommends Invite only, so this is usually hidden)

    • Logging in

    1. Click Login with Netlify Identity

    2. A modal opens with two options: Log in and Sign up

    3. If you have been invited and have set a password, click Log in

    4. Enter your email and password

    5. Click Log in

    You are redirected to the CMS dashboard.

    If you have been invited but have not set a password

    1. Check your email for an invitation from Netlify

    2. Click the invitation link

    3. Set a password

    4. You are redirected to the CMS, already logged in

    5. On future visits, use the login button with the password you set

    If you have not been invited

    You cannot log in. Contact the site owner and ask to be invited. The site owner adds you via Netlify → Identity → Invite users.

    Session duration

    Your login session lasts until:

  • You log out
  • The session expires (typically 1 hour of inactivity)
  • You clear browser cookies

    • If you are working on a long editing session, the CMS may ask you to log in again when you click Publish. This is normal — it is a security feature.

    The Interface

    After logging in, you land on the Decap CMS dashboard. The interface has three main areas:

    The left sidebar

    The sidebar lists all collections. Each collection is a group of content:

  • ⚙ Settings — site metadata, navbar, footer
  • 🧭 Navbar — navigation items
  • 🦶 Footer — footer structure
  • 🏠 Homepage — homepage sections
  • 📝 Posts — blog articles
  • 🛠 Services — service pages
  • 📄 Pages — static pages (About, Privacy, Terms, License)
  • ✉ Contact Page — contact page content

    • Click a collection to expand it. If the collection is a folder collection (like Posts or Services), it shows a list of entries. If it is a file collection (like Settings or Navbar), it shows a single file that represents the collection.

    The main panel

    When you click a collection, the main panel shows:

  • For folder collections — a list of entries (posts, services) with title, date, and status
  • For file collections — a single entry (the metadata, navbar, or footer) ready to edit

    • The main panel is where you do all the work: browsing, editing, publishing.

    The top toolbar

    The top of the main panel has three buttons:

  • Save — saves the current entry as a draft (does not publish)
  • Publish — commits the change to Git and triggers a rebuild
  • ⋯ (more) — additional actions: Delete, View on site, Editorial workflow (if enabled)

    • The status indicator at the top shows whether there are unpublished changes in the current entry.

    The media library

    The media library is accessible from any image field. It shows all images in public/images/, allows uploading new images, and selects images for the current field.

    Editing Collections

    The editing workflow is the same for every collection. The differences are the fields available.

    Folder collections (Posts, Services, Pages)

    To edit an existing entry:

    1. Click the collection in the sidebar (e.g., 📝 Posts)

    2. The main panel lists all entries

    3. Click an entry to open it

    4. Edit the fields in the form

    5. Click Publish to save and deploy

    To create a new entry:

    1. Click the collection in the sidebar

    2. Click New [Post / Service / Page] in the top-right

    3. Fill in the fields

    4. Click Publish

    To delete an entry:

    1. Open the entry

    2. Click ⋯ in the top-right

    3. Choose Delete entry

    4. Confirm

    File collections (Settings, Navbar, Footer, Homepage, Contact)

    To edit:

    1. Click the collection in the sidebar

    2. Click the single entry that appears

    3. Edit the fields

    4. Click Publish

    File collections have a single entry. You cannot create new ones — the file path is fixed in config.yml.

    The form fields

    Each field has a label and an input:

  • String — single-line text input
  • Text — multi-line textarea
  • Markdown — rich text editor with formatting toolbar
  • Image — image picker (opens the media library)
  • Date — date picker
  • Boolean — toggle switch
  • List — a repeatable group of items
  • Object — a nested group of fields
  • Select — dropdown

    • Field validation

    Decap CMS validates fields as you type. If a required field is empty, the field shows a red border and the Publish button may be disabled.

    Common validation errors:

  • Required field is empty — fill it in
  • Date format is wrong — use the date picker
  • Image path is invalid — re-select the image from the media library
  • URL is malformed — check for missing https:// or typos

    • If you cannot publish, scroll through the form to find the field with the red border. The error is there.

    The Media Library

    The media library manages all uploaded images.

    Opening the media library

    1. Open any entry with an image field

    2. Click the image field or the Choose an image button

    3. The media library opens

    Uploading a new image

    1. Click Upload in the top-right of the media library

    2. Choose a file from your computer

    3. The image uploads to public/images/ with its original filename

    4. The image appears at the top of the library

    5. Click the image to select it for the current field

    6. Close the media library (or click outside)

    Selecting an existing image

    1. The media library shows all existing images in a grid

    2. Click any image to select it

    3. The field updates with the image path

    The image path

    After selecting, the field shows a path like /images/filename.webp. This is what gets saved to the frontmatter.

    File naming

    Decap CMS preserves uploaded filenames. hero-dotnet-enterprise.webp stays hero-dotnet-enterprise.webp. Rename files before uploading to keep paths clean.

    Good filenames:

  • hero-main.webp
  • post-why-static-sites-win.webp
  • service-architecture.webp
  • og-default.jpg

    • Bad filenames:

  • IMG_20260512_143022.jpg (meaningless, hard to find later)
  • My Image.JPG (spaces and uppercase)
  • Screenshot 2026-05-12 at 3.45.22 PM.png (long, unhelpful)

    • Overwriting files

    If you upload a file with the same name as an existing file, Decap CMS overwrites it. This updates every place that references the file.

    To avoid accidental overwrites: use unique, descriptive filenames. If you need to update an image, upload a new version with a different name and update the reference.

    External image URLs

    You do not have to upload an image. The image field also accepts a URL. Paste any URL to an external image:

  • Unsplash — https://images.unsplash.com/photo-1234567890?w=1200&q=80&auto=format&fit=crop
  • Your CDN — https://cdn.example.com/images/hero.webp
  • Any public image URL — https://example.com/image.jpg

    • External URLs are not uploaded; they are referenced. The image loads from the external source.

    Publishing

    Publishing is the moment a change goes live. Understanding what happens is important.

    What Publish does

    When you click Publish:

    1. Decap CMS serializes your form fields back to YAML or Markdown

    2. It commits the file to your Git repository via Git Gateway

    3. A commit message is generated automatically (usually something like "Create Post 'Title'" or "Update Settings")

    4. Netlify detects the commit

    5. Netlify rebuilds the site (runs dotnet run -- build)

    6. The built site deploys to the CDN

    7. The change is live — typically within 60 seconds

    You do not need to do anything else. The entire pipeline is automated.

    Watching the deploy

    1. Open Netlify dashboard for your site

    2. Click Deploys

    3. The new deploy appears at the top, in progress

    4. Click it to see the build log

    5. When it completes (green check), the change is live

    If the deploy fails: the log shows the error. Common causes: YAML syntax error in the file (Decap CMS usually catches these before committing), .NET SDK issue (rare), or a content reference that breaks the build.

    Draft vs Publish

    Draft (Save) — saves the entry without committing to Git. The change is not deployed. The entry remains in the CMS but the live site is unchanged.

    Publish — commits to Git and deploys. The live site updates.

    Most edits should be published immediately. Drafts are useful when you are editing a long entry and want to save progress without deploying.

    Note: draft state is stored in Decap CMS's local storage. If you clear your browser data or switch devices, drafts are lost. Only Publish persists changes.

    Editorial Workflow

    If you enabled Editorial Workflow in config.yml, entries go through a review process before going live:

  • Draft — the entry is being written
  • In Review — the entry is submitted for review
  • Ready — the entry is approved and waiting for publish

    • To enable editorial workflow, add this to config.yml:

    publish_mode: editorial_workflow

    For a solo site owner, editorial workflow adds friction without value. Skip it.

    For a team with multiple editors and reviewers, editorial workflow ensures that only approved content goes live. It uses Git branches and pull requests under the hood.

    Dax Pro's default: editorial workflow is disabled. Content goes live on Publish. Enable it only if you need it.

    History and Rollback

    Every change to your site is a Git commit. This means you have a complete history of every edit, and you can restore any previous version.

    Viewing history in Decap CMS

    The CMS does not show a built-in history view. To see history, use GitHub.

    Viewing history in GitHub

    1. Open your repository on GitHub

    2. Click Commits — this shows every commit with:

    - The commit message (e.g., "Create Post 'Why Static Sites Win'")

    - The author (the email associated with the Identity user)

    - The date and time

    - The files changed

    3. Click any commit to see what changed

    Rolling back a single file

    1. Open the file in GitHub (e.g., content/posts/why-static-sites-win.md)

    2. Click History

    3. Find the commit before the change you want to undo

    4. Click the commit, then click View file (to see the file at that commit)

    5. Copy the content

    6. Return to the file at HEAD, edit it, paste the old content

    7. Commit via GitHub's UI

    This is a manual process. For frequent rollbacks, it may be easier to use the CMS to re-edit the content.

    Rolling back via Netlify

    Netlify keeps every deploy. You can restore the entire site to a previous deploy:

    1. Open Netlify dashboard

    2. Click Deploys

    3. Find the deploy you want to restore

    4. Click it

    5. Click Publish deploy (or Restore this deploy depending on the interface version)

    The site immediately reverts to the state of that deploy. The source code in Git is unchanged — only the served version.

    Note: publishing an old deploy does not revert the source. If you make a new commit afterward, the site jumps back to the new state. To permanently revert, you must also revert the source in Git.

    When to roll back

  • A change broke the site — the deploy failed or the site looks wrong
  • Content was published by mistake — revert to before the mistake
  • You want to A/B test — publish deploy A, then deploy B, then restore deploy A

    • For most situations, editing the content through the CMS is easier than rolling back. Rolling back is for emergencies and major mistakes.

    Inviting Editors

    Only invited users can log in to Decap CMS. To invite someone:

    Step 1: Open Netlify Identity

    1. Open Netlify dashboard for your site

    2. Click Integrations → Identity (or Site configuration → Identity depending on the interface)

    3. The Identity dashboard shows the current user list

    Step 2: Invite the user

    1. Click Invite users

    2. Enter the email address

    3. Click Send

    Step 3: The editor receives an invitation

    1. Netlify sends an invitation email

    2. The editor clicks the invitation link

    3. They set a password

    4. They are redirected to the CMS, already logged in

    5. They can now edit content

    The editor does not need a GitHub account. Git Gateway handles the Git commits on their behalf using the site owner's personal access token.

    Managing existing editors

    In Netlify Identity, you can:

  • See all users — the user list
  • Confirm pending users — users who have not yet accepted their invitation
  • Remove users — revoke access immediately
  • Reset passwords — send a password reset email

    • To remove an editor: click the user's name, click Delete user, confirm. They are logged out and cannot log in again.

    Resetting Passwords

    If an editor forgets their password:

    Step 1: They use the "Forgot password" link

    1. On the login screen, click Forgot password? (if visible)

    2. Enter their email

    3. Netlify sends a password reset email

    4. They click the link, set a new password

    The "Forgot password" link is only visible if it is enabled in Netlify Identity settings. If it is not visible, use the manual method.

    Step 2: Or, the site owner resets it manually

    1. Open Netlify Identity

    2. Find the user

    3. Click their name

    4. Click Send password recovery

    5. The editor receives an email to reset their password

    Step 3: If email is not working

    If the editor is not receiving emails:

    1. Check their spam folder

    2. Check their email address in Netlify Identity — is it spelled correctly?

    3. Remove the user and re-invite them (this creates a fresh invitation)

    4. Check Netlify Identity's email settings — some configurations use a generic sender that may be flagged as spam

    Common Decap CMS Problems

    Problem 1: /admin/ shows a blank page.

    The Decap CMS JavaScript failed to load. Causes:

  • The admin/index.html file is missing — check public/admin/index.html in the repository
  • The Decap CDN is down — rare, but if unpkg.com is unreachable, the CMS does not load. Try again in a few minutes
  • Content Security Policy blocks the script — if you added a CSP header, it may block the CMS. Check the browser console for CSP errors

    • Fix: check the browser console (F12). The error tells you what failed to load.

    Problem 2: "Login failed" error.

    The Identity credentials are wrong or expired. Causes:

  • Wrong password — use "Forgot password" to reset
  • The user was not invited — check the Identity user list
  • The invitation expired — invitations expire after 7 days. Re-invite

    • Problem 3: "Failed to persist entry" on Publish.

    The CMS cannot commit to GitHub. Causes:

  • Git Gateway is disabled — enable it in Netlify Identity settings
  • The personal access token is expired — regenerate on GitHub, paste into Netlify Git Gateway settings
  • The token lacks repo scope — regenerate with the correct scopes
  • The repository is archived or read-only — unarchive it on GitHub

    • Problem 4: Publishing works but the site does not update.

    The commit succeeded but the rebuild failed. Causes:

  • The build is still running — wait 60 seconds
  • The build failed — check Netlify → Deploys → the failed deploy log
  • Browser cache — hard-refresh (Ctrl + Shift + R)

    • Problem 5: A field shows the wrong value after saving.

    The CMS may be caching old data. Causes:

  • Browser cache — hard-refresh the CMS page
  • The build has not run — the CMS shows the source file, not the built site; the source is correct, the site will update after the build

    • Problem 6: Editor can log in but cannot see any content.

    Git Gateway is configured but the editor's permissions are limited. Causes:

  • The Git Gateway token is missing or wrong — check Netlify Identity settings
  • The repository is private and the token lacks access — regenerate the token with access to the specific repository

    • Problem 7: Uploading an image fails.

    The media library cannot write to public/images/. Causes:

  • The media_folder path is wrong — check public/admin/config.yml
  • Git Gateway cannot write — check the token permissions
  • The image is too large — some Git providers limit file size. Compress the image and try again

    • Problem 8: The CMS is slow.

    Decap CMS loads content from Git on every visit. Causes:

  • Many entries — if you have hundreds of posts, the CMS loads them all. This is slow but works
  • Slow network — the CMS depends on GitHub's API. Check your connection
  • Browser extensions — some ad blockers interfere with the CMS. Try an incognito window

    • Problem 9: Editor sees "Unauthorized" or "403".

    The editor is authenticated but lacks permission to write. Causes:

  • Git Gateway is disabled — enable it
  • The token is wrong — regenerate and re-paste

    • Problem 10: Changes made in CMS do not appear in Git.

    The commit did not happen. Causes:

  • The editor clicked "Save" (draft) instead of "Publish" — draft mode does not commit
  • The commit failed silently — check the browser console for errors
  • The Git Gateway is slow — sometimes commits take 30 seconds to appear. Wait and refresh

    • Best Practices

    1. One change per publish. Publishing a large batch of edits at once makes it hard to roll back if something breaks. Publish incrementally.

    2. Preview before publishing. After editing, scroll through the preview (if enabled) or open the live site in a new tab to verify the change looks right.

    3. Use descriptive commit messages. The CMS auto-generates messages based on the entry title. If you make structural changes, add a note in the field description so the commit message is clear.

    4. Log out after editing on shared devices. Sessions last up to an hour. If you are on a shared computer, log out explicitly.

    5. Do not edit the same entry from two devices. Concurrent edits conflict. One person's change overwrites the other. Coordinate if you have multiple editors.

    6. Keep the media library clean. Delete unused images periodically. A bloated public/images/ slows down the media library.

    7. Back up before major changes. Before a large content migration, download a ZIP of the repository from GitHub. This is your safety net.

    8. Use the editorial workflow only if you need it. For solo editors, it adds friction. For teams, it prevents accidents.

    What You Have Now

    After this chapter, you can:

  • ✅ Log in to Decap CMS at /admin/
  • ✅ Navigate the sidebar and collections
  • ✅ Edit existing entries and create new ones
  • ✅ Use the media library to upload and select images
  • ✅ Publish changes and watch the deploy
  • ✅ Use draft mode when appropriate
  • ✅ Understand editorial workflow and when to enable it
  • ✅ View history in GitHub and roll back via Netlify
  • ✅ Invite editors and manage access
  • ✅ Reset passwords
  • ✅ Fix the ten most common Decap CMS problems
  • ✅ Follow best practices for editorial work

Decap CMS is the editorial layer of your site. Once installed and configured, it is where most of your content work happens. The faster you get comfortable with it, the less time you spend on tooling and the more time you spend on content.

The next chapter is Troubleshooting — a central reference for the most common issues across the entire Dax Pro stack: build errors, deploy failures, CMS problems, DNS issues, and everything else.

→ Continue to Troubleshooting