From ZIP to Running Site

In the previous chapter you downloaded Dax Pro from Gumroad, installed the .NET 9 SDK, and extracted the project ZIP. The project files exist on your machine — but they are just text. Nothing has compiled them yet.

This chapter turns those files into a running website. It walks through:

1. Creating a clean project folder — where to put Dax Pro and why location matters

2. Opening the project in a terminal — how to navigate there in Windows, Linux, and macOS

3. Running the first build — dotnet run -- build and what it produces

4. Starting the local development server — dotnet run -- start and what it serves

5. Running Decap CMS locally — the two-terminal pattern that makes local editing work

6. Deciding between local and cloud — why you should build locally first and deploy later

Read every step. Installation problems in static site generators almost always come from skipping steps or from running commands in the wrong directory.

---

Step 1 — Create a Clean Project Folder

Before running anything, decide where the project lives. The location matters for two reasons.

First, the path must not contain spaces. The .NET CLI and many static site tools break when the working directory has spaces in its path. C:\Users\John\My Projects\dax pro will cause inexplicable failures. C:\Users\John\Projects\dax-pro will work every time.

Second, the path must not be inside a synchronized cloud folder (iCloud Drive, OneDrive, Dropbox, Google Drive). These services sometimes modify files during a build or lock them, both of which cause intermittent build failures that are hard to diagnose.

Creating the folder on Windows

1. Open File Explorer

2. Navigate to your user directory: C:\Users\YourName

3. Right-click in the empty space and choose New → Folder

4. Name it Projects (no spaces, no accents)

5. Double-click to enter Projects

6. Right-click inside and choose New → Folder

7. Name it dax-pro

8. You should now have C:\Users\YourName\Projects\dax-pro

Move the extracted Dax Pro files into this folder. If you extracted the ZIP directly to Downloads\dax-pro, you have two options:

• Option A: Move the whole dax-pro folder into C:\Users\YourName\Projects\
• Option B: Delete the extracted folder from Downloads and re-extract the ZIP directly into C:\Users\YourName\Projects\

The end state should be:

C:\Users\YourName\Projects\dax-pro\
├── _data\
├── content\
├── templates\
├── public\
├── Dax.csproj
├── Program.cs
├── README.md
├── LICENSE
└── netlify.toml

Creating the folder on Linux

mkdir -p ~/projects/dax-pro
cd ~/projects/dax-pro

Move the extracted files into ~/projects/dax-pro:

unzip ~/Downloads/dax-pro-v1.0.zip -d ~/projects/

After extraction, the project lives at ~/projects/dax-pro/. Confirm:

ls -la ~/projects/dax-pro/

Creating the folder on macOS

mkdir -p ~/Projects/dax-pro
cd ~/Projects/dax-pro

Move the extracted files into ~/Projects/dax-pro. macOS folder names are case-insensitive by default, so Projects and projects are the same folder. That is fine.

Confirm the contents:

ls -la ~/Projects/dax-pro/

---

Step 2 — Open a Terminal in the Project Folder

Every command in the rest of this chapter assumes you are inside the dax-pro directory. If you are not in the right directory, dotnet run will look for Dax.csproj in the wrong place and fail with a confusing error.

Opening a terminal on Windows

The easiest way is through File Explorer:

1. Open File Explorer

2. Navigate to C:\Users\YourName\Projects\dax-pro

3. Click the address bar at the top

4. Type cmd and press Enter

A Command Prompt opens at that folder. You will see the folder path at the top of the window.

Alternatively, use PowerShell:

1. In File Explorer, navigate to the project folder

2. Right-click in the empty space

3. Choose Open in Terminal (Windows 11) or Open PowerShell window here (Windows 10)

To confirm you are in the right place, run:

dir

You should see _data, content, templates, public, Program.cs, Dax.csproj, and the other project files.

Opening a terminal on Linux

cd ~/projects/dax-pro
pwd

pwd should print /home/YourName/projects/dax-pro. Confirm contents with:

ls

Opening a terminal on macOS

cd ~/Projects/dax-pro
pwd

pwd should print /Users/YourName/Projects/dax-pro. Confirm:

ls

Opening the project in VS Code (recommended)

