Content Editing with Decap CMS

Decap CMS is included with BlazorForge as an optional admin panel. You can edit content through a browser without touching any code or Markdown files.

This page covers local mode for development and online mode for production.

What Decap CMS Does

Decap CMS provides a browser-based editor for every piece of content in BlazorForge.

You can edit the home page, about page, contact page, journal index, services index, journal articles, service pages, site identity, SEO settings, navigation menu, footer, and global widgets.

All changes are saved as Markdown or JSON files. There is no database.

The Admin Page

Decap CMS lives in wwwroot/admin/. It has two files.

The file wwwroot/admin/index.html loads the Decap CMS JavaScript library. This file is the entry point for the admin panel.

The file wwwroot/admin/config.yml defines the collections, fields, and backend configuration.

The admin panel is available at http://localhost:5052/admin/ after you start the site.

Without index.html, the /admin/ route does not exist. That is why the file must be present.

Local Mode Setup

Local mode runs Decap CMS on your development machine. It saves changes directly to your working directory. You do not need a GitHub account, Netlify account, or any authentication setup.

Step 1: Install Node.js

Decap Server requires Node.js. If you do not have it, install it from the official Node.js website. Version 18 or later is recommended.

Verify the installation:

node --version

You should see a version number like v20.11.0.

Step 2: Install Decap Server

In a terminal, run:

npm install -g decap-server

Wait for the installation to finish. It takes thirty to sixty seconds.

Verify:

decap-server --version

If the command is not recognized, try npx decap-server --version.

Step 3: Enable Local Backend

Open wwwroot/admin/config.yml with a text editor.

At the very top of the file, add this line:

local_backend: true

Then find the backend section:

backend:
  name: github
  repo: creativitas/blazorforge
  branch: main
  base_url: https://api.netlify.com
  auth_endpoint: auth

Replace it with:

backend:
  name: git-gateway
  branch: main

Save the file.

The top of the file should now look like this:

local_backend: true

backend:
  name: git-gateway
  branch: main

media_folder: "wwwroot/images/uploads"
public_folder: "/images/uploads"

publish_mode: editorial_workflow

collections:
  ...

Step 4: Run Decap Server

Open a new terminal window and run:

npx decap-server

You should see output like:

Decap CMS Proxy Server listening on port 8081

Leave this terminal open. Decap Server must keep running while you use the CMS.

Step 5: Run BlazorForge

Open a second terminal, navigate to the BlazorForge folder, and run:

dotnet run

Wait until the terminal shows Now listening on: http://localhost:5052.

Leave this terminal open too.

You now have two terminals running at the same time. This is normal.

Step 6: Open the CMS

Open your browser and go to:

http://localhost:5052/admin/

The Decap CMS login screen appears. Because you are running in local mode, no login is required. The CMS dashboard opens automatically.

Navigating the CMS

The left sidebar shows the content collections.

Pages contains the home, about, contact, journal index, and services index.

Engineering Journal contains all journal articles.

Themes & Services contains all service pages.

Site Settings contains site identity, SEO settings, navigation, footer, and global widgets.

Editing a Page

Click Pages in the sidebar, then click Home Page.

The home page editor opens with all fields visible. These include title, slug, SEO, header CTA, hero, stats, features, showcase, testimonials, pricing, services banner, FAQ, and bottom CTA.

Change any field. Click Save in the top-right corner. The change is saved as a Markdown file in wwwroot/content/home.md.

To see the change on the site, stop the Blazor server and run dotnet run again. The Markdown compiler regenerates the metadata, and the new content appears after you refresh the browser.

Creating a Journal Article

Click Engineering Journal in the sidebar, then click New Journal Article.

Fill in the fields: title, slug, author, author role, author bio, date, category, category tag, reading time, featured toggle, tags, excerpt, cover image, cover alt, SEO overrides, and body.

The Body field is a Markdown editor with a toolbar for bold, italic, headings, links, images, and lists.

Click Save when done. The article is saved in wwwroot/content/journal/.

Uploading Images

When you click an image field, the CMS opens an image browser. Click Upload to add a new image from your computer.

The image is saved to wwwroot/images/uploads/. The path is filled into the field automatically, for example /images/uploads/my-screenshot.jpg.

The Editorial Workflow

BlazorForge uses the editorial workflow. New content starts as a draft.

When you save a new article, you see three states: Draft, In Review, and Ready.

To publish an article, open it and click the Publish button at the top.

In local mode, publishing simply moves the file from a draft folder to the main content folder. No external service is involved.

Online Mode with Netlify Identity

For production, you want to edit content from anywhere, not just your local machine. This requires an online backend.

The recommended setup uses Netlify Identity and Git Gateway. This is covered in Deploy to Netlify.

Switching Between Local and Online

The config.yml file is different for each mode.

In local mode, the top of the file contains local_backend: true and the backend is git-gateway.

In online mode, the local_backend line is removed. The backend is also git-gateway, but it works through Netlify Identity instead of the local server.

When you deploy to Netlify, you remove the local_backend line. When you work locally, you add it back.

Troubleshooting

If the CMS says it cannot connect, make sure Decap Server is running in a separate terminal.

If the login screen keeps appearing, verify that local_backend: true is at the top of config.yml and that Decap Server is running.

If images do not upload, check that the folder wwwroot/images/uploads/ exists. Create it manually if it does not.

If the CMS shows a blank white page, open the browser console with F12. The most common cause is a syntax error in config.yml. Verify indentation: two spaces per level, no tabs.

If changes do not appear on the site, stop the Blazor server and run dotnet run again. The Markdown compiler must regenerate the metadata.

Stopping Everything

When you are done, press Ctrl + C in both terminals.

The next time you want to edit content, run both commands again.

Next Steps

If you want to deploy and use the CMS online, continue to Deploy to Netlify.