Getting Started

**Referenced Files in This Document** - [package.json](file://package.json) - [README.md](file://README.md) - [.eleventy.js](file://.eleventy.js) - [cloudflare-pages.toml](file://cloudflare-pages.toml) - [wrangler.jsonc](file://wrangler.jsonc) - [worker.js](file://worker.js) - [src/admin/config.yml](file://src/admin/config.yml) - [src/admin/index.html](file://src/admin/index.html) - [src/_data/site.json](file://src/_data/site.json) - [src/content/news/2025-10-17-political-powerhouse.md](file://src/content/news/2025-10-17-political-powerhouse.md) - [netlify.toml](file://netlify.toml) - [tina/config.ts](file://tina/config.ts)

Table of Contents

  1. Introduction
  2. Prerequisites
  3. Installation
  4. Development Workflow
  5. Project Structure Overview
  6. Content Editing Guide
  7. Asset Management
  8. Testing and Verification
  9. Deployment
  10. Troubleshooting
  11. Quick Start Examples
  12. Conclusion

Introduction

This guide helps developers and content editors set up the Ace Strategies platform locally, understand the project structure, and manage content efficiently. The platform is built with Eleventy, hosted on Cloudflare Workers, and includes a Git-backed CMS for content management.

Prerequisites

Before installing, ensure your environment meets the following requirements:

  • Node.js: Version 18 or higher
  • npm: Version 9 or higher
  • Wrangler CLI: Installed and authenticated (wrangler login)
  • A Cloudflare account with Workers enabled

These requirements are documented in the project’s README and enforced by the package configuration.

Section sources

  • [README.md:47-53](file://README.md#L47-L53)
  • [package.json:22-24](file://package.json#L22-L24)

Installation

Follow these steps to install and prepare the project locally:

  1. Clone the repository and navigate into the project directory.
  2. Install dependencies:
    npm install
  3. Start the local development server:
    • Eleventy-only dev server:
      npm start
      • Open http://localhost:8080 in your browser.
    • Dev server with CMS:
      npm run dev:cms
      • Site: http://localhost:8080
      • CMS: http://localhost:4001

Notes:

  • The CMS entry point is served from the admin directory and is configured in the Eleventy configuration.
  • The CMS schema defines collections and fields for content editing.

Section sources

  • [README.md:56-76](file://README.md#L56-L76)
  • [.eleventy.js:7-13](file://.eleventy.js#L7-L13)
  • [src/admin/index.html:1-12](file://src/admin/index.html#L1-L12)
  • [src/admin/config.yml:1-10](file://src/admin/config.yml#L1-L10)

Development Workflow

The typical development workflow includes:

  • Running the Eleventy dev server for local preview.
  • Using the CMS for content editing when needed.
  • Building for production and previewing locally via Wrangler.
  • Deploying to Cloudflare Workers.

Key commands:

  • Start Eleventy dev server:
    npm start
  • Start CMS dev server:
    npm run dev:cms
  • Build for production:
    npm run build
  • Preview production build locally:
    npm run preview

Build output:

  • Eleventy generates the static site under _site/.
  • Pagefind adds a search index under _site/pagefind/.
  • The CMS admin is included in _site/admin/.

Section sources

  • [README.md:160-171](file://README.md#L160-L171)
  • [package.json:5-12](file://package.json#L5-L12)
  • [README.md:556-586](file://README.md#L556-L586)

Project Structure Overview

The repository is organized as follows:

  • src/: Source files for Eleventy (templates, content, data, assets, admin)
    • _data/: Global data files available to all templates
    • _includes/: Nunjucks layouts and macros
    • content/: Markdown content collections (news, cases, team, knowledge, newsletters, services)
    • assets/: CSS, JS, and media repositories
    • admin/: CMS entry point and configuration
    • legal/, services/, and top-level templates for pages
  • tina/: TinaCMS configuration (local-only)
  • Root configuration files:
    • .eleventy.js: Eleventy configuration
    • package.json: Scripts and dependencies
    • wrangler.jsonc: Cloudflare Workers configuration
    • cloudflare-pages.toml, netlify.toml: Legacy deployment configs

Key directories and files:

  • Eleventy configuration: .eleventy.js
  • CMS configuration: src/admin/config.yml
  • CMS entry point: src/admin/index.html
  • Site settings: src/_data/site.json
  • Example content: src/content/news/2025-10-17-political-powerhouse.md
  • Worker: worker.js
  • Wrangler config: wrangler.jsonc

Section sources

  • [README.md:80-156](file://README.md#L80-L156)
  • [.eleventy.js:267-283](file://.eleventy.js#L267-L283)

Content Editing Guide

The platform uses a Git-backed CMS. Editors can access the CMS at /admin/ and manage content directly in the repository.

Accessing the CMS:

  • Navigate to the CMS URL and sign in with GitHub.
  • The registered GitHub App ID and callback URL are configured in the CMS settings.

Collections available in the CMS:

  • News & Insights
  • Case Studies
  • Team Members
  • Knowledge Base
  • Newsletters
  • Site Settings
  • Testimonials
  • IAA Partners
  • Client Logos

CMS schema highlights:

  • Collections are defined in src/admin/config.yml.
  • Media uploads are stored under src/assets/repository/images/uploads.
  • Public URLs for uploaded media are mapped accordingly.

Editor workflow:

  • Make edits in the CMS.
  • Save and commit changes; the repository triggers a Cloudflare Workers rebuild.

Section sources

  • [README.md:174-204](file://README.md#L174-L204)
  • [src/admin/config.yml:11-105](file://src/admin/config.yml#L11-L105)
  • [src/admin/config.yml:106-774](file://src/admin/config.yml#L106-L774)
  • [src/admin/index.html:1-12](file://src/admin/index.html#L1-L12)

Asset Management

Assets are organized under src/assets/:

  • CSS: Stylesheets and modules
  • JS: Client-side scripts and modules
  • Repository: Images and uploads for clients, team, UI, and CMS/Obsidian uploads

Static assets are passed through to the build output via Eleventy configuration. Media uploads for the CMS are stored under src/assets/repository/images/uploads.

Obsidian knowledge base:

  • The repository acts as an Obsidian vault.
  • New notes are created in src/content/knowledge/.
  • Attachments are placed under src/assets/repository/images/uploads/.

Section sources

  • [.eleventy.js:7-14](file://.eleventy.js#L7-L14)
  • [README.md:373-422](file://README.md#L373-L422)

Testing and Verification

Verification steps to confirm a successful local setup:

  • Confirm the dev server is running and accessible at http://localhost:8080.
  • Verify CMS dev server at http://localhost:4001 (when using npm run dev:cms).
  • Build the project and inspect the output in _site/.
  • Preview production build locally via Wrangler:
    npm run preview

Common checks:

  • Ensure Node.js and npm versions meet the project requirements.
  • Confirm Wrangler CLI is installed and authenticated.
  • Validate that Eleventy configuration paths align with the project structure.

Section sources

  • [README.md:56-76](file://README.md#L56-L76)
  • [README.md:556-586](file://README.md#L556-L586)
  • [package.json:22-24](file://package.json#L22-L24)

Deployment

The platform deploys to Cloudflare Workers. The canonical deployment uses Wrangler to upload the static site and the Worker.

Manual deployment:

npm run deploy

Continuous deployment:

  • Cloudflare Workers Builds is connected to the repository.
  • Pushing to main updates the production site.
  • Branch pushes create previews at {branch}-aces-prime.kami-rostami-design.workers.dev.

Cloudflare setup:

  • Authenticate Wrangler and create KV namespaces for member authentication.
  • Set secrets for session management, email service, and external APIs.
  • Configure custom domains in the Cloudflare dashboard.

Build output:

  • _site/: Static site
  • _site/admin/: CMS interface
  • _site/pagefind/: Search index and WASM

Section sources

  • [README.md:556-586](file://README.md#L556-L586)
  • [README.md:523-548](file://README.md#L523-L548)
  • [wrangler.jsonc:1-35](file://wrangler.jsonc#L1-L35)
  • [cloudflare-pages.toml:1-17](file://cloudflare-pages.toml#L1-L17)
  • [netlify.toml:1-26](file://netlify.toml#L1-L26)

Troubleshooting

Common setup issues and resolutions:

  • Node.js/npm version mismatch:
    • Ensure Node.js ≥ 18 and npm ≥ 9.
  • Wrangler authentication:
    • Run wrangler login and verify access to your Cloudflare account.
  • Missing CMS secrets (optional):
    • For local TinaCMS builds, set TINA_PUBLIC_CLIENT_ID and TINA_TOKEN if needed.
  • Contact form placeholder:
    • Replace the Web3Forms access key placeholder in the site settings before enabling the form.
  • Member authentication KV namespaces:
    • Create and bind KV namespaces for member emails and magic tokens in Wrangler configuration.
  • Polling data secrets:
    • Set Google Sheets ID and API key secrets for live polling data.

Verification steps:

  • Confirm the dev server runs without errors.
  • Check that the CMS loads and allows editing.
  • Validate that the build completes and produces _site/ with expected assets.

Section sources

  • [README.md:47-53](file://README.md#L47-L53)
  • [README.md:497-520](file://README.md#L497-L520)
  • [README.md:523-548](file://README.md#L523-L548)
  • [README.md:656-665](file://README.md#L656-L665)
  • [src/_data/site.json:14](file://src/_data/site.json#L14)

Quick Start Examples

Making content changes:

  • Add a new news article:
    • Create a new Markdown file in src/content/news/ with frontmatter fields (title, date, author, excerpt, image, etc.).
    • Commit and push; the site rebuilds automatically.
  • Edit site settings:
    • Update src/_data/site.json via the CMS or directly in the repository.
  • Manage testimonials and IAA partners:
    • Use the CMS collections “Testimonials” and “IAA Partners” to update lists.

Testing the development environment:

  • Start the dev server:
    npm start
  • Open http://localhost:8080 and verify the homepage and content pages load.
  • Start the CMS dev server:
    npm run dev:cms
  • Open http://localhost:4001 and confirm the CMS interface and collections.

Section sources

  • [README.md:56-76](file://README.md#L56-L76)
  • [src/content/news/2025-10-17-political-powerhouse.md:1-18](file://src/content/news/2025-10-17-political-powerhouse.md#L1-L18)
  • [src/admin/config.yml:11-105](file://src/admin/config.yml#L11-L105)

Conclusion

You are now ready to develop and edit content for the Ace Strategies platform. Use the Eleventy dev server for rapid iteration, the CMS for content management, and Wrangler for production deployments. Refer to the project’s README for detailed configuration and troubleshooting guidance.