If you are using VS Code, skip the terminal navigation entirely. From the project folder:

code .

On Windows, this works if you installed VS Code with the "Add to PATH" option (the default). On macOS, you may need to install the code command first by opening VS Code, pressing Cmd + Shift + P, and choosing Shell Command: Install 'code' command in PATH.

Once VS Code is open, press ` Ctrl + ` (Windows/Linux) or Cmd + ` (macOS) to open the integrated terminal. It opens in the project directory automatically.

---

Step 3 — Run the First Build

The first build compiles the DAX engine (C#), reads your content and data files, applies templates, and writes static HTML to the site/ folder.

In your terminal, run:

dotnet run -- build

The first run will take 30–90 seconds because the SDK downloads NuGet packages and compiles the C# project. Subsequent builds take about one second.

You will see output like this:

D.A.X - Dotnet by AXcora

[DAX] build start...
[DAX] loaded yaml: config
[DAX] loaded yaml: footer
[DAX] loaded yaml: metadata
[DAX] loaded yaml: nav
[DAX] built 49 pages to /site - collections: posts,services - tags: 31
[DAX] built at 20/10/2026 15.40.23

The critical line is:

[DAX] built 49 pages to /site - collections: posts,services - tags: 31

This tells you:

• 49 pages were generated
• They were written to the /site folder
• Two collections were detected: posts and services
• 31 tags were indexed from your content

If the numbers differ on your machine, that is expected — your content is different from the demo content. What matters is that the build succeeded without errors.

What the Build Produces

Open the site/ folder in your file browser or in VS Code. You will see:

site/
├── index.html              ← the homepage
├── about/
│   └── index.html          ← /about/
├── contact/
│   └── index.html          ← /contact/
├── posts/
│   ├── index.html          ← /posts/ list
│   └── dax-pro-vs-blazor-wasm/
│       └── index.html      ← /posts/dax-pro-vs-blazor-wasm/
├── services/
│   └── index.html          ← /services/ list
├── tags/
│   └── index.html          ← /tags/ index
├── css/
│   └── style.css           ← copied from public/css/
├── js/
│   └── main.js             ← copied from public/js/
├── images/
│   └── (your images)       ← copied from public/images/
├── admin/
│   ├── index.html          ← Decap CMS entry
│   ├── config.yml          ← Decap CMS collections
│   └── daxlogo.webp        ← Decap logo
├── sitemap.xml             ← auto-generated
├── robots.txt              ← auto-generated
└── rss.xml                 ← auto-generated

Every folder with an index.html inside is a URL path. /posts/dax-pro-vs-blazor-wasm/index.html becomes https://yoursite.com/posts/dax-pro-vs-blazor-wasm/.

The site/ folder is the final output. This is what you upload to a static host. During development, this folder is regenerated every time you change content, templates, or data.

If the Build Fails

Common errors and their causes:

MSBUILD : error MSB1009: Project file does not exist.

You are not in the dax-pro directory. Run cd to the correct folder and try again.

error CS0246: The type or namespace name 'X' could not be found.

A template file is missing or malformed. Check templates/ and confirm all files are present.

[BUILD ERROR] Object reference not set to an instance of an object.

A YAML file or Markdown frontmatter has a structural problem. Check _data/.yaml and content/.md for missing quotes, mismatched indentation, or Windows line endings.

UnauthorizedAccessException: Access to the path 'site/...' is denied.

Another program (often a file explorer or editor preview) is locking a file. Close it and try again.

Build hangs for 30+ seconds on the first run

The SDK is downloading NuGet packages. This is normal and happens only once. Wait for it to complete.

---

Step 4 — Start the Local Development Server

Once the build succeeds, you can start a local web server to preview your site. Run:

dotnet run -- start

The first time you run this, the DAX engine runs a build first (if necessary), then starts an HTTP server. You will see:

[DAX] serving at http://localhost:8080/

Open a browser and navigate to:

http://localhost:8080/

You will see your Dax Pro homepage. Click through the navigation, open a blog post, load /services/, submit the contact form — everything should work exactly as it will in production.

How the Development Server Works

The dotnet run -- start command starts a lightweight HTTP server on port 8080. It serves files from the site/ folder. It also starts a file watcher — every time you save a change to a .md, .dax, .yaml, or .css file, the server automatically rebuilds and the browser reflects the change when you refresh.

You do not need to restart the server after editing content or templates. Save the file, refresh the browser, see the change.

The server output shows rebuild events:

[DAX] changed posts.md -> rebuild
[DAX] built 49 pages to /site - collections: posts,services - tags: 31

Stopping the Server

Press Ctrl + C in the terminal. The server stops immediately. To restart it later, run dotnet run -- start again.

Changing the Port

If port 8080 is already in use (uncommon but possible), you can stop the conflicting process or edit Program.cs to use a different port. For most users, port 8080 is available by default.

---

Step 5 — Running Decap CMS Locally

Decap CMS is an editorial interface. When you open /admin/ in your browser, it loads a React application that lets you edit content through forms. Each save writes a Markdown or YAML file back into your project.

This means Decap CMS needs two things running simultaneously:

1. The Dax Pro development server — so the browser can load /admin/ and you can preview content

2. The Decap CMS proxy server — so the editorial interface can write files to your local project

Without the proxy server, Decap CMS will open in your browser but cannot save changes. You will see an error like "Failed to persist entry" when you click Publish.

The Two-Terminal Pattern

To use Decap CMS locally, you need two terminal windows running simultaneously.

Terminal 1 — the Dax Pro development server:

cd ~/Projects/dax-pro       # or your project path
dotnet run -- start

Leave this terminal running. It serves the site at http://localhost:8080/.

Terminal 2 — the Decap CMS proxy server:

cd ~/Projects/dax-pro
npx decap-server

This starts a lightweight local server that Decap CMS uses to write files to your filesystem. It listens on port 8081 by default.

If you do not have Node.js installed, you have two options:

• Option A: Install Node.js from nodejs.org, then run npx decap-server
• Option B: Skip Decap CMS locally. Edit Markdown files directly in VS Code. Deploy to the cloud, and use Decap CMS from the deployed site later (see below).

Opening the Editor

With both terminals running:

1. Open a browser

2. Navigate to http://localhost:8080/admin/

3. You will see the Decap CMS login screen

4. Click Login — because local_backend: true is set in config.yml, Decap CMS connects to the proxy server running in Terminal 2

5. You are now in the editorial interface

You can edit any collection: homepage, navbar, footer, posts, services, pages, contact. Every save writes back to the file system in your project folder. The development server detects the change and rebuilds automatically.

To verify: edit the site title in ⚙ Settings → Site Metadata, click Publish, wait two seconds, refresh http://localhost:8080/. The new title appears.

Closing the Local Session

When you are done editing:

1. Press Ctrl + C in Terminal 2 to stop the Decap CMS proxy

2. Press Ctrl + C in Terminal 1 to stop the development server

Your changes are saved to the project files. They will be included in the next build.

If You Skip Decap Locally

You do not have to run Decap CMS during development. You can edit Markdown and YAML files directly in VS Code. The development server rebuilds automatically on save.

The choice depends on your workflow:

Workflow	When to use
Edit Markdown directly	Solo developer, comfortable with YAML
Run Decap CMS locally	Team with editors who need a visual interface
Edit locally, Decap in cloud	Recommended for most projects (see next section)

---

Step 6 — Local First, Cloud Later

This is the most important architectural recommendation in the entire documentation. Read it carefully.

Build and validate your site entirely locally before touching any cloud service.

The reason is simple: cloud deployment adds an entire layer of potential failure — DNS, build pipeline, Git authentication, CMS authentication, environment variables — none of which you can debug if the local build itself is broken. If you deploy to the cloud before your local build works, every problem becomes two problems, and you cannot tell whether the cause is your project or the cloud configuration.

The recommended workflow is:

Phase 1 — Local Development

1. Install the SDK and unpack Dax Pro (previous chapter)

2. Run dotnet run -- build and confirm it succeeds

3. Run dotnet run -- start and preview the site at http://localhost:8080/

4. Edit content, tweak _data/*.yaml, change the CSS — all locally

5. Verify every page renders correctly, every link works, every image loads

6. If you plan to use Decap CMS, run the two-terminal pattern and test one save

7. Only when the site looks exactly how you want it locally — proceed to Phase 2

Phase 2 — Cloud Deployment

1. Push the project to a Git repository (GitHub, GitLab, or Azure Repos)

2. Connect the repository to Netlify, Vercel, or Azure Static Web Apps

3. The cloud service builds your site using the same dotnet run -- build command

4. Configure Decap CMS with Netlify Identity or Git Gateway

5. Invite editors via the cloud dashboard

6. Done

This order prevents the classic failure mode where a user deploys to Netlify on day one, hits a build error, and spends three days debugging whether the problem is their YAML, their Netlify configuration, or their Decap CMS authentication. By validating locally first, you eliminate half of those variables.

What About Decap CMS in the Cloud?

You can configure Decap CMS locally (as described in Step 5). But for most projects, the local Decap setup is unnecessary friction. Here is the pragmatic approach:

• During development: edit files directly in VS Code. Do not run the Decap proxy. You do not need a visual editor while you are building the site.
• When the site is ready and deployed: configure Decap CMS in the cloud (Netlify Identity or Git Gateway). Editors log in at https://yoursite.com/admin/. They commit changes. Netlify rebuilds. Everything works.

This means you only need to run one terminal during development (dotnet run -- start). You do not need Node.js. You do not need npx decap-server. You do not need two terminals.

The local Decap setup exists for teams that want to test the editorial workflow before deploying. If you are a solo developer or a small team, skip it.

The Cloud-First Path — When It Makes Sense

There is exactly one situation where cloud-first makes sense: when you are deploying a site whose content is entirely managed by a non-technical editor from day one.

Example: a marketing team has purchased Dax Pro, hired you to build the site, and wants to start writing content through a CMS interface immediately. In that case, you would:

1. Build the site structure locally (theme, layout, pages)

2. Deploy to Netlify

3. Configure Decap CMS in the cloud

4. Invite the editor

5. The editor writes content via Decap; every save triggers a cloud rebuild

Note that even in this scenario, the theme and layout were still built locally. Only the content editing happens in the cloud. The distinction is: build locally, edit in the cloud. Never build in the cloud before building locally.

A Warning About Repeated Cloud Rebuilds

If you configure Decap CMS in the cloud and then continue making structural changes (theme, layout, data files) locally, every local change you push to Git will trigger a cloud rebuild. This is fine for a few changes, but it becomes slow and expensive if you are making hundreds of small commits.

The recommended rhythm:

1. Development phase: all structural work locally, no Decap, no cloud rebuilds

2. Content phase: site is deployed, Decap configured, editors write content, cloud rebuilds on every save

3. Maintenance phase: rare structural changes are made locally, tested locally, then pushed to Git once — one cloud rebuild

Follow this rhythm and your cloud build minutes stay low.

---

Quick Reference — The Commands You Will Use

For day-to-day use, you only need these commands. Bookmark this section.

Build the site

dotnet run -- build

Produces site/. Use this when you want to generate the final output for deployment.

Start the development server

dotnet run -- start

Serves the site at http://localhost:8080/ and rebuilds on every file change.

Run Decap CMS locally (optional, two-terminal)

# Terminal 1
dotnet run -- start

Terminal 2
npx decap-server

Then open http://localhost:8080/admin/.

Stop the development server

Ctrl + C

Check the SDK version

dotnet --version

Should print 9.0.x.

Build and deploy to production

dotnet run -- build
Upload the site/ folder to your static host
Or push to Git and let Netlify/Vercel build automatically

---

What You Have Now

After completing this chapter, you have:

• ✅ A clean dax-pro project folder on your machine
• ✅ A successful build producing site/ with 40+ pages
• ✅ A running local development server at http://localhost:8080/
• ✅ A working preview of your full Dax Pro site
• ✅ (Optional) A working local Decap CMS editorial interface
• ✅ A clear workflow: build locally, edit in the cloud

The next chapter covers Configuration — editing metadata.yaml, nav.yaml, and footer.yaml` to match your brand, your navigation, and your footer structure.

If your build succeeded and the site looks correct in your browser, you are ready. If anything failed, re-read the section covering the failure — the answer is in this chapter, in the previous chapter, or in the troubleshooting section of the README.

→ Continue to Configuration