Deploy to Netlify

This is the complete guide to deploying BlazorForge to Netlify and enabling Decap CMS online editing. Every step is covered, from creating a GitHub account to editing your first article through the browser.

Follow the steps in order. Do not skip ahead.

Overview

After completing this guide, you will have a live BlazorForge site on Netlify with a working content management system. Editors will log in through Netlify Identity, changes will commit to GitHub through Git Gateway, and Netlify will rebuild automatically.

The only change needed to switch between local and online mode is a single line in config.yml.

Requirements

A computer with a terminal. Windows, macOS, or Linux.

Git installed on your computer. Check with git --version. If missing, install from https://git-scm.com.

A .NET 9 SDK for local testing. Check with dotnet --version. If missing, see Requirements.

A GitHub account. If you do not have one, create it in Step 1.

A Netlify account. You will create it in Step 4.

Step 1: Create a GitHub Account

If you already have a GitHub account, skip to Step 2.

Open your browser and go to https://github.com.

Click Sign up in the top-right corner.

Fill in your email address, a password, and a username. The username will be public, so choose carefully.

Solve the puzzle captcha.

Click Create account.

GitHub sends a verification code to your email. Enter it.

On the welcome screen, you can skip the personalization steps. They are optional.

Your GitHub account is ready.

Step 2: Install and Configure Git

If Git is already installed, verify it with git --version and skip to the configuration part below.

If Git is not installed, download it from https://git-scm.com/downloads. Follow the installer for your operating system. On Windows, accept the default options.

After installation, open a new terminal and verify:

git --version

You should see a version number like git version 2.43.0.

Now configure Git with your identity. Run these two commands, replacing the values with your own:

git config --global user.name "Your Name"
git config --global user.email "your-email@example.com"

Use the same email address you used for GitHub.

Verify the configuration:

git config --global --list

You should see your name and email listed.

Step 3: Push the Project to GitHub

Open a terminal in the BlazorForge folder.

If you are on Windows, open File Explorer, navigate to the folder, click the address bar, type cmd, and press Enter.

If you are on macOS or Linux, open Terminal, type cd with a space, drag the BlazorForge folder into the terminal, and press Enter.

Initialize Git in the project:

git init

Add all files to the staging area:

git add .

Create the first commit:

git commit -m "Initial commit"

Rename the branch to main:

git branch -M main

Now create a repository on GitHub.

Open https://github.com/new in your browser.

Enter the repository name: blazorforge.

Leave the description blank.

Choose Public. Netlify free plan requires public repositories.

Do not check Initialize this repository with a README.

Click Create repository.

GitHub shows a page with setup instructions. Find the section titled “or push an existing repository from the command line”.

Copy the two commands shown. They will look like:

git remote add origin https://github.com/your-username/blazorforge.git
git push -u origin main

Run them in your terminal one at a time. Replace your-username if needed.

Git may ask for your GitHub username and password.

If you have two-factor authentication enabled, your password will not work. You need a Personal Access Token.

Step 3a: Create a Personal Access Token (If Needed)

If Git asks for a password and rejects it, create a Personal Access Token.

Open https://github.com/settings/tokens in your browser.

Click Generate new token, then Generate new token (classic).

Give the token a name, for example: BlazorForge Deploy.

Set expiration to 90 days.

Under scopes, check repo and workflow.

Click Generate token.

Copy the token immediately. You will not see it again.

When Git asks for your password, paste the token instead.

Step 4: Create a Netlify Account

Open your browser and go to https://netlify.com.

Click Sign up in the top-right corner.

Click Sign up with GitHub.

Authorize Netlify to access your GitHub account when prompted.

You now have a Netlify account.

Step 5: Create a New Netlify Site

In the Netlify dashboard, click Add new site.

Choose Import an existing project.

Click Deploy with GitHub.

If prompted, authorize Netlify to access your repositories.

A list of your repositories appears. Select blazorforge.

Netlify reads netlify.toml from your repository and pre-fills the build settings automatically.

Verify the settings:

Build command: chmod +x build.sh && ./build.sh

Publish directory: publish/wwwroot

If these values are correct, click Deploy site.

If they are not, enter them manually.

Step 6: Wait for the First Build

Netlify starts the first build. The process takes three to five minutes because the build agent must download and install the .NET 9 SDK.

You can watch the build log in the Netlify dashboard. Each step is logged.

When the build finishes, Netlify shows a URL like:

https://amazing-cat-12345.netlify.app

Click the URL. Your BlazorForge site is now live on the internet.

Step 7: Enable Netlify Identity

From your Netlify site dashboard, click Site configuration in the top navigation.

In the left sidebar, click Identity.

Click Enable Identity.

Netlify Identity provides user authentication for Decap CMS.

Step 8: Set Registration to Invite Only

Still on the Identity page, scroll down to Registration.

Click Edit settings.

Set Registration preferences to Invite only.

Click Save.

This prevents strangers from signing up to your CMS.

Step 9: Enable Git Gateway

On the same Identity page, scroll down to Services.

Find Git Gateway.

Click Enable Git Gateway.

Authorize Netlify to access your GitHub repository when prompted.

Git Gateway lets Decap CMS commit changes to GitHub on behalf of your users, without requiring each user to have a GitHub account.

Step 10: Invite Yourself as an Admin

On the Identity page, click Invite users.

Enter the email address you want to use for CMS login.

Click Send.

Check your email inbox. You will receive an invitation from Netlify.

Click the link in the email.

Set a password for your account.

You are now registered as an admin user.

Step 11: Change config.yml for Online Mode

This is the only change required to switch BlazorForge from local mode to online mode.

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

If the file starts with local_backend: true, change it to local_backend: false.

If the file does not contain a local_backend line, add local_backend: false as the first line.

The top of the file should now look like this:

local_backend: false

backend:
  name: git-gateway
  branch: main

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

publish_mode: editorial_workflow

collections:
  # ... the rest of the file remains the same

Save the file.

Commit and push the change:

git add wwwroot/admin/config.yml
git commit -m "Enable online mode for Decap CMS"
git push

Netlify detects the new commit and rebuilds automatically. Wait two to three minutes.

Step 12: Verify the Admin HTML

Open wwwroot/admin/index.html with a text editor.

Verify that the file contains the Netlify Identity widget script inside the head section:

<script src="https://identity.netlify.com/v1/netlify-identity-widget.js"></script>

Verify that the file contains this script at the end of the body, just before the closing body tag:

<script>
  if (window.netlifyIdentity) {
    window.netlifyIdentity.on("init", user => {
      if (!user) {
        window.netlifyIdentity.on("login", () => {
          document.location.href = "/admin/";
        });
      }
    });
  }
</script>

The first script loads the Netlify Identity widget. The second script redirects the user back to the CMS after login.

If either script is missing, add it. Save the file.

Commit and push:

git add wwwroot/admin/index.html
git commit -m "Verify Netlify Identity widget"
git push

Step 13: Log In to the Online CMS

Open your Netlify site URL with /admin/ at the end:

https://your-site-name.netlify.app/admin/

The Decap CMS login screen appears.

Click Login with Netlify Identity.

Enter the email and password you set in Step 10.

Click Log in.

The Decap CMS dashboard opens.

Step 14: Explore the CMS

The left sidebar shows your content collections.

Under Pages you will find Home Page, About Page, Contact Page, Journal Index Page, and Services Index Page.

Under Engineering Journal you will find all journal articles.

Under Themes & Services you will find all service pages.

Under Site Settings you will find Site Identity, SEO Settings, Navigation, Footer, and Global Widgets.

Click any item to open the editor.

Step 15: Edit Your First Content

Click Pages in the sidebar.

Click Home Page.

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

Change any field. For example, change the hero title.

Click Save in the top-right corner.

The change is saved to wwwroot/content/home.md in your GitHub repository.

Netlify rebuilds the site automatically. Wait two to three minutes.

Refresh the live site. Your change is visible.

Step 16: Create a Journal Article

Click Engineering Journal in the sidebar.

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 finished.

The article is saved to wwwroot/content/journal/ in your GitHub repository.

Netlify rebuilds and the article appears on the site.

Step 17: Upload 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/ in your GitHub repository.

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 means the content is not yet published. In Review means the content is ready for review. Ready means the content is published.

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

How the Workflow Works Behind the Scenes

When you edit content in the online CMS, the following happens automatically.

Decap CMS sends the change to Netlify Identity. Netlify Identity verifies your login. Git Gateway commits the change to your GitHub repository. Netlify detects the new commit. Netlify rebuilds the site. The changes are live within two to five minutes.

No manual commands are needed.

Switching Back to Local Mode

When you want to work locally, change local_backend: false back to local_backend: true in config.yml.

Open two terminals. In the first, run npx decap-server. In the second, run dotnet run.

Open http://localhost:5052/admin/. No login is required in local mode.

Adding Other Editors

To add more users to the CMS, open the Netlify dashboard and navigate to Site configuration, then Identity, then Invite users.

Enter the email address of the editor. Click Send.

They receive an invitation email. Once they accept it and set a password, they can log in at https://your-site-name.netlify.app/admin/.

Each editor can create and modify content. Only admins can invite other users.

Troubleshooting

If the Netlify build fails with dotnet: command not found, verify that build.sh exists in the project root and that netlify.toml uses chmod +x build.sh && ./build.sh as the build command.

If the build fails with MSB3073, verify that BlazorForge.csproj contains the DotNetExe property group inside the CompileMarkdownContent target.

If the build succeeds but the site shows 404 on refresh, verify that netlify.toml contains the redirect rule from = "/*" to = "/index.html" status = 200.

If the CMS login page shows a blank white screen, verify that the Netlify Identity widget script is loaded in wwwroot/admin/index.html.

If login fails with User not confirmed, check your email for the invitation link and click it.

If you see Git Gateway Error when saving content, make sure Git Gateway is enabled in the Identity settings and that your user has the admin role.

If changes do not appear on the live site, wait two to five minutes. Check the Deploys tab in Netlify for a running build.

If the CMS says Not Found, verify that the URL ends with a trailing slash: /admin/.

Summary

After completing this guide, you have a live BlazorForge site on Netlify with online Decap CMS. Editors log in through Netlify Identity. Changes commit to GitHub through Git Gateway. Netlify rebuilds automatically.

The only change needed to switch between local and online mode is the local_backend line in config.yml.

Next Steps

To customize the theme after deploying, see Customization.

For common questions, see FAQ.