Developer Guide
This Developer Guide is for developers who want to understand how BlazorForge works internally, modify the source code, or extend the theme with new features.
If you are looking for installation and deployment instructions, see the User Guide instead.
What This Guide Covers
Section titled “What This Guide Covers”The Developer Guide covers the technical architecture of BlazorForge.
The Architecture Overview explains how the different parts of the project fit together.
The Folder Structure section explains what each folder contains and why.
The Tech Stack section lists the frameworks, libraries, and tools used.
The Models section documents the C# classes that represent content.
The Services section explains the business logic layer.
The Components section documents the Razor components.
The Markdown Compiler section explains how Markdown becomes JSON.
The SEO System section explains how meta tags and structured data are generated.
The Decap CMS Config section explains the CMS configuration.
The Extending section shows how to add new pages, components, and collections.
The Contributing section explains how to contribute improvements back.
Who This Guide Is For
Section titled “Who This Guide Is For”This guide assumes you know C#, Razor, and basic .NET concepts. If you are new to Blazor, read the User Guide first.
You should be comfortable with:
C# and .NET 9.
Razor components and Blazor rendering.
Basic Markdown and YAML syntax.
Git and version control.
Project Overview
Section titled “Project Overview”BlazorForge is a Blazor WebAssembly application. It renders pages on the client using Razor components. Content is stored as Markdown and JSON files. A small C# console tool compiles the Markdown into JSON metadata that the Blazor app reads at runtime.
The architecture has four main layers.
The content layer contains Markdown files in wwwroot/content/ and JSON files in wwwroot/data/.
The compile layer is a .NET console application in Tools/ that reads the Markdown and writes JSON metadata to wwwroot/metadata/.
The application layer is the Blazor WebAssembly app itself, with Razor pages in Pages/, reusable components in Shared/, and shared layout in Layout/.
The service layer contains the C# classes in Services/ that load data, generate SEO tags, and orchestrate everything.
How the Pieces Fit Together
Section titled “How the Pieces Fit Together”When you run dotnet run, the following sequence happens.
The MSBuild target CompileMarkdownContent runs before the build. It calls the Tools project, which reads every Markdown file in wwwroot/content/ and writes JSON metadata files to wwwroot/metadata/. It also generates sitemap.xml, feed.xml, and robots.txt in wwwroot/.
The Blazor project builds. The compiler bundles all the Razor components and C# code into a WebAssembly application.
The development server starts on port 5052.
When you open the browser, the Blazor WebAssembly app boots. It reads data/site.json, data/seo.json, data/navbar.json, data/footer.json, and data/widget.json through ConfigService. It reads the compiled metadata through MarkdownService. It sets SEO tags through SeoService.
Each page is a Razor component with a @page directive. The router in App.razor matches the current URL to a page component. The page component loads its data, sets SEO, and renders the UI.
Design Principles
Section titled “Design Principles”BlazorForge follows four design principles.
First, content is separate from code. All text, images, navigation, and configuration live in Markdown and JSON files. Changing content never requires changing C#.
Second, everything is data-driven. The UI reads from config and metadata. No content is hardcoded in Razor components.
Third, the theme uses pure C#. There is no JavaScript framework, no npm dependency, and no TypeScript compilation. Everything compiles with dotnet build.
Fourth, the theme is accessible by default. Every component uses semantic HTML, ARIA labels, keyboard navigation, and focus management. WCAG 2.1 AA compliance is built in.
How to Read This Guide
Section titled “How to Read This Guide”If you are new to the project, read the sections in order. Start with Architecture Overview, then Folder Structure, then Tech Stack.
If you are looking for a specific topic, jump directly to the relevant section.
If you want to extend the theme, start with Extending BlazorForge and refer to the other sections as needed